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
- Host: GitHub
- URL: https://github.com/palantir/conjure-go-runtime
- Owner: palantir
- License: apache-2.0
- Created: 2018-08-08T17:22:59.000Z (almost 7 years ago)
- Default Branch: develop
- Last Pushed: 2025-04-06T01:13:08.000Z (2 months ago)
- Last Synced: 2025-04-06T02:22:40.184Z (2 months ago)
- Topics: octo-correct-managed
- Language: Go
- Homepage:
- Size: 6.26 MB
- Stars: 13
- Watchers: 256
- Forks: 23
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- Changelog: changelog/0.3.2/pr-56.v2.yml
- License: LICENSE
Awesome Lists containing this project
README
conjure-go-runtime
==================
[](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).