Module : http

Module overview

This module provides an implementation for connecting and interacting with HTTP, HTTP2, and WebSocket endpoints. The module facilitates two types of endpoints as ‘Client’ and ‘Listener’.

Client endpoints

Client endpoints are used to connect to and interact with HTTP endpoints. They support connection pooling and can be configured to have a maximum number of active connections that can be made with the remote endpoint. Client endpoints activate connection eviction after a given idle period and also support follow-redirects so that the users do not have to manually handle 3xx HTTP status codes.

Client endpoints handle resilience in multiple ways such as load balancing, circuit breaking, endpoint timeouts, and a retry mechanism.

Load balancing is used in the round robin or failover manner.

When a failure occurs in the remote service, the client connections might wait for some time before a timeout occurs. Awaiting requests consume resources in the system. Circuit Breakers are used to trip after a certain number of failed requests to the remote service. Once a circuit breaker trips, it does not allow the client to send requests to the remote service for a period of time.

The Ballerina circuit breaker supports tripping on HTTP error status codes and I/O errors. Failure thresholds can be configured based on a sliding window (e.g., 5 failures within 10 seconds). Client endpoints also support a retry mechanism that allows a client to resend failed requests periodically for a given number of times.

Client endpoints support Server Name Indication (SNI), Certificate Revocation List (CRL), Online Certificate Status Protocol (OCSP), and OCSP Stapling for SSL/TLS connections. They also support HTTP2, keep-alive, chunking, HTTP caching, data compression/decompression, and authentication/authorization.

A Client endpoint can be defined using the URL of the remote service that the client needs to connect with, as shown below:

http:Client clientEndpoint = new("https://my-simple-backend.com");

The defined Client endpoint can be used to call a remote service as follows:

// Send a GET request to the specified endpoint.
var response = clientEndpoint->get("/get?id=123");

For more information, see Client Endpoint Example, Circuit Breaker Example, HTTP Redirects Example.

Listener endpoints

A Service represents a collection of network-accessible entry points and can be exposed via a Listener endpoint. A resource represents one such entry point and can have its own path, HTTP methods, body format, 'consumes' and 'produces' content types, CORS headers, etc. In resources, http:caller and http:Request are mandatory parameters while path and body are optional.

When a Service receives a request, it is dispatched to the best-matched resource.

A Listener endpoint can be defined as follows:

// Attributes associated with the `Listener` endpoint are defined here.
listener http:Listener helloWorldEP = new(9090);

Then a Service can be defined and attached to the above Listener endpoint as shown below:

// By default, Ballerina assumes that the service is to be exposed via HTTP/1.1.
@http:ServiceConfig { basePath: "/helloWorld" }
service helloWorld on helloWorldEP {

   // All resource functions are invoked with arguments of server connector and request.
   @http:ResourceConfig {
       methods: ["POST"],
       path: "/{name}",
       body: "message"
   }
   resource function sayHello(http:Caller caller, http:Request req, string name, string message) {
       http:Response res = new;
       // A util method that can be used to set string payload.
       res.setPayload("Hello, World! I’m " + <@untainted> name + ". " + <@untainted> message);
       // Sends the response back to the client.
       var result = caller->respond(res);
       if (result is http:ListenerError) {
            error err = result;
            log:printError("Error sending response", err = err);
       }
   }
}

See Listener Endpoint Example, HTTP CORS Example, HTTP Failover Example, HTTP Load Balancer Example

Listener endpoints can be exposed via SSL. They support Mutual SSL, Hostname Verification, and Application Layer Protocol Negotiation (ALPN) for HTTP2. Listener endpoints also support Certificate Revocation List (CRL), Online Certificate Status Protocol (OCSP), OCSP Stapling, HTTP2, keep-alive, chunking, HTTP caching, data compression/decompression, and authentication/authorization.

For more information, see Mutual SSL Example.

For more information, see Caching Example, HTTP Disable Chunking Example.

WebSocket

This module also provides support for WebSockets. There are two types of WebSocket endpoints: WebSocketClient and WebSocketListener. Both endpoints support all WebSocket frames. The WebSocketClient has a callback service.

There are two types of services for WebSockets. The service of the server has the WebSockerCaller as the resource parameter and the callback service of the client has WebSocketClient as the resource parameter. The WebSocket services have a fixed set of resources that do not have a resource config. The incoming messages are passed to these resources.

