Skip to main content

http client

http client

The http client binding receives inbound application streams and encodes each request as a network stream via HTTP/1.1 protocol. Note that the same network stream can be reused to encode multiple HTTP/1.1 requests.

Conditional routes based on http request headers are used to route these network streams to an exit binding.

http_client:
  type: http
  kind: client
  options:
    versions:
      - h2
  exit: tcp_client

Configuration (* required)

options

object

The client specific options.

options:
  overrides:
    custom-text: custom-value

options.requests

array of object

Options to configure typed validations for request fields.

requests[].content

enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ] as string, or object

Enforce validation for the request content.

content.model*

enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ]

A schema or type to validate the request content. Refer to the individual model docs for type specific implementation.

content.validate

enum [ strict, lenient ] as string, or object | Default: strict

Controls how strictly the content model enforces conformance to the schema. Can also be set independently for decode and encode.

validate.decode

enum [ strict, lenient ]

Validation mode applied when decoding the value.

validate.encode

enum [ strict, lenient ]

Validation mode applied when encoding the value.

requests[].content-type

array of string

Content type of the HTTP request.

requests[].headers

object as map of named enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ] as string, or object as map of named object properties

Enforce validation for request headers.

requests[].method

enum [ GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE ]

HTTP request method.

requests[].params

object

Query parameters of the HTTP request.

params.path

object as map of named enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ] as string, or object as map of named object properties

Enforce validation for path

path.model*

enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ]

A schema or type to validate the path content. Refer to the individual model docs for type specific implementation.

path.validate

enum [ strict, lenient ] as string, or object | Default: strict

Controls how strictly the model enforces conformance to the schema. Can also be set independently for decode and encode.

params.query

object as map of named enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ] as string, or object as map of named object properties

Enforce validation for query

query.model*

enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ]

A schema or type to validate the query content. Refer to the individual model docs for type specific implementation.

query.validate

enum [ strict, lenient ] as string, or object | Default: strict

Controls how strictly the model enforces conformance to the schema. Can also be set independently for decode and encode.

requests[].path

string

URL path of the HTTP request.

requests[].responses

array of object

Options to configure typed validations for response fields.

responses[].content

enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ] as string, or object

Enforce validation for the response content.

content.model*

enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ]

A schema or type to validate the response content. Refer to the individual model docs for type specific implementation.

responses[].content-type

array of string

Content type of the HTTP response.

responses[].headers

object as map of named enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ] as string, or object as map of named object properties

Enforce validation for response headers.

headers:
  my-header:
    model: string
    maxLength: 100

headers.model*

enum [ avro, boolean, bytes, double, float, int32, int64, json, protobuf, string, vector ]

A schema or type to validate the headers content. Refer to the individual model docs for type specific implementation.

headers.validate

enum [ strict, lenient ] as string, or object | Default: strict

Controls how strictly the model enforces conformance to the schema. Can also be set independently for decode and encode.

responses[].status

integer, array of integer

HTTP status code or codes for the response

options.versions

array of enum [ http/1.1, h2 ] | Default: http/1.1,h2

Supported protocol versions.

options.overrides

object as map of named string properties

Request header overrides.

options.authorization

object as map of named object properties

Guard credentials to inject into the upstream request. The named key references a guard defined elsewhere in the configuration. At most one guard may be referenced.

options:
  authorization:
    my_guard:
      credentials:
        headers:
          authorization: Bearer {credentials}

authorization.credentials*

object

Where to inject the named guard's credentials into the outbound request. At least one of cookies, headers, or query is required.

credentials.cookies

object as map of named string properties

Cookie name/value pairs added to the outbound request, with the value containing the literal placeholder {credentials}, substituted with the raw credentials presented to the guard.

credentials.headers

object as map of named string properties

HTTP request headers added to the outbound request, with the value containing either the literal placeholder {credentials}, substituted with the raw credentials presented to the guard, or both {username} and {password} placeholders together.

credentials.query

object as map of named string properties

Query parameters added to the outbound request, with the value containing the literal placeholder {credentials}, substituted with the raw credentials presented to the guard.

routes

array of object

Conditional http specific routes. At least one of routes or the top-level exit is required.

routes:
  - when:
      - headers:
          ":scheme": https
          ":authority": example.com:443
    exit: echo_server

routes[].guarded

object as map of named array of string

List of roles required by each named guard to authorize this route.

routes:
  - guarded:
      my_guard:
        - read:items

Dynamic guarded routes allow roles to be evaluated at runtime based on the incoming HTTP request.

routes:
  - guarded:
      my_guard:
        - ${method}${path}

${method} Replaced with the request method (e.g., GET, POST)

${path} Replaced with the request path (e.g., /items, /users/123)

A combination of both static and dynamic guarded routes is supported.

routes[].when

array of object

List of conditions (any match) to match this route. Read more: When a route matches

routes:
  - when:
      - headers:
          ":scheme": https
          ":authority": example.com:443

when[].headers

object as map of named string properties

Header name value pairs (all match).

routes[].with

object

HTTP parameters for matched route when http streams.

routes:
  - with:
      headers:
        overrides:
          ":scheme": https
          ":authority": example.com:443

with.headers

object

Options for headers when adapting a route.

headers.overrides

object as map of named string properties

HTTP header name value pairs overrides.

routes[].exit

string

Next binding when following this route.

routes:
  - when:
    ...
    exit: echo_server

exit

string

Default exit binding when no conditional routes are viable.

exit: echo_server

telemetry

object

Defines the desired telemetry for the binding.

telemetry.metrics

array

Telemetry metrics to track

telemetry:
  metrics:
    - stream.*
    - http.*

telemetry.attributes

object as map of named string properties

Telemetry attributes to add to the binding metrics.

Gateway Version