iver-wharf / wharf-api-client-go

REST & gRPC client to talk to the Wharf API, written in Go

Go-lang RPC client for Wharf

A library to talk to Wharf via Wharf's main API written in Go.

Uses net/http to send HTTP requests and encoding/json to serialize/deserialize each message back and forth.

This project is for example used inside the providers to create projects into the database when importing from GitLab, GitHub, or Azure DevOps.

Compatibility

wharf-api-client-go	wharf-api
v1	v0, v1, v2, v3, v4, and v51
v2	v5, and beyond

¹: The PUT endpoints /api/project, /api/token, and /api/provider were removed in wharf-api v5.0.0.

Usage

$ go get github.com/iver-wharf/wharf-api-client-go/v2/pkg/wharfapi

package main

import (
	"fmt"
	"github.com/iver-wharf/wharf-api-client-go/v2/pkg/wharfapi"
)

func main() {
	client := wharfapi.Client{
		APIURL:     "https://example.wharf.com",
		AuthHeader: "Bearer some-auth-token",
	}

	project,err := client.GetProjectByID(125)

	if err != nil {
		fmt.Printf("Unable to find project\n")
	} else {
		fmt.Printf("Project #%d: %s\n", project.ProjectID, project.Name)
	}
}

Sample output

GET | PROJECT | 125
Project #125: MyProject

Linting

make deps # download linting dependencies

make lint

make lint-go # only lint Go code
make lint-md # only lint Markdown files

Some errors can be fixed automatically. Keep in mind that this updates the files in place.

make lint-fix

make lint-fix-go # only lint and fix Go files
make lint-fix-md # only lint and fix Markdown files

---

Maintained by Iver. Licensed under the MIT license.

wharf-api-client-go's Issues

Remove Provider.UploadURL

Continuation from iver-wharf/wharf-api#56

The Provider's upload URL is unused. This change is not backwards compatible for any code that uses wharfapi.Provider.UploadURL for any purpose.

Implement missing methods for endpoints

Unimplemented methods for endpoints that are implemented in wharf-api v5.0.0.

• CreateBuildArtifact (Sending file(s) through multipart form data)
• CreateBuildTestResult (Sending file(s) through multipart form data)
• StreamBuildLog (Receiving a stream)
• Get/Update/DeleteProjectOverrides
• DeleteProject
• GetBuildArtifact (Receive artifact BLOB instead of metadata)

Add PostProject method to Client and update PutProject

There is currently no way to POST a project to wharf-api using this client.

This was "okay" before since the backend PUT and POST operations for projects were basically identical, but with recent updates in wharf-api PUTting now leads to a successful create, except for the fact that the ProviderID becomes null and the import process has to be repeated to get the desired result.

• Add PostProject method to Client
• Update PutProject to pass ID in query params instead of json body, to match the new endpoint described in RFC-0016
• Update PutProject docs comment to no longer say that it adds a new project if none matches, as this is no longer the expected behavior from wharf-api.

Add context.Context throughout

Should allow setting context.Context on each request.

No need to keep the non-context.Context variant. Better to just replace and do a major version bump.

PutBranch POSTs, should PUT

PutBranch should do as the name says and PUT, not POST.

• Make PutBranch PUT instead of POST

Logs streaming (gRPC) fails if no port in APIURL

If specifying e.g http://wharf-api (assuming port 80 because of the protocol) then it error the following:

Error while dialing dial tcp: address wharf-api: missing port in address

This error is from our manual tests with wharf-cmd. Full log:

May-05 14:21Z [ERROR|AGGREGATOR        |…k8saggregator.go:137] Relay error.  pod=stage/wharf-cmd-worker-5w8kb  error=`relaying to wharf: logs: open logs stream to wharf-api: open log creation stream: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing dial tcp: address wharf-api: missing port in address"` (*fmt.wrapError)

Need automated testing via `go test`

Based on iver-wharf/iver-wharf.github.io#75

Need to run Go tests and goimports formatting tests on commits and pull requests automatically.

As Wharf cannot do this yet, we should aim at using GitHub Actions.

Either we use the starter-workflow for Go https://github.com/actions/starter-workflows/blob/1d8891efc2151b2290b1d93e8489f9b1f41bd047/ci/go.yml which simply runs go test

Or we could look into a better integrated solution that could report failing tests as annotations inside the pull requests, such as:

• https://github.com/marketplace/actions/golang-test
• https://github.com/marketplace/actions/golang-test-annotations

Make wharf-api v5.0 compatible

Changes needed to be made to be wharf-api v5.0 compatible.

!! This is a non-exhaustive list of changes required !!
Please comment with any additional things that come to mind.

• Update PUT endpoints to pass ID using path params instead of in the request body.
  • https://iver-wharf.github.io/rfcs/published/0016-wharf-api-endpoints-cleanup#new-layout-for-models
• Add missing methods
  • PostProject
  • PostBranch
• Update PutXXX methods docs comments to no longer say they create.
  • PutBranch
  • PutToken
  • PutProject
  • PutProvider
• Methods named PutXXX that actually POST
  • PutBranch - Change to PUT
• Methods named PostXXX that actually PUT
  • PostProjectRun - Change to POST
• Update GetXXX methods to match new ones.

Names used here are previous names for the functions.

• Use the same name as the wharf-api v5.0.0 handlers for the endpoints, e.g. GetProjectListHandler, minus the -Handler.

Backwards compatibility

Backwards compatibility will not be considered for this change.
Code using this client won't need to change that many things, whilst trying to keep it backwards compatible would greatly extend the required time to complete this.

Map projects by ID: Add RemoteProjectID

Depends on iver-wharf/wharf-api#12

After adding Project.RemoteProjectID to wharf-api we need to add it here as well to stay up-to-date.

Add engines support

Support specifying engine in regarded endpoints that was added in wharf-api v5.1.0.

• New endpoint:

  GET /api/engine

• New query param ?engine=:

  POST /api/project/{projectId}/build?engine=jenkins

Ref: iver-wharf/wharf-api#134

Doesn't follow redirects

The library doesn't follow redirects, but instead errors out with non-2xx status: 301 Moved Permanently

It should obviously follow the redirects. Don't know why it doesn't.

This has forced us to use some ugly URLs with trailing slashes due to implementation details in the wharf-api:

wharf-api-client-go/pkg/wharfapi/test_result.go

Line 96 in 5ddf339

path := fmt.Sprintf("/api/build/%d/test-result/", buildID)

Write docs on all exported types and functions

For all endpoint functions, something like this should be enough:

+// GetTokenByID invokes the HTTP request:
+//     GET /api/token/{tokenID}
 func (c Client) GetTokenByID(tokenID uint) (Token, error) {	newToken := Token{}
 	apiURL := fmt.Sprintf("%s/api/token/%v", c.APIURL, tokenID)

Somewhere there should be a note about the ProblemError and AuthError that can be returned. Perhaps in an example test, or in the package documentation, or both