WebSocket upgrade: During a WebSocket upgrade, the initial message received is an HTTP request. To intercept this request and perform the upgrade explicitly with custom headers, the user must create an HTTP resource with WebSocket-specific configurations as follows:

@http:ResourceConfig {
    webSocketUpgrade: {
        upgradePath: "/{name}",
        upgradeService: chatApp
    }
}
resource function upgrader(http:Caller caller, http:Request req, string name) {
}

The upgradeService is a server callback service.

onOpen resource: As soon as the WebSocket handshake is completed and the connection is established, the onOpen resource is dispatched. This resource is only available in the service of the server.

onText resource: The received text messages are dispatched to this resource.

onBinary resource: The received binary messages are dispatched to this resource.

onPing and onPong resources: The received ping and pong messages are dispatched to these resources respectively.

onIdleTimeout: This resource is dispatched when the idle timeout is reached. The idleTimeout has to be configured either in the WebSocket service or the client configuration.

onClose: This resource is dispatched when a close frame with a statusCode and a reason is received.

onError: This resource is dispatched when an error occurs in the WebSocket connection. This will always be preceded by a connection closure with an appropriate close frame.

For more information, see WebSocket Basic Example, HTTP to WebSocket Upgrade Example, WebSocket Chat Application, WebSocket Proxy Server.

Logging

This module supports two types of logs:

To publish logs to a socket, both the host and port configurations must be provided.

See HTTP Access Logs Example, HTTP Trace Logs Example

Records

AuthzCacheConfig Provides a set of configurations for controlling the authorization caching behaviour of the endpoint.
Bucket Represents a discrete sub-part of the time window (Bucket).
CacheConfig Provides a set of configurations for controlling the caching behaviour of the endpoint.
CircuitBreakerConfig Provides a set of configurations for controlling the behaviour of the Circuit Breaker.
CircuitBreakerInferredConfig Derived set of configurations from the `CircuitBreakerConfig`.
CircuitHealth Maintains the health of the Circuit Breaker.
ClientConfiguration Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
ClientHttp1Settings Provides settings related to HTTP/1.x protocol.
ClientHttp2Settings Provides settings related to HTTP/2 protocol.
ClientSecureSocket Provides configurations for facilitating secure communication with a remote HTTP endpoint.
CompressionConfig A record for providing configurations for content compression.
CorsConfig Configurations for CORS support.
Detail Holds the details of an HTTP error
FailoverClientConfiguration Provides a set of HTTP related configurations and failover related configurations.
FailoverConfig Provides a set of configurations for controlling the failover behaviour of the endpoint.
FailoverInferredConfig Inferred failover configurations passed into the failover client.
FollowRedirects Provides configurations for controlling the endpoint's behaviour in response to HTTP redirect related responses.
HttpResourceConfig Configuration for an HTTP resource.
HttpServiceConfig Contains the configurations for an HTTP service.
HttpTimeoutError Defines a timeout error occurred during service invocation.
ListenerAuth Authentication configurations for the listener.
ListenerConfiguration Provides a set of configurations for HTTP service endpoints.
ListenerHttp1Settings Provides settings related to HTTP/1.x protocol.
ListenerOcspStapling A record for providing configurations for certificate revocation status checks.
ListenerSecureSocket Configures the SSL/TLS options to be used for HTTP service.
LoadBalanceActionErrorData Represents an error occurred in an remote function of the Load Balance connector.
LoadBalanceClientConfiguration The configurations related to the load balance client endpoint.
Local Presents a read-only view of the local address.
MutualSslHandshake A record for providing mutual ssl handshake results.
OutboundAuthConfig The `OutboundAuthConfig` record can be used to configure the authentication mechanism used by the HTTP endpoint.
PoolConfiguration Configurations for managing HTTP client connection pool.
Protocols A record for configuring SSL/TLS protocol and version to be used.
ProxyConfig Proxy server configurations to be used with the HTTP client endpoint.
Remote Presents a read-only view of the remote address.
RetryConfig Provides configurations for controlling the retrying behavior in failure scenarios.
RetryInferredConfig Derived set of configurations from the `RetryConfig`.
RollingWindow Represents a rolling window in the Circuit Breaker.
ServiceResourceAuth Configures the authentication scheme for a service or a resource.
TargetService Represents a single service and its related configurations.
ValidateCert A record for providing configurations for certificate revocation status checks.
Versioning Configurations for service versioning.
WSServiceConfig Configurations for a WebSocket service.
WebSocketClientConfiguration Configuration for the WebSocket client endpoint.
WebSocketUpgradeConfig Resource configuration to upgrade from HTTP to WebSocket.

