An open API service indexing awesome lists of open source software.

https://github.com/palantir/conjure-go-runtime

Go implementation of the Conjure runtime
https://github.com/palantir/conjure-go-runtime

octo-correct-managed

Last synced: 2 months ago
JSON representation

Go implementation of the Conjure runtime

Awesome Lists containing this project

README

        


Autorelease

conjure-go-runtime
==================
[![](https://godoc.org/github.com/palantir/conjure-go-runtime?status.svg)](http://godoc.org/github.com/palantir/conjure-go-runtime)

Golang packages for Conjure-flavored RPC. The full specification is at [github.com/palantir/conjure/docs/spec/wire.md](https://github.com/palantir/conjure/blob/master/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](https://github.com/palantir/conjure/blob/master/docs/spec/wire.md#55-conjure-errors).
* `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`](conjure-go-client/httpclient/client_params.go) for the majority of general-purpose params.
The returned client can be used wherever `http.DefaultClient` can be.

```go
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](https://github.com/palantir/conjure/blob/master/docs/spec/wire.md#55-conjure-errors).
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](https://github.com/palantir/conjure-go-runtime/issues/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.

```go
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](https://github.com/palantir/http-remoting-api):
```yml
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](http://www.apache.org/licenses/LICENSE-2.0).