conjure-go-runtime

Golang packages for Conjure-flavored RPC. The full specification is at github.com/palantir/conjure/docs/spec/wire.md.

Packages:

• conjure-go-contract/codecs: The codecs package defines encode/decode behavior for multiple serialization formats. These are used to manipulate request and response bodies.
• conjure-go-contract/errors: The errors package defines conjure-formatted error types as described in the Conjure wire spec.
• conjure-go-contract/uuid: The uuid package provides an implementation of the UUID as defined in RFC 4122.
• conjure-go-client/httpclient: The httpclient package provides a general HTTP client package which can provide a standard library *http.Client or a more opinionated httpclient.Client implementation. The majority of the documentation below describes this package.

Client Usage

The NewHTTPClient(params ...ClientParam) constructor returns a standard library *http.Client configured using Palantir best practices. It offers customizability via ClientParams passed as arguments; see client_params.go for the majority of general-purpose params. The returned client can be used wherever http.DefaultClient can be.

var conf httpclient.ServicesConfig // populate in-code or from yaml

clientConf, err := conf.ClientsConfig("my-service")
if err != nil {
	return err
}
client, err := httpclient.NewHTTPClient(
    httpclient.WithConfig(clientConf),
    httpclient.WithHTTPTimeout(30 * time.Second),
    httpclient.WithUserAgent(fmt.Sprintf("%s/%s", appName, appVersion)),
    httpclient.WithNoProxy())

resp, err := client.Post(ctx,
		httpclient.WithRPCMethodName("CreateFoo"),
		httpclient.WithPath(fooEndpoint),
		httpclient.WithJSONRequest(fooInput),
        httpclient.WithJSONResponse(&fooOutput))

Features

Auth Token Provider

The httpclient.AuthTokenProvider ClientParam sets the Authorization header on each request using the token from the provider. Its interface allows an implementation which refreshes and caches the client's credentials over time.

Error response decoding

httpclient supports a configurable ErrorDecoder for constructing an error given a particular response condition. The default decoder, restErrorDecoder, handles responses with status codes greater than or equal to 400. If the response has a Content-Type of application/json, we attempt to deserialize the body as a Conjure error. Otherwise, the body will be included as an unsafeParam named responseBody. A safeParam statusCode is added to the error and can be accessed with httpclient.StatusCodeFromError.

Error detection can be disabled with the ClientParam httpclient.WithDisableRestErrors() or overridden with httpclient.WithErrorDecoder(). Note that this customizability may change in a future major release (see #80).

HTTP2

HTTP2 support is enabled by default in the generated client. If this must be disabled, use the httpclient.DisableHTTP2() ClientParam.

Metrics

The httpclient.Metrics ClientParam enables the client.response timer metric. By default, it is tagged with method, family (of status code), and service-name.

Panic Recovery

The httpclient.PanicRecovery ClientParam recovers panics occurring during a round trip and propagates them as errors.

Round Trip Middleware

Use a httpclient.Middleware to read or modify a request before it is sent, or a response before it is returned. The transport package includes a number of ClientParams which use this framework under the hood.

type Middleware interface {
	// RoundTrip mimics the API of http.RoundTripper, but adds a 'next' argument.
	// RoundTrip is responsible for invoking next.RoundTrip(req) and returning the response.
	RoundTrip(req *http.Request, next http.RoundTripper) (*http.Response, error)
}

We use round trip middleware to inject headers, instument metrics, and more. Custom middleware can be provided using the httpclient.RoundTripMiddleware param.

Docs TODOs

• Request body behavior
• Response body behavior

Client Configuration

config.go includes a yaml-tagged ServicesConfig struct for use in application config objects. The httpclient.Config ClientParam applies a configuration to a client builder.

Example configuration, inspired by http-remoting-api:

clients:
  max-num-retries: 3
  security:
    ca-files:
    - var/security/ca.pem
    cert-file: var/security/cert.pem
    key-file:  var/security/key.pem
  services:
    api-1:
      uris:
      - https://api-1.example.com/api
      security:
        # Use custom keypair with api-1.
        cert-file: var/security/api-1/cert.pem
        key-file:  var/security/api-1/key.pem
        # Use default system CA certs for external connections
        ca-files: []
    api-2:
      uris:
      - https://api-2a.example.com/api
      - https://api-2b.example.com/api
      - https://api-2c.example.com/api

Retry Behavior

Conjure-go-runtime HTTP clients provide the following retry behavior:

• HTTP Status Code Handling
  • 307 (Temporary Redirect), 308 (Permanent Redirect): the client retries the request with the URL included in the HTTP response's 'Location' header.
  • 429 (Too Many Requests): the client retries the request to a different node based on its URI configuration. TODO: support deriving backoff from the retry-after HTTP response header
  • 503 (Service Unavailable): the client retries the request to a different node based on its URI configuration.
  • 5XX responses: the client retries the request to a different node based on its URI configuration.
• Network Error Handling: the client retries the request to a different node based on its URI configuration.

License

This project is made available under the Apache 2.0 License.