Objects

AuthnFilter

Representation of the Authentication filter.

AuthzFilter

Representation of the Authorization filter.

AuthzHandler

Representation of Authorization Handler for HTTP.

BasicAuthHandler

Defines the Basic Auth header handler for inbound and outbound HTTP traffic.

BearerAuthHandler

Representation of the Bearer Auth header handler for both inbound and outbound HTTP traffic.

FilterContext

Representation of request filter Context.

HttpCache

Implements a cache for storing HTTP responses. This cache complies with the caching policy set when configuring HTTP caching in the HTTP client endpoint.

HttpFuture

Represents a 'future' that returns as a result of an asynchronous HTTP request submission. This can be used as a reference to fetch the results of the submission.

InboundAuthHandler

The representation of an inbound authentication handler for HTTP traffic.

LoadBalancerRoundRobinRule

Implementation of round robin load balancing strategy.

LoadBalancerRule

LoadBalancerRule provides a required interfaces to implement different algorithms.

OutboundAuthHandler

The representation of an outbound authentication handler for HTTP traffic.

PushPromise

Represents an HTTP/2 PUSH_PROMISE frame.

Request

Represents an HTTP request.

RequestCacheControl

Configures cache control directives for a Request.

RequestFilter

Abstract Representation of a HTTP Request Filter. This filter will be applied before the request is dispatched to the relevant resource. Any RequestFilter implementation should be structurally similar to or implement the RequestFilter object.

Response

Represents an HTTP response.

ResponseCacheControl

Configures cache control directives for a Response.

ResponseFilter

Abstract Representation of a HTTP Response Filter. This filter will be applied in the response path. Any ResponseFilter implementation should be structurally similar to or implement the ResponseFilter object.

Clients

Caller

The caller actions for responding to client requests.

CircuitBreakerClient

A Circuit Breaker implementation which can be used to gracefully handle network failures.

Client

The HTTP client provides the capability for initiating contact with a remote HTTP service. The API it provides includes functions for the standard HTTP methods, forwarding a received request and sending requests using custom HTTP verbs.

FailoverClient

An HTTP client endpoint which provides failover support over multiple HTTP clients.

HttpCachingClient

An HTTP caching client implementation which takes an HttpActions instance and wraps it with an HTTP caching layer.

HttpClient

Provides the HTTP actions for interacting with an HTTP server. Apart from the standard HTTP methods, forward() and execute() functions are provided. More complex and specific endpoint types can be created by wrapping this generic HTTP actions implementation.

HttpSecureClient

Provides secure HTTP remote functions for interacting with HTTP endpoints. This will make use of the authentication schemes configured in the HTTP client endpoint to secure the HTTP requests.

LoadBalanceClient

LoadBalanceClient endpoint provides load balancing functionality over multiple HTTP clients.

RedirectClient

Provides redirect functionality for HTTP client remote functions.

RetryClient

Provides the HTTP remote functions for interacting with an HTTP endpoint. This is created by wrapping the HTTP client to provide retrying over HTTP requests.

WebSocketCaller

Represents a WebSocket caller.

WebSocketClient

Represents a WebSocket client endpoint.

Listeners

Listener

This is used for creating HTTP server endpoints. An HTTP server endpoint is capable of responding to remote callers. The Listener is responsible for initializing the endpoint using the provided configurations.

MockListener

Mock server endpoint which does not open a listening port.

Functions

createHttpCachingClient

Creates an HTTP client capable of caching HTTP responses.

createHttpSecureClient

Creates an HTTP client capable of securing HTTP requests with authentication.

extractAuthorizationHeaderValue

Extracts the Authorization header value from the request.

invokeEndpoint

The HEAD remote function implementation of the Circuit Breaker. This wraps the head() function of the underlying HTTP remote function provider.

parseHeader

