http server

The http server binding decodes HTTP/1.1 protocol or HTTP/2 protocol on the inbound network stream, producing higher level application streams for each request.

Cross-Origin Resource Sharing (CORS) is supported by specifying an access control policy of cross-origin. Further configuration allows for finer-grained access control including specific request origins, methods and headers allowed, and specific response headers exposed.

Authorization is enforced by a guard and the credentials can be extracted from a cookie, header or query parameter.

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

http_server:
  type: http
  kind: server
  options:
    access-control:
      policy: cross-origin
    authorization:
      my_jwt_guard:
        credentials:
          headers:
            authorization: Bearer {credentials}
  routes:
    - when:
        - headers:
            ":scheme": https
            ":authority": example.com:443
      exit: echo_server

Configuration (* required)

options

object

The server specific options.

options:
  access-control:
    policy: cross-origin
  authorization:
    my_jwt_guard:
      credentials:
        headers:
          authorization: Bearer {credentials}
  overrides:
    custom-text: custom-value

options.requests

array of object

Options to configure typed validations for request fields.

requests[].content

enum [ double, float, int32, int64, json, string ], object

Enforce validation for the request content.

content.model*

enum [ double, float, int32, int64, json, string ]

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

requests[].content-type

array of string

Content type of the HTTP request.

requests[].headers

object as map of named enum [ double, float, int32, int64, json, string ], 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 [ double, float, int32, int64, json, string ], object as map of named object properties

Enforce validation for path

path.model*

enum [ double, float, int32, int64, json, string ]

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

params.query

object as map of named enum [ double, float, int32, int64, json, string ], object as map of named object properties

Enforce validation for query

query.model*

enum [ double, float, int32, int64, json, string ]

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

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 [ double, float, int32, int64, json, string ], object

Enforce validation for the response content.

content.model*

enum [ double, float, int32, int64, json, string ]

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 [ double, float, int32, int64, json, string ], object as map of named object properties

Enforce validation for response headers.

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

headers.model*

enum [ double, float, int32, int64, json, string ]

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

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.access-control

object

Defines the same-origin or cross-origin access control policy for the HTTP protocol.

access-control.policy

enum [ same-origin, cross-origin ] | Default: same-origin

Supported access control policies.

access-control.policy: same-origin

const

Extra properties aren't needed when using Same Origin access control for the HTTP protocol.

options:
  access-control:
    policy: same-origin

access-control.policy: cross-origin

const

Additional properties that cover Cross Origin Resource Sharing (CORS) access control for the HTTP protocol.

options:
  access-control:
    policy: cross-origin

access-control.allow

object

Sets the CORS allowed request origins, methods, headers and credentials for the HTTP protocol.

Important

Omission of the allow object means Zilla will allow all origins, methods and headers, without credentials.

allow.origins

array of string

Allowed request origins. Omission of this property is considered allow all *.

allow.methods

array of string

Allowed request methods. Omission of this property is considered allow all *.

allow.headers

array of string

Allowed request headers. Omission of this property is considered allow all *.

allow.credentials

boolean

Support fetch credentials mode include.

access-control.max-age

integer

Maximum cache age (in seconds) for allowed headers and methods.

access-control.expose

object

Exposed cross-origin response headers.

Important

Omission means all response headers.

expose.headers

array of string

Exposed response headers.

options.authorization

object as map of named object properties

Authorization by a named guard for the HTTP/1.1 and HTTP/2 protocols.

authorization:
  my_jwt_guard:
    credentials:
      headers:
        authorization: Bearer {credentials}

authorization.credentials*

object

Defines how to extract credentials from the HTTP request.

credentials.cookies

object as map of named string properties

Named cookie value pattern with {credentials}.

credentials.headers

object as map of named string properties

Named header value pattern with {credentials}, e.g. "Bearer {credentials}".

credentials.query*

object as map of named string properties

Named query parameter value pattern with {credentials}.

routes*

array of object

Conditional http specific routes.

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

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.*