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.Config(clientConf),
httpclient.HTTPTimeout(30 * time.Second),
httpclient.UserAgent(fmt.Sprintf("%s/%s", appName, appVersion),
httpclient.NoProxy())
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.
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
- Retry behavior
- Request body behavior
- Response body behavior
- Error handling
- REST error creation
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
License
This project is made available under the Apache 2.0 License.