Parses the given header value to extract its value and parameter map.

Constants

AUTH_HEADER

Represents the Authorization header name.

AUTH_HEADER_BEARER

Indicates that the authentication credentials should be sent via the Authentication header.

POST_BODY_BEARER

Indicates that the Authentication credentials should be sent via the body of the POST request.

NO_BEARER

Indicates that the authentication credentials should not be sent.

STATUS_CODE

Indicates the status code.

NO_CACHE

Forces the cache to validate a cached response with the origin server before serving.

NO_STORE

Instructs the cache to not store a response in non-volatile storage.

NO_TRANSFORM

Instructs intermediaries not to transform the payload.

MAX_AGE

When used in requests, max-age implies that clients are not willing to accept responses whose age is greater than max-age. When used in responses, the response is to be considered stale after the specified number of seconds.

MAX_STALE

Indicates that the client is willing to accept responses which have exceeded their freshness lifetime by no more than the specified number of seconds.

MIN_FRESH

Indicates that the client is only accepting responses whose freshness lifetime >= current age + min-fresh.

ONLY_IF_CACHED

Indicates that the client is only willing to accept a cached response. A cached response is served subject to other constraints posed by the request.

MUST_REVALIDATE

Indicates that once the response has become stale, it should not be reused for subsequent requests without validating with the origin server.

PUBLIC

Indicates that any cache may store the response.

PRIVATE

Indicates that the response is intended for a single user and should not be stored by shared caches.

PROXY_REVALIDATE

Has the same semantics as must-revalidate, except that this does not apply to private caches.

S_MAX_AGE

In shared caches, s-maxage overrides the max-age or expires header field.

MAX_STALE_ANY_AGE

Setting this as the max-stale directives indicates that the max-stale directive does not specify a limit.

CACHE_CONTROL_AND_VALIDATORS

This is a more restricted mode of RFC 7234. Setting this as the caching policy restricts caching to instances where the cache-control header and either the etag or last-modified header are present.

RFC_7234

Caching behaviour is as specified by the RFC 7234 specification.

HTTP_ERROR_CODE

Constant for the http error code

MULTIPART_AS_PRIMARY_TYPE

Represents multipart primary type

HTTP_FORWARD

Constant for the HTTP FORWARD method

HTTP_GET

Constant for the HTTP GET method

HTTP_POST

Constant for the HTTP POST method

HTTP_DELETE

Constant for the HTTP DELETE method

HTTP_OPTIONS

Constant for the HTTP OPTIONS method

HTTP_PUT

Constant for the HTTP PUT method

HTTP_PATCH

Constant for the HTTP PATCH method

HTTP_HEAD

Constant for the HTTP HEAD method

HTTP_SUBMIT

constant for the HTTP SUBMIT method

HTTP_NONE

Constant for the identify not an HTTP Operation

CHUNKING_AUTO

If the payload is less than 8KB, content-length header is set in the outbound request/response, otherwise chunking header is set in the outbound request/response.}

CHUNKING_ALWAYS

Always set chunking header in the response.

CHUNKING_NEVER

Never set the chunking header even if the payload is larger than 8KB in the outbound request/response.

COMPRESSION_AUTO

When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the outbound request/response accept-encoding/content-encoding option.

COMPRESSION_ALWAYS

Always set accept-encoding/content-encoding in outbound request/response.

COMPRESSION_NEVER

Never set accept-encoding/content-encoding header in outbound request/response.

REDIRECT_MULTIPLE_CHOICES_300

Represents the HTTP redirect status code 300 - Multiple Choices.

REDIRECT_MOVED_PERMANENTLY_301

Represents the HTTP redirect status code 301 - Moved Permanently.

REDIRECT_FOUND_302

Represents the HTTP redirect status code 302 - Found.

REDIRECT_SEE_OTHER_303

Represents the HTTP redirect status code 303 - See Other.

REDIRECT_NOT_MODIFIED_304

Represents the HTTP redirect status code 304 - Not Modified.

REDIRECT_USE_PROXY_305

Represents the HTTP redirect status code 305 - Use Proxy.

REDIRECT_TEMPORARY_REDIRECT_307

Represents the HTTP redirect status code 307 - Temporary Redirect.

REDIRECT_PERMANENT_REDIRECT_308

