Makefile

@@ -27,7 +27,11 @@ endif
 
 .PHONY: lint
 lint: lint-prepare ## Run the golangci linter
-	golangci-lint run
+	./bin/golangci-lint run
+
+.PHONY: update
+update: ## Update all dependencies
+	go get -u ./... && go mod tidy
 
 .PHONY: tidy
 tidy: ## Remove unused dependencies

README.md

@@ -23,6 +23,7 @@ library will cut releases that will be tagged with v3.0.0, v3.0.1 etc, see the V
 ## Usage
 - [Authentication](./README.md#authentication)
 - [Resources](./README.md#resources)
+- [Filtering](./README.md#filtering)
 - [Pagination](./README.md#pagination)
 - [Asynchronous Jobs](./README.md#asynchronous-jobs)
 - [Error Handling](./README.md#error-handling)
@@ -82,6 +83,42 @@ __NOTE__ - Using the context package you can easily pass cancellation signals an
 for handling a request. In case there is no context available, then `context.Background()` can be used as a starting
 point.
 
+### Filtering
+This library should support all possible
+[filtering combinations that the CF API supports](https://v3-apidocs.cloudfoundry.org/version/3.188.0/index.html#filters),
+including those that may not be valid. While the library tries to steer you in a direction that won't allow for invalid
+combinations it's still possible to create filters that are nonsensical. The support matrix for filters:
+
+| Type | Multi-valued | Empty | Relational Op | Not |
+| --- | --- | --- | --- | --- |
+| Timestamp | x | | x | x |
+| String | x | x | | x |
+
+Full filtering example, find all apps with the name of spring-music:
+```go
+opts := client.NewAppListOptions()
+opts.Names.EqualTo("spring-music")
+apps, _ := cf.Applications.ListAll(context.Background(), opts)
+fmt.Printf("Found %d apps named spring-music\n", len(apps))
+```
+
+Find multiple applications with specific names:
+```go
+opts.Names.EqualTo("credit-processor-service", "credit-processor-ui")
+```
+
+Find all apps not named spring-music:
+```go
+opts.Names.NotEqualTo("spring-music")
+```
+
+Find all spring-music apps created within a date range:
+```go
+opts.Names.EqualTo("spring-music")
+opts.CreateAts.After(date1)
+opts.CreateAts.Before(date2)
+```
+
 ### Pagination
 All requests for resource collections (apps, orgs, spaces etc) support pagination. Pagination options are described
 in the client.ListOptions struct and passed to the list methods directly or as an embedded type of a more specific

client/app_features_test.go

@@ -9,7 +9,7 @@ import (
 )
 
 func TestAppFeatures(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(163)
+	g := testutil.NewObjectJSONGenerator()
 	appFeature := g.AppFeature().JSON
 
 	tests := []RouteTest{

client/app_test.go

@@ -11,7 +11,7 @@ import (
 )
 
 func TestApps(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(1)
+	g := testutil.NewObjectJSONGenerator()
 	app1 := g.Application().JSON
 	app2 := g.Application().JSON
 	app3 := g.Application().JSON

client/app_usage_test.go

@@ -9,7 +9,7 @@ import (
 )
 
 func TestAppUsages(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(161)
+	g := testutil.NewObjectJSONGenerator()
 	appUsage := g.AppUsage().JSON
 	appUsage2 := g.AppUsage().JSON
 	appUsage3 := g.AppUsage().JSON

client/audit_event_test.go

@@ -9,7 +9,7 @@ import (
 )
 
 func TestAuditEvents(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(161)
+	g := testutil.NewObjectJSONGenerator()
 	auditEvent := g.AuditEvent().JSON
 	auditEvent2 := g.AuditEvent().JSON
 	auditEvent3 := g.AuditEvent().JSON

client/build.go

@@ -138,12 +138,15 @@ func (c *BuildClient) ListForAppAll(ctx context.Context, appGUID string, opts *B
 
 // PollStaged waits until the build is staged, fails, or times out
 func (c *BuildClient) PollStaged(ctx context.Context, guid string, opts *PollingOptions) error {
-	return PollForStateOrTimeout(func() (string, error) {
+	return PollForStateOrTimeout(func() (string, string, error) {
 		build, err := c.Get(ctx, guid)
 		if build != nil {
-			return string(build.State), err
+			if build.Error != nil {
+				return string(build.State), *build.Error, err
+			}
+			return string(build.State), "", err
 		}
-		return "", err
+		return "", "", err
 	}, string(resource.BuildStateStaged), opts)
 }
 

client/build_test.go

@@ -10,7 +10,7 @@ import (
 )
 
 func TestBuilds(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(2)
+	g := testutil.NewObjectJSONGenerator()
 	build := g.Build("STAGED").JSON
 	build2 := g.Build("STAGED").JSON
 	build3 := g.Build("STAGED").JSON

client/buildpack_test.go

@@ -11,7 +11,7 @@ import (
 )
 
 func TestBuildpacks(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(1002)
+	g := testutil.NewObjectJSONGenerator()
 	buildpack := g.Buildpack().JSON
 	buildpack2 := g.Buildpack().JSON
 	buildpack3 := g.Buildpack().JSON

client/deployment.go

@@ -39,6 +39,7 @@ func (c *DeploymentClient) Cancel(ctx context.Context, guid string) error {
 }
 
 // Create a new deployment
+// Rolling restart can be triggered by passing in the app guid and existing droplet guid
 func (c *DeploymentClient) Create(ctx context.Context, r *resource.DeploymentCreate) (*resource.Deployment, error) {
 	// validate the params
 	if r.Droplet != nil && r.Revision != nil {

client/deployment_test.go

@@ -12,7 +12,7 @@ import (
 )
 
 func TestDeployments(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(4)
+	g := testutil.NewObjectJSONGenerator()
 	deployment := g.Deployment().JSON
 	deployment2 := g.Deployment().JSON
 	deployment3 := g.Deployment().JSON

client/domain_test.go

@@ -10,7 +10,7 @@ import (
 )
 
 func TestDomains(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(1)
+	g := testutil.NewObjectJSONGenerator()
 	domain := g.Domain().JSON
 	domain2 := g.Domain().JSON
 	domain3 := g.Domain().JSON

client/droplet_test.go

@@ -15,7 +15,7 @@ import (
 )
 
 func TestDroplets(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(2)
+	g := testutil.NewObjectJSONGenerator()
 	droplet := g.Droplet().JSON
 	droplet2 := g.Droplet().JSON
 	droplet3 := g.Droplet().JSON

client/envar_group_test.go

@@ -10,7 +10,7 @@ import (
 )
 
 func TestEnvVarGroups(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(852)
+	g := testutil.NewObjectJSONGenerator()
 	envVarGroup := g.EnvVarGroup().JSON
 
 	tests := []RouteTest{

client/feature_flag_test.go

@@ -10,7 +10,7 @@ import (
 )
 
 func TestFeatureFlags(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(852)
+	g := testutil.NewObjectJSONGenerator()
 	ff := g.FeatureFlag().JSON
 	ff2 := g.FeatureFlag().JSON
 	ff3 := g.FeatureFlag().JSON

client/filter.go

@@ -30,41 +30,63 @@ func (r FilterModifier) String() string {
 	return ""
 }
 
+type TimestampFilterList []TimestampFilter
+
 type TimestampFilter struct {
 	Timestamp []time.Time
 	Operator  FilterModifier
 }
 
-func (t *TimestampFilter) EqualTo(createdAt ...time.Time) {
-	t.Timestamp = createdAt
+func (tl *TimestampFilterList) EqualTo(ts ...time.Time) {
+	*tl = append(*tl, TimestampFilter{
+		Timestamp: ts,
+	})
 }
 
-func (t *TimestampFilter) Before(createdAt time.Time) {
-	t.Timestamp = []time.Time{
-		createdAt,
-	}
-	t.Operator = FilterModifierLessThan
+func (tl *TimestampFilterList) Before(ts time.Time) {
+	*tl = append(*tl, TimestampFilter{
+		Timestamp: []time.Time{
+			ts,
+		},
+		Operator: FilterModifierLessThan,
+	})
 }
 
-func (t *TimestampFilter) BeforeOrEqualTo(createdAt time.Time) {
-	t.Timestamp = []time.Time{
-		createdAt,
-	}
-	t.Operator = FilterModifierLessThanOrEqual
+func (tl *TimestampFilterList) BeforeOrEqualTo(ts time.Time) {
+	*tl = append(*tl, TimestampFilter{
+		Timestamp: []time.Time{
+			ts,
+		},
+		Operator: FilterModifierLessThanOrEqual,
+	})
 }
 
-func (t *TimestampFilter) After(createdAt time.Time) {
-	t.Timestamp = []time.Time{
-		createdAt,
-	}
-	t.Operator = FilterModifierGreaterThan
+func (tl *TimestampFilterList) After(ts time.Time) {
+	*tl = append(*tl, TimestampFilter{
+		Timestamp: []time.Time{
+			ts,
+		},
+		Operator: FilterModifierGreaterThan,
+	})
 }
 
-func (t *TimestampFilter) AfterOrEqualTo(createdAt time.Time) {
-	t.Timestamp = []time.Time{
-		createdAt,
+func (tl *TimestampFilterList) AfterOrEqualTo(ts time.Time) {
+	*tl = append(*tl, TimestampFilter{
+		Timestamp: []time.Time{
+			ts,
+		},
+		Operator: FilterModifierGreaterThanOrEqual,
+	})
+}
+
+func (tl TimestampFilterList) Serialize(values url.Values, tag string) error {
+	for _, t := range tl {
+		err := t.Serialize(values, tag)
+		if err != nil {
+			return err
+		}
 	}
-	t.Operator = FilterModifierGreaterThanOrEqual
+	return nil
 }
 
 func (t TimestampFilter) Serialize(values url.Values, tag string) error {

client/isolation_segment_test.go

@@ -10,7 +10,7 @@ import (
 )
 
 func TestIsolationSegments(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(1)
+	g := testutil.NewObjectJSONGenerator()
 	iso := g.IsolationSegment().JSON
 	iso2 := g.IsolationSegment().JSON
 	iso3 := g.IsolationSegment().JSON

client/job.go

@@ -2,7 +2,6 @@ package client
 
 import (
 	"context"
-
 	"github.com/cloudfoundry/go-cfclient/v3/internal/path"
 	"github.com/cloudfoundry/go-cfclient/v3/resource"
 )
@@ -21,20 +20,19 @@ func (c *JobClient) Get(ctx context.Context, guid string) (*resource.Job, error)
 
 // PollComplete waits until the job completes, fails, or times out
 func (c *JobClient) PollComplete(ctx context.Context, jobGUID string, opts *PollingOptions) error {
-	err := PollForStateOrTimeout(func() (string, error) {
+	err := PollForStateOrTimeout(func() (string, string, error) {
 		job, err := c.Get(ctx, jobGUID)
 		if job != nil {
-			return string(job.State), err
+			var cfErrors string
+			for _, e := range job.Errors {
+				cfErrors += "\n" + e.Error()
+			}
+			for _, e := range job.Warnings {
+				cfErrors += "\n" + e.Detail
+			}
+			return string(job.State), cfErrors, err
 		}
-		return "", err
+		return "", "", err
 	}, string(resource.JobStateComplete), opts)
-
-	// attempt to return the underlying saved job error
-	if err == AsyncProcessFailedError {
-		job, _ := c.Get(ctx, jobGUID)
-		if job != nil && len(job.Errors) > 0 {
-			return job.Errors[0]
-		}
-	}
 	return err
 }

client/job_test.go

@@ -2,15 +2,24 @@ package client
 
 import (
 	"context"
+	"github.com/stretchr/testify/require"
 	"net/http"
 	"testing"
+	"time"
 
 	"github.com/cloudfoundry/go-cfclient/v3/testutil"
 )
 
 func TestJobs(t *testing.T) {
-	g := testutil.NewObjectJSONGenerator(1)
+	g := testutil.NewObjectJSONGenerator()
 	job := g.Job("COMPLETE").JSON
+	jobProcessing := g.Job("PROCESSING").JSON
+	jobFailed := g.JobFailed().JSON
+	pollingOpts := &PollingOptions{
+		FailedState:   "FAILED",
+		Timeout:       time.Second,
+		CheckInterval: time.Nanosecond,
+	}
 
 	tests := []RouteTest{
 		{
@@ -19,12 +28,44 @@ func TestJobs(t *testing.T) {
 				Method:   "GET",
 				Endpoint: "/v3/jobs/c33a5caf-77e0-4d6e-b587-5555d339bc9a",
 				Output:   g.Single(job),
-				Status:   http.StatusOK},
+				Status:   http.StatusOK,
+			},
 			Expected: job,
 			Action: func(c *Client, t *testing.T) (any, error) {
 				return c.Jobs.Get(context.Background(), "c33a5caf-77e0-4d6e-b587-5555d339bc9a")
 			},
 		},
+		{
+			Description: "Poll job that succeeds",
+			Route: testutil.MockRoute{
+				Method:   "GET",
+				Endpoint: "/v3/jobs/c33a5caf-77e0-4d6e-b587-5555d339bc9a",
+				Output:   []string{jobProcessing, job},
+				Statuses: []int{http.StatusOK, http.StatusOK},
+			},
+			Action: func(c *Client, t *testing.T) (any, error) {
+				err := c.Jobs.PollComplete(context.Background(), "c33a5caf-77e0-4d6e-b587-5555d339bc9a", pollingOpts)
+				return nil, err
+			},
+		},
+		{
+			Description: "Poll job that fails",
+			Route: testutil.MockRoute{
+				Method:   "GET",
+				Endpoint: "/v3/jobs/40e49716-44a3-4ae9-9926-d1a804acf70c",
+				Output:   []string{jobProcessing, jobFailed},
+				Statuses: []int{http.StatusOK, http.StatusOK},
+			},
+			Action: func(c *Client, t *testing.T) (any, error) {
+				err := c.Jobs.PollComplete(context.Background(), "40e49716-44a3-4ae9-9926-d1a804acf70c", pollingOpts)
+				require.Error(t, err)
+				require.ErrorContains(t, err, "received state FAILED while waiting for async process")
+				require.ErrorContains(t, err, "cfclient error (CF-UnprocessableEntity|10008): something went wrong")
+				require.ErrorContains(t, err, "cfclient error (UnknownError|10001): unexpected error occurred")
+				require.ErrorContains(t, err, "some warning")
+				return nil, nil
+			},
+		},
 	}
 	ExecuteTests(tests, t)
 }