Represents the HTTP redirect status code 308 - Permanent Redirect.

FAILOVER_ALL_ENDPOINTS_FAILED

Represents the reason string for the http:FailoverAllEndpointsFailedError

FAILOVER_ENDPOINT_ACTION_FAILED

Represents the reason string for the http:FailoverActionFailedError

UPSTREAM_SERVICE_UNAVAILABLE

Represents the reason string for the http:UpstreamServiceUnavailableError

ALL_LOAD_BALANCE_ENDPOINTS_FAILED

Represents the reason string for the http:AllLoadBalanceEndpointsFailedError

ALL_RETRY_ATTEMPTS_FAILED

Represents the reason string for the http:AllRetryAttemptsFailed

IDLE_TIMEOUT_TRIGGERED

Represents the reason string for the http:IdleTimeoutError

AUTHN_FAILED

Represents the reason string for the http:AuthenticationError

AUTHZ_FAILED

Represents the reason string for the http:AuthorizationError

INIT_OUTBOUND_REQUEST_FAILED

Represents the reason string for the http:InitializingOutboundRequestError

WRITING_OUTBOUND_REQUEST_HEADERS_FAILED

Represents the reason string for the http:WritingOutboundRequestHeadersError

WRITING_OUTBOUND_REQUEST_BODY_FAILED

Represents the reason string for the http:WritingOutboundRequestBodyError

INIT_INBOUND_RESPONSE_FAILED

Represents the reason string for the http:InitializingInboundResponseError

READING_INBOUND_RESPONSE_HEADERS_FAILED

Represents the reason string for the http:ReadingInboundResponseBodyError

READING_INBOUND_RESPONSE_BODY_FAILED

Represents the reason string for the http:ReadingInboundResponseBodyError

INIT_INBOUND_REQUEST_FAILED

Represents the reason string for the http:InitialingInboundRequestError

READING_INBOUND_REQUEST_HEADERS_FAILED

Represents the reason string for the http:ReadingInboundRequestHeadersError

READING_INBOUND_REQUEST_BODY_FAILED

Represents the reason string for the http:ReadingInboundRequestBodyError

INIT_OUTBOUND_RESPONSE_FAILED

Represents the reason string for the http:InitializingOutboundResponseError

WRITING_OUTBOUND_RESPONSE_HEADERS_FAILED

Represents the reason string for the http:WritingOutboundResponseHeadersError

WRITING_OUTBOUND_RESPONSE_BODY_FAILED

Represents the reason string for the http:WritingOutboundResponseBodyError

INITIATING_100_CONTINUE_RESPONSE_FAILED

Represents the reason string for the http:Initiating100ContinueResponseError

WRITING_100_CONTINUE_RESPONSE_FAILED

Represents the reason string for the http:Writing100ContinueResponseError

GENERIC_CLIENT_ERROR

Error reason for generic client error

GENERIC_LISTENER_ERROR

Represents the reason string for the http:GenericListenerError

UNSUPPORTED_ACTION

Represents the reason string for the http:UnsupportedActionError

HTTP2_CLIENT_ERROR

Represents the reason string for the http:Http2ClientError

MAXIMUM_WAIT_TIME_EXCEEDED

Represents the reason string for the http:MaximumWaitTimeExceededError

SSL_ERROR

Represents the reason string for the http:SslError

AGE

HTTP header key age. Gives the current age of a cached HTTP response.

AUTHORIZATION

HTTP header key authorization

CACHE_CONTROL

HTTP header key cache-control. Specifies the cache control directives required for the function of HTTP caches.

CONTENT_LENGTH

HTTP header key content-length. Specifies the size of the response body in bytes.

CONTENT_TYPE

HTTP header key content-type. Specifies the type of the message payload.

DATE

HTTP header key date. The timestamp at the time the response was generated/received.

ETAG

HTTP header key etag. A finger print for a resource which is used by HTTP caches to identify whether a resource representation has changed.

EXPECT

HTTP header key expect. Specifies expectations to be fulfilled by the server.

EXPIRES

HTTP header key expires. Specifies the time at which the response becomes stale.

IF_MATCH

HTTP header key if-match

IF_MODIFIED_SINCE

HTTP header key if-modified-since. Used when validating (with the origin server) whether a cached response is still valid. If the representation of the resource has modified since the timestamp in this field, a 304 response is returned.

IF_NONE_MATCH

HTTP header key if-none-match. Used when validating (with the origin server) whether a cached response is still valid. If the ETag provided in this field matches the representation of the requested resource, a 304 response is returned.

IF_RANGE

HTTP header key if-range

IF_UNMODIFIED_SINCE

HTTP header key if-unmodified-since

LAST_MODIFIED

HTTP header key last-modified. The time at which the resource was last modified.

LOCATION

HTTP header key location. Indicates the URL to redirect a request to.

PRAGMA

HTTP header key pragma. Used in dealing with HTTP 1.0 caches which do not understand the cache-control header.

SERVER

HTTP header key server. Specifies the details of the origin server.

WARNING

HTTP header key warning. Specifies warnings generated when serving stale responses from HTTP caches.

TRANSFER_ENCODING

HTTP header key transfer-encoding. Specifies what type of transformation has been applied to entity body.

CONNECTION

HTTP header key connection. Allows the sender to specify options that are desired for that particular connection.

UPGRADE

HTTP header key upgrade. Allows the client to specify what additional communication protocols it supports and would like to use, if the server finds it appropriate to switch protocols.

PASSED

Mutual SSL handshake is successful.

FAILED

Mutual SSL handshake has failed.

NONE

Not a mutual ssl connection.

CB_OPEN_STATE

Represents the open state of the circuit. When the Circuit Breaker is in OPEN state, requests will fail immediately.

CB_HALF_OPEN_STATE

Represents the half-open state of the circuit. When the Circuit Breaker is in HALF_OPEN state, a trial request will be sent to the upstream service. If it fails, the circuit will trip again and move to the OPEN state. If not, it will move to the CLOSED state.

CB_CLOSED_STATE

Represents the closed state of the circuit. When the Circuit Breaker is in CLOSED state, all requests will be allowed to go through to the upstream service. If the failures exceed the configured threhold values, the circuit will trip and move to the OPEN state.

STATUS_CONTINUE

The HTTP response status code: 100 Continue

STATUS_SWITCHING_PROTOCOLS

The HTTP response status code: 101 Switching Protocols

STATUS_OK

The HTTP response status code: 200 OK

STATUS_CREATED

The HTTP response status code: 201 Created

STATUS_ACCEPTED

The HTTP response status code: 202 Accepted

STATUS_NON_AUTHORITATIVE_INFORMATION

The HTTP response status code: 203 Non Authoritative Information

STATUS_NO_CONTENT

The HTTP response status code: 204 No Content

STATUS_RESET_CONTENT

The HTTP response status code: 205 Reset Content

STATUS_PARTIAL_CONTENT

The HTTP response status code: 206 Partial Content

STATUS_MULTIPLE_CHOICES

The HTTP response status code: 300 Multiple Choices

STATUS_MOVED_PERMANENTLY

The HTTP response status code: 301 Moved Permanently

STATUS_FOUND

The HTTP response status code: 302 Found

STATUS_SEE_OTHER

The HTTP response status code: 303 See Other

STATUS_NOT_MODIFIED

The HTTP response status code: 304 Not Modified

STATUS_USE_PROXY

The HTTP response status code: 305 Use Proxy

STATUS_TEMPORARY_REDIRECT

The HTTP response status code: 307 Temporary Redirect

STATUS_PERMANENT_REDIRECT

The HTTP response status code: 308 Permanent Redirect

STATUS_BAD_REQUEST

The HTTP response status code: 400 Bad Request

STATUS_UNAUTHORIZED

The HTTP response status code: 401 Unauthorized

STATUS_PAYMENT_REQUIRED

The HTTP response status code: 402 Payment Required

STATUS_FORBIDDEN

The HTTP response status code: 403 Forbidden

STATUS_NOT_FOUND

The HTTP response status code: 404 Not Found

STATUS_METHOD_NOT_ALLOWED

The HTTP response status code: 405 Method Not Allowed

STATUS_NOT_ACCEPTABLE

The HTTP response status code: 406 Not Acceptable

STATUS_PROXY_AUTHENTICATION_REQUIRED

The HTTP response status code: 407 Proxy Authentication Required

STATUS_REQUEST_TIMEOUT

The HTTP response status code: 408 Request Timeout

STATUS_CONFLICT

The HTTP response status code: 409 Conflict

STATUS_GONE

The HTTP response status code: 410 Gone

STATUS_LENGTH_REQUIRED

The HTTP response status code: 411 Length Required

STATUS_PRECONDITION_FAILED

The HTTP response status code: 412 Precondition Failed

STATUS_PAYLOAD_TOO_LARGE

The HTTP response status code: 413 Payload Too Large

STATUS_URI_TOO_LONG

The HTTP response status code: 414 URI Too Long

STATUS_UNSUPPORTED_MEDIA_TYPE

The HTTP response status code: 415 Unsupported Media Type

STATUS_RANGE_NOT_SATISFIABLE

The HTTP response status code: 416 Range Not Satisfiable

STATUS_EXPECTATION_FAILED

The HTTP response status code: 417 Expectation Failed

STATUS_UPGRADE_REQUIRED

The HTTP response status code: 426 Upgrade Required

STATUS_INTERNAL_SERVER_ERROR

The HTTP response status code: 500 Internal Server Error

STATUS_NOT_IMPLEMENTED

The HTTP response status code: 501 Not Implemented

STATUS_BAD_GATEWAY

The HTTP response status code: 502 Bad Gateway

STATUS_SERVICE_UNAVAILABLE

The HTTP response status code: 503 Service Unavailable

STATUS_GATEWAY_TIMEOUT

The HTTP response status code: 504 Gateway Timeout

STATUS_HTTP_VERSION_NOT_SUPPORTED

The HTTP response status code: 505 HTTP Version Not Supported

KEEPALIVE_AUTO

Decides to keep the connection alive or not based on the connection header of the client request }

KEEPALIVE_ALWAYS

Keeps the connection alive irrespective of the connection header value }

KEEPALIVE_NEVER

Closes the connection irrespective of the connection header value }

SERVICE_NAME

Constant for the service name reference.

RESOURCE_NAME

Constant for the resource name reference.

REQUEST_METHOD

Constant for the request method reference.

CONNECTION_CLOSURE_ERROR

Error reason for failures during connection closure

INVALID_HANDSHAKE_ERROR

Error reason for WebSocket handshake failures

PAYLOAD_TOO_BIG_ERROR

Error reason for exceeding maximum frame size

PROTOCOL_ERROR

Error reason for other side breaking the protocol

CONNECTION_ERROR

Error reason for connection failures

INVALID_CONTINUATION_FRAME_ERROR

Error reason for invalid continuation frame

GENERIC_ERROR

Error reason for errors not captured by the specific errors

Annotations

ResourceConfig

The annotation which is used to configure an HTTP resource.

ServiceConfig

The annotation which is used to configure an HTTP service.

WebSocketServiceConfig

The annotation which is used to configure a WebSocket service.

Types

CachingPolicy

Used for configuring the caching behaviour. Setting the policy field in the CacheConfig record allows the user to control the caching behaviour.

Chunking

Defines the possible values for the chunking configuration in HTTP services and clients.

AUTO: If the payload is less than 8KB, content-length header is set in the outbound request/response, otherwise chunking header is set in the outbound request/response ALWAYS: Always set chunking header in the response NEVER: Never set the chunking header even if the payload is larger than 8KB in the outbound request/response

CircuitState

A finite type for modeling the states of the Circuit Breaker. The Circuit Breaker starts in the CLOSED state. If any failure thresholds are exceeded during execution, the circuit trips and goes to the OPEN state. After the specified timeout period expires, the circuit goes to the HALF_OPEN state. If the trial request sent while in the HALF_OPEN state succeeds, the circuit goes back to the CLOSED state.

ClientAuthError

Defines the Auth error types that returned from client

ClientError

Defines the possible client error types

Compression

Options to compress using gzip or deflate.

AUTO: When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the outbound request/response accept-encoding/content-encoding option ALWAYS: Always set accept-encoding/content-encoding in outbound request/response NEVER: Never set accept-encoding/content-encoding header in outbound request/response

CredentialBearer

Specifies how to send the authentication credentials when exchanging tokens.

HttpOperation

Defines the HTTP operations related to circuit breaker, failover and load balancer.

FORWARD: Forward the specified payload GET: Request a resource POST: Create a new resource DELETE: Deletes the specified resource OPTIONS: Request communication options available PUT: Replace the target resource PATCH: Apply partial modification to the resource HEAD: Identical to GET but no resource body should be returned SUBMIT: Submits a http request and returns an HttpFuture object NONE: No operation should be performed

HttpVersion

Defines the supported HTTP protocols.

HTTP_1_0: HTTP/1.0 protocol HTTP_1_1: HTTP/1.1 protocol HTTP_2_0: HTTP/2.0 protocol

InboundRequestError

Defines the listener error types that returned while receiving inbound request

InboundResponseError

Defines the client error types that returned while receiving inbound response

KeepAlive

Defines the possible values for the keep-alive configuration in service and client endpoints.

ListenerError

Defines the possible listener error types

MutualSslStatus

Defines the possible values for the mutual ssl status.

passed: Mutual SSL handshake is successful. failed: Mutual SSL handshake has failed.

OutboundRequestError

Defines the client error types that returned while sending outbound request

OutboundResponseError

Defines the listener error types that returned while sending outbound response

RedirectCode

Defines the HTTP redirect codes as a type.

RequestMessage

The types of messages that are accepted by HTTP client when sending out the outbound request.

ResiliencyError

Defines the resiliency error types that returned from client

ResponseMessage

The types of messages that are accepted by HTTP listener when sending out the outbound response.

WebSocketError

The union of all the WebSocket related errors

Errors

AllLoadBalanceEndpointsFailedError

Represents a client error that occurred due to all the load balance endpoint failure

AllRetryAttemptsFailed

Represents a client error that occurred due to all the the retry attempts failure

AuthenticationError

Represents a listener error that occurred due to inbound request authentication failure

AuthorizationError

Represents a listener error that occurred due to inbound request authorization failure

FailoverActionFailedError

Represents a client error that occurred due to failover action failure

FailoverAllEndpointsFailedError

Represents a client error that occurred due to all the failover endpoint failure

GenericClientError

Represents a generic client error

GenericListenerError

Represents a generic listener error

Http2ClientError

Represents an HTTP/2 client generic error

IdleTimeoutError

Represents the error that triggered upon a request/response idle timeout

InitializingInboundRequestError

Represents a listener error that occurred due to inbound request initialization failure

InitializingInboundResponseError

Represents a client error that occurred due to inbound response initialization failure

InitializingOutboundRequestError

Represents a client error that occurred due to outbound request initialization failure

InitializingOutboundResponseError

Represents a listener error that occurred due to outbound response initialization failure

Initiating100ContinueResponseError

Represents an error that occurred due to 100 continue response initialization failure

LoadBalanceActionError
MaximumWaitTimeExceededError

Represents a client error that occurred exceeding maximum wait time

ReadingInboundRequestBodyError

Represents a listener error that occurred while writing the inbound request entity body

ReadingInboundRequestHeadersError

Represents a listener error that occurred while reading inbound request headers

ReadingInboundResponseBodyError

Represents a client error that occurred while reading inbound response entity body

ReadingInboundResponseHeadersError

Represents a client error that occurred while reading inbound response headers

SslError

Represents a client error that occurred due to SSL failure

UnsupportedActionError

Represents a client error that occurred due to unsupported action invocation

UpstreamServiceUnavailableError

Represents a client error that occurred due to upstream service unavailability

Writing100ContinueResponseError

Represents an error that occurred while writing 100 continue response

WritingOutboundRequestBodyError

Represents a client error that occurred while writing outbound request entity body

WritingOutboundRequestHeadersError

Represents a client error that occurred while writing outbound request headers

WritingOutboundResponseBodyError

Represents a listener error that occurred while writing outbound response entity body

WritingOutboundResponseHeadersError

Represents a listener error that occurred while writing outbound response headers

WsConnectionClosureError

Raised during failures in connection closure

WsConnectionError

Raised during connection failures

WsGenericError

Raised for errors not captured by the specific errors

WsInvalidContinuationFrameError

Raised when an out of order/invalid continuation frame is received

WsInvalidHandshakeError

Raised during the handshake when the WebSocket upgrade fails

WsPayloadTooBigError

Raised when receiving a frame with a payload exceeding the maximum size

WsProtocolError

Raised when the other side breaks the protocol