ballerina/http module

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 Certificate Revocation List (CRL), Online Certificate Status Protocol (OCSP) and OCSP Stapling for SSL/TLS connection. They also support HTTP2, keep-alive, chunking, HTTP caching, and data compression/decompression.

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, endpoint 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.

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 Server Name Indication (SNI) and Application Layer Protocol Negotiation (ALPN). Listener endpoints also support Certificate Revocation List (CRL), Online Certificate Status Protocol (OCSP), OCSP Stapling, HTTP2, keep-alive, chunking, HTTP caching, and data compression/decompression.

See Mutual SSL Example.

See Caching Example, HTTP Disable Chunking Example.

WebSocket

The module also provides support for WebSocket. 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 WebSocket. 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. idleTimeout has to be configured by the user in either the WebSocket service or 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.

See WebSocket Basic Example, HTTP to WebSocket Upgrade Example, WebSocket Chat Application, WebSocket Proxy Server

Logging

This module supports two types of logs:

  • HTTP access logs: These are standard HTTP access logs that are formatted using the combined log format and logged at the INFO level. Logs can be published to the console or a file using the following configurations:
    • b7a.http.accesslog.console=true
    • b7a.http.accesslog.path=<path_to_log_file>
  • HTTP trace logs: These are detailed logs of requests coming to/going out of and responses coming to/going out of service endpoints or a client endpoints. Trace logs can be published to the console, to a file or to a network socket using the following set of configurations:
    • b7a.http.tracelog.console=true
    • b7a.http.tracelog.path=<path_to_log_file>
    • b7a.http.tracelog.host=<host_name>
    • b7a.http.tracelog.port=<port>

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

See HTTP Access Logs Example, HTTP Trace Logs Example

Samples

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");

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 " + untaint name + ". " + untaint message);
       // Sends the response back to the client.
       var result = caller->respond(res);
       if (result is error) {
            log:printError("Error sending response", err = result);
       }
   }
}

Type Definitions

Type Values Description
AuthStoreProvider LDAP_AUTH_STORE | CONFIG_AUTH_STORE

Authentication storage providers for BasicAuth scheme.

CachingPolicy RFC_7234 | CACHE_CONTROL_AND_VALIDATORS

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

Chunking CHUNKING_NEVER | CHUNKING_AUTO | CHUNKING_ALWAYS

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 CB_OPEN_STATE | CB_HALF_OPEN_STATE | CB_CLOSED_STATE

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.

Compression COMPRESSION_NEVER | COMPRESSION_AUTO | COMPRESSION_ALWAYS

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 POST_BODY_BEARER | NO_BEARER | AUTH_HEADER_BEARER

Specifies how to send the authentication credentials when exchanging tokens.

HttpOperation HTTP_PUT | HTTP_POST | HTTP_PATCH | HTTP_OPTIONS | HTTP_NONE | HTTP_HEAD | HTTP_GET | HTTP_FORWARD | HTTP_DELETE

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 NONE: No operation should be performed

InboundAuthScheme JWT_AUTH | BASIC_AUTH

Inbound authentication schemes.

KeepAlive KEEPALIVE_NEVER | KEEPALIVE_AUTO | KEEPALIVE_ALWAYS

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

MutualSslStatus null | PASSED | FAILED

Defines the possible values for the mutual ssl status.

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

OAuth2GrantType PASSWORD_GRANT | DIRECT_TOKEN | CLIENT_CREDENTIALS_GRANT

Specifies the type of the OAuth2 grant type

OutboundAuthScheme OAUTH2 | JWT_AUTH | BASIC_AUTH

Outbound authentication schemes.

RedirectCode REDIRECT_USE_PROXY_305 | REDIRECT_TEMPORARY_REDIRECT_307 | REDIRECT_SEE_OTHER_303 | REDIRECT_PERMANENT_REDIRECT_308 | REDIRECT_NOT_MODIFIED_304 | REDIRECT_MULTIPLE_CHOICES_300 | REDIRECT_MOVED_PERMANENTLY_301 | REDIRECT_FOUND_302

Defines the HTTP redirect codes as a type.

RequestMessage xml | string | null | json | io:ReadableByteChannel | byte[] | Request | Entity[]

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

ResponseMessage xml | string | null | json | io:ReadableByteChannel | byte[] | Response | Entity[]

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

Annotations

Name Attachement Points Data Type Description
ResourceConfig resource HttpResourceConfig

The annotation which is used to configure an HTTP resource.

ServiceConfig service HttpServiceConfig

The annotation which is used to configure an HTTP service.

WebSocketServiceConfig service WSServiceConfig

The annotation which is used to configure a WebSocket service.

Records Summary

Record Description
AuthCacheConfig Provides a set of configurations for controlling the authorization caching behaviour of the endpoint.
AuthConfig The `AuthConfig` record can be used to configure the authentication mechanism used by the HTTP endpoint.
AuthProvider Configuration for authentication providers.
Authentication Can be used for enabling/disabling authentication in an HTTP service.
BasicAuthConfig The `BasicAuthConfig` record can be used to configure Basic Authentication used by the HTTP 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.
CachedToken The `CachedToken` stores the values received from the authorization/token server to use them for the latter requests without requesting tokens again.
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.
ClientCredentialsGrantConfig The `ClientCredentialsGrantConfig` record can be used to configue OAuth2 client credentials grant type.
ClientEndpointConfig Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
CompressionConfig A record for providing configurations for content compression.
CorsConfig Configurations for CORS support.
DirectTokenConfig The `DirectTokenConfig` record configures the access token directly.
DirectTokenRefreshConfig The `DirectTokenRefreshConfig` record passes the configurations for refreshing the access token for the grant type of the direct token grant type.
FailoverClientEndpointConfiguration 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.
JwtAuthConfig The `JwtAuthConfig` record can be used to configure JWT based authentication used by the HTTP endpoint.
ListenerAuthConfig Configures the authentication scheme for a service or a resource.
LoadBalanceActionErrorData Represents an error occurred in an remote function of the Load Balance connector.
LoadBalanceClientEndpointConfiguration 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.
OAuth2AuthConfig The `OAuth2AuthConfig` record can be used to configure OAuth2 based authentication used by the HTTP endpoint.
PasswordGrantConfig The `PasswordGrantConfig` record can be used to configue OAuth2 password grant type
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.
RefreshConfig The `RefreshConfig` record can be used to pass the configurations for refreshing the access token of password grant type.
Remote Presents a read-only view of the remote address.
RequestLimits Configures limits for requests. If these limits are violated, the request is rejected.
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.
SecureSocket Provides configurations for facilitating secure communication with a remote HTTP endpoint.
ServiceEndpointConfiguration Provides a set of configurations for HTTP service endpoints.
ServiceOcspStapling A record for providing configurations for certificate revocation status checks.
ServiceSecureSocket Configures the SSL/TLS options to be used for HTTP service.
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.
WebSocketClientEndpointConfig Configuration for the WebSocket client endpoint.
WebSocketUpgradeConfig Resource configuration to upgrade from HTTP to WebSocket.

Objects Summary

Object Description
AuthHandlerRegistry

Representation of the Http Auth Handler Registry.

AuthnFilter

Representation of the Authentication filter.

AuthnHandlerChain

Representation of Authentication handler chain

AuthzFilter

Representation of the Authorization filter

CircuitBreakerClient

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

Filter

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

FilterContext

Representation of request filter Context.

HttpAuthnHandler

Representation of Authentication handler for HTTP traffic.

HttpAuthzHandler

Representation of Authorization Handler for HTTP

HttpBasicAuthnHandler

Defines Basic Auth handler for HTTP traffic.

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

HttpJwtAuthnHandler

Representation of JWT Auth handler for HTTP traffic

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.

LoadBalancerRounRobinRule

Implementation of round robin load balancing strategy.

LoadBalancerRule

LoadBalancerRule provides a required interfaces to implement different algorithms.

MockListener

Mock server endpoint which does not open a listening port.

PushPromise

Represents an HTTP/2 PUSH_PROMISE frame.

Request

Represents an HTTP request.

RequestCacheControl

Configures cache control directives for a Request.

Response

Represents an HTTP response.

ResponseCacheControl

Configures cache control directives for a Response.

WebSocketListener

Represents a WebSocket service endpoint.

Endpoints Summary

Endpoint Description
Caller

The caller actions for responding to client requests.

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.

HttpCaller

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.

HttpClient

Provides the HTTP remote functions 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 remote functions 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.

Functions Summary

Return Type Function and Description
Client|error<> createHttpCachingClient(string url, http:ClientEndpointConfig config, http:CacheConfig cacheConfig)

Creates an HTTP client capable of caching HTTP responses.

Client|error<> createHttpSecureClient(string url, http:ClientEndpointConfig config)

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

string|error<> decode(string url, string charset)

Decodes the given URL.

string|error<> encode(string url, string charset)

Encodes the given URL.

string|null extractBasicAuthHeaderValue(http:Request req)

Extracts the basic authentication header value from the request.

Response|error<> invokeEndpoint(string path, http:Request outRequest, FORWARD|GET|POST|DELETE|OPTIONS|PUT|PATCH|HEAD|NONE requestAction, http:Client httpClient)

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

(string,map<any>)|error<> parseHeader(string headerValue)

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

Constants

Name Data Type Value Description
AUTH_HEADER string Authorization

Authentication header name.

AUTH_SCHEME_BASIC string Basic

Basic authentication scheme.

AUTH_SCHEME_BEARER string Bearer

Bearer authentication scheme.

BASIC_AUTH BASIC_AUTH

Basic authentication scheme.

OAUTH2 OAUTH2

OAuth2 authentication scheme.

JWT_AUTH JWT_AUTH

JWT authentication scheme.

CONFIG_AUTH_STORE CONFIG_AUTH_STORE

Configuration file based authentication storage.

LDAP_AUTH_STORE LDAP_AUTH_STORE

LDAP based authentication storage.

NO_CACHE string no-cache

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

NO_STORE string no-store

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

NO_TRANSFORM string no-transform

Instructs intermediaries not to transform the payload.

MAX_AGE string 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 string 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 string min-fresh

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

ONLY_IF_CACHED string 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 string 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 string public

Indicates that any cache may store the response.

PRIVATE string private

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

PROXY_REVALIDATE string proxy-revalidate

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

S_MAX_AGE string s-maxage

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

MAX_STALE_ANY_AGE int 9223372036854775807

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

CACHE_CONTROL_AND_VALIDATORS 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 RFC_7234

Caching behaviour is as specified by the RFC 7234 specification.

HTTP_ERROR_CODE string {ballerina/http}HTTPError

Constant for the http error code

MULTIPART_AS_PRIMARY_TYPE string multipart/

Represents multipart primary type

HTTP_FORWARD FORWARD

Constant for the HTTP FORWARD method

HTTP_GET GET

Constant for the HTTP GET method

HTTP_POST POST

Constant for the HTTP POST method

HTTP_DELETE DELETE

Constant for the HTTP DELETE method

HTTP_OPTIONS OPTIONS

Constant for the HTTP OPTIONS method

HTTP_PUT PUT

Constant for the HTTP PUT method

HTTP_PATCH PATCH

Constant for the HTTP PATCH method

HTTP_HEAD HEAD

Constant for the HTTP HEAD method

HTTP_NONE NONE

Constant for the identify not an HTTP Operation

CHUNKING_AUTO 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

Always set chunking header in the response.

CHUNKING_NEVER NEVER

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

COMPRESSION_AUTO 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

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

COMPRESSION_NEVER NEVER

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

REDIRECT_MULTIPLE_CHOICES_300 300

Represents the HTTP redirect status code 300 - Multiple Choices.

REDIRECT_MOVED_PERMANENTLY_301 301

Represents the HTTP redirect status code 301 - Moved Permanently.

REDIRECT_FOUND_302 302

Represents the HTTP redirect status code 302 - Found.

REDIRECT_SEE_OTHER_303 303

Represents the HTTP redirect status code 303 - See Other.

REDIRECT_NOT_MODIFIED_304 304

Represents the HTTP redirect status code 304 - Not Modified.

REDIRECT_USE_PROXY_305 305

Represents the HTTP redirect status code 305 - Use Proxy.

REDIRECT_TEMPORARY_REDIRECT_307 307

Represents the HTTP redirect status code 307 - Temporary Redirect.

REDIRECT_PERMANENT_REDIRECT_308 308

Represents the HTTP redirect status code 308 - Permanent Redirect.

AGE string age

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

AUTHORIZATION string authorization

HTTP header key authorization

CACHE_CONTROL string cache-control

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

CONTENT_LENGTH string content-length

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

CONTENT_TYPE string content-type

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

DATE string date

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

ETAG string 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 string expect

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

EXPIRES string expires

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

IF_MATCH string if-match

HTTP header key if-match

IF_MODIFIED_SINCE string 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 string 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 string if-range

HTTP header key if-range

IF_UNMODIFIED_SINCE string if-unmodified-since

HTTP header key if-unmodified-since

LAST_MODIFIED string last-modified

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

LOCATION string location

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

PRAGMA string pragma

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

SERVER string server

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

WARNING string warning

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

TRANSFER_ENCODING string transfer-encoding

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

PASSED passed

Mutual SSL handshake is succesful.

FAILED failed

Mutual SSL handshake has failed.

NONE ()

Not a mutual ssl connection.

AUTH_HEADER_BEARER AUTH_HEADER_BEARER

Indicates that the authentication credentials should be sent via the Authentication Header

POST_BODY_BEARER POST_BODY_BEARER

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

NO_BEARER NO_BEARER

Indicates that the authentication credentials should not be sent

CLIENT_CREDENTIALS_GRANT CLIENT_CREDENTIALS_GRANT

Indicates OAuth2 client credentials grant type

PASSWORD_GRANT PASSWORD_GRANT

Indicates OAuth2 password grant type

DIRECT_TOKEN DIRECT_TOKEN

Indicates direct token as a grant type, where this is considered as a custom way of providing access tokens by the user

CB_OPEN_STATE OPEN

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

CB_HALF_OPEN_STATE HALF_OPEN

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 CLOSED

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.

CONTINUE_100 int 100

The HTTP response status code: 100 Continue

SWITCHING_PROTOCOLS_101 int 101

The HTTP response status code: 101 Switching Protocols

OK_200 int 200

The HTTP response status code: 200 OK

CREATED_201 int 201

The HTTP response status code: 201 Created

ACCEPTED_202 int 202

The HTTP response status code: 202 Accepted

NON_AUTHORITATIVE_INFORMATION_203 int 203

The HTTP response status code: 203 Non Authoritative Information

NO_CONTENT_204 int 204

The HTTP response status code: 204 No Content

RESET_CONTENT_205 int 205

The HTTP response status code: 205 Reset Content

PARTIAL_CONTENT_206 int 206

The HTTP response status code: 206 Partial Content

MULTIPLE_CHOICES_300 int 300

The HTTP response status code: 300 Multiple Choices

MOVED_PERMANENTLY_301 int 301

The HTTP response status code: 301 Moved Permanently

FOUND_302 int 302

The HTTP response status code: 302 Found

SEE_OTHER_303 int 303

The HTTP response status code: 303 See Other

NOT_MODIFIED_304 int 304

The HTTP response status code: 304 Not Modified

USE_PROXY_305 int 305

The HTTP response status code: 305 Use Proxy

TEMPORARY_REDIRECT_307 int 307

The HTTP response status code: 307 Temporary Redirect

PERMANENT_REDIRECT_308 int 308

The HTTP response status code: 308 Permanent Redirect

BAD_REQUEST_400 int 400

The HTTP response status code: 400 Bad Request

UNAUTHORIZED_401 int 401

The HTTP response status code: 401 Unauthorized

PAYMENT_REQUIRED_402 int 402

The HTTP response status code: 402 Payment Required

FORBIDDEN_403 int 403

The HTTP response status code: 403 Forbidden

NOT_FOUND_404 int 404

The HTTP response status code: 404 Not Found

METHOD_NOT_ALLOWED_405 int 405

The HTTP response status code: 405 Method Not Allowed

NOT_ACCEPTABLE_406 int 406

The HTTP response status code: 406 Not Acceptable

PROXY_AUTHENTICATION_REQUIRED_407 int 407

The HTTP response status code: 407 Proxy Authentication Required

REQUEST_TIMEOUT_408 int 408

The HTTP response status code: 408 Request Timeout

CONFLICT_409 int 409

The HTTP response status code: 409 Conflict

GONE_410 int 410

The HTTP response status code: 410 Gone

LENGTH_REQUIRED_411 int 411

The HTTP response status code: 411 Length Required

PRECONDITION_FAILED_412 int 412

The HTTP response status code: 412 Precondition Failed

PAYLOAD_TOO_LARGE_413 int 413

The HTTP response status code: 413 Payload Too Large

URI_TOO_LONG_414 int 414

The HTTP response status code: 414 URI Too Long

UNSUPPORTED_MEDIA_TYPE int 415

The HTTP response status code: 415 Unsupported Media Type

RANGE_NOT_SATISFIABLE_416 int 416

The HTTP response status code: 416 Range Not Satisfiable

EXPECTATION_FAILED_417 int 417

The HTTP response status code: 417 Expectation Failed

UPGRADE_REQUIRED_426 int 426

The HTTP response status code: 426 Upgrade Required

INTERNAL_SERVER_ERROR_500 int 500

The HTTP response status code: 500 Internal Server Error

NOT_IMPLEMENTED_501 int 501

The HTTP response status code: 501 Not Implemented

BAD_GATEWAY_502 int 502

The HTTP response status code: 502 Bad Gateway

SERVICE_UNAVAILABLE_503 int 503

The HTTP response status code: 503 Service Unavailable

GATEWAY_TIMEOUT_504 int 504

The HTTP response status code: 504 Gateway Timeout

HTTP_VERSION_NOT_SUPPORTED_505 int 505

The HTTP response status code: 505 HTTP Version Not Supported

KEEPALIVE_AUTO AUTO

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

KEEPALIVE_ALWAYS ALWAYS

Keeps the connection alive irrespective of the connection header value }

KEEPALIVE_NEVER NEVER

Closes the connection irrespective of the connection header value }

public type AuthCacheConfig record

Provides a set of configurations for controlling the authorization caching behaviour of the endpoint.

Field Name Data Type Default Value Description
enabled boolean true

Specifies whether authorization caching is enabled. Caching is enabled by default.

capacity int 100

The capacity of the cache

expiryTimeMillis int 5 * 1000

The number of milliseconds to keep an entry in the cache

evictionFactor float 1.0

The fraction of entries to be removed when the cache is full. The value should be between 0 (exclusive) and 1 (inclusive).

public type AuthConfig record

The `AuthConfig` record can be used to configure the authentication mechanism used by the HTTP endpoint.

Field Name Data Type Default Value Description
scheme BASIC_AUTH|OAUTH2|JWT_AUTH

Authentication scheme

config http:BasicAuthConfig|http:OAuth2AuthConfig|http:JwtAuthConfig

Configuration related to the selected authenticator.

public type AuthProvider record

Configuration for authentication providers.

Field Name Data Type Default Value Description
id string

Authentication provider instance id

scheme BASIC_AUTH|JWT_AUTH? ()

Authentication scheme

authStoreProvider CONFIG_AUTH_STORE|LDAP_AUTH_STORE? ()

Authentication store provider (Config, LDAP, etc.) implementation

config auth:LdapAuthProviderConfig|auth:ConfigAuthProviderConfig|auth:JWTAuthProviderConfig? ()

Configuration related to the selected authentication provider.

public type Authentication record

Can be used for enabling/disabling authentication in an HTTP service.

Field Name Data Type Default Value Description
enabled boolean false

Specifies whether authentication is enabled

public type BasicAuthConfig record

The `BasicAuthConfig` record can be used to configure Basic Authentication used by the HTTP endpoint.

Field Name Data Type Default Value Description
username string

Username for Basic authentication

password string

Password for Basic authentication

public type Bucket record

Represents a discrete sub-part of the time window (Bucket).

Field Name Data Type Default Value Description
totalCount int 0

Total number of requests received during the sub-window time frame

failureCount int 0

Number of failed requests during the sub-window time frame

rejectedCount int 0

Number of rejected requests during the sub-window time frame

lastUpdatedTime time:Time

The time that the Bucket is last updated.

public type CacheConfig record

Provides a set of configurations for controlling the caching behaviour of the endpoint.

Field Name Data Type Default Value Description
enabled boolean true

Specifies whether HTTP caching is enabled. Caching is enabled by default.

isShared boolean false

Specifies whether the HTTP caching layer should behave as a public cache or a private cache

expiryTimeMillis int 86400

The number of milliseconds to keep an entry in the cache

capacity int 8388608

The capacity of the cache

evictionFactor float 0.2

The fraction of entries to be removed when the cache is full. The value should be between 0 (exclusive) and 1 (inclusive).

policy CACHE_CONTROL_AND_VALIDATORS|RFC_7234 CACHE_CONTROL_AND_VALIDATORS

Gives the user some control over the caching behaviour. By default, this is set to CACHE_CONTROL_AND_VALIDATORS. The default behaviour is to allow caching only when the cache-control header and either the etag or last-modified header are present.

public type CachedToken record

The `CachedToken` stores the values received from the authorization/token server to use them for the latter requests without requesting tokens again.

Field Name Data Type Default Value Description
accessToken string

Access token for the authorization server

refreshToken string

Refresh token for the refresh token server

expiryTime int

Expiry time of the access token in milliseconds

public type CircuitBreakerConfig record

Provides a set of configurations for controlling the behaviour of the Circuit Breaker.

Field Name Data Type Default Value Description
rollingWindow http:RollingWindow {}

RollingWindow options of the CircuitBreaker

failureThreshold float 0.0

The threshold for request failures. When this threshold exceeds, the circuit trips. The threshold should be a value between 0 and 1.

resetTimeMillis int 0

The time period(in milliseconds) to wait before attempting to make another request to the upstream service

statusCodes int[] []

Array of HTTP response status codes which are considered as failures

public type CircuitBreakerInferredConfig record

Derived set of configurations from the `CircuitBreakerConfig`.

Field Name Data Type Default Value Description
failureThreshold float 0.0

The threshold for request failures. When this threshold exceeds, the circuit trips. The threshold should be a value between 0 and 1

resetTimeMillis int 0

The time period(in milliseconds) to wait before attempting to make another request to the upstream service

statusCodes boolean[] []

Array of HTTP response status codes which are considered as failures

noOfBuckets int 0

Number of buckets derived from the RollingWindow

rollingWindow http:RollingWindow {}

RollingWindow options provided in the CircuitBreakerConfig

public type CircuitHealth record

Maintains the health of the Circuit Breaker.

Field Name Data Type Default Value Description
lastRequestSuccess boolean false

Whether last request is success or not

totalRequestCount int 0

Total request count received within the RollingWindow

lastUsedBucketId int 0

ID of the last bucket used in Circuit Breaker calculations

startTime time:Time time:currentTime()

Circuit Breaker start time

lastRequestTime time:Time

The time that the last request received

lastErrorTime time:Time

The time that the last error occurred

lastForcedOpenTime time:Time

The time that circuit forcefully opened at last

totalBuckets http:Bucket?[] []

The discrete time buckets into which the time window is divided

public type ClientCredentialsGrantConfig record

The `ClientCredentialsGrantConfig` record can be used to configue OAuth2 client credentials grant type.

Field Name Data Type Default Value Description
tokenUrl string

Token URL for the authorization server

clientId string

Client ID for the client credentials grant authentication

clientSecret string

Client secret for the client credentials grant authentication

scopes string[]

Scope of the access request

clockSkew int 0

Clock skew in seconds

retryRequest boolean true

Retry the request if the initial request returns a 401 response

credentialBearer AUTH_HEADER_BEARER|POST_BODY_BEARER|NO_BEARER AUTH_HEADER_BEARER

How authentication credentials are sent to the authorization server

public type ClientEndpointConfig record

Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.

Field Name Data Type Default Value Description
circuitBreaker http:CircuitBreakerConfig? ()

Configurations associated with Circuit Breaker behaviour

timeoutMillis int 60000

The maximum time to wait (in milliseconds) for a response before closing the connection

keepAlive AUTO|ALWAYS|NEVER KEEPALIVE_AUTO

Specifies whether to reuse a connection for multiple requests

chunking AUTO|ALWAYS|NEVER AUTO

The chunking behaviour of the request

httpVersion string 1.1

The HTTP version understood by the client

forwarded string disable

The choice of setting forwarded/x-forwarded header

followRedirects http:FollowRedirects? ()

Configurations associated with Redirection

retryConfig http:RetryConfig? ()

Configurations associated with Retry

proxy http:ProxyConfig? ()

Proxy server related options

poolConfig http:PoolConfiguration? ()
secureSocket http:SecureSocket? ()

SSL/TLS related options

cache http:CacheConfig {}

HTTP caching related configurations

compression AUTO|ALWAYS|NEVER COMPRESSION_AUTO

Specifies the way of handling compression (accept-encoding) header

auth http:AuthConfig? ()

HTTP authentication related configurations

public type CompressionConfig record

A record for providing configurations for content compression.

Field Name Data Type Default Value Description
enable AUTO|ALWAYS|NEVER COMPRESSION_AUTO

The status of compression

contentTypes string[] []

Content types which are allowed for compression

public type CorsConfig record

Configurations for CORS support.

Field Name Data Type Default Value Description
allowHeaders string[] []

The array of allowed headers by the service

allowMethods string[] []

The array of allowed methods by the service

allowOrigins string[] []

The array of origins with which the response is shared by the service

exposeHeaders string[] []

The whitelisted headers which clients are allowed to access

allowCredentials boolean false

Specifies whether credentials are required to access the service

maxAge int -1

The maximum duration to cache the preflight from client side

public type DirectTokenConfig record

The `DirectTokenConfig` record configures the access token directly.

Field Name Data Type Default Value Description
accessToken string

Access token for the authorization server

refreshConfig http:DirectTokenRefreshConfig

Configurations for refreshing the access token

clockSkew int 0

Clock skew in seconds

retryRequest boolean true

Retry the request if the initial request returns a 401 response

credentialBearer AUTH_HEADER_BEARER|POST_BODY_BEARER|NO_BEARER AUTH_HEADER_BEARER

How authentication credentials are sent to the authorization server

public type DirectTokenRefreshConfig record

The `DirectTokenRefreshConfig` record passes the configurations for refreshing the access token for the grant type of the direct token grant type.

Field Name Data Type Default Value Description
refreshUrl string

Refresh token URL for the refresh token server

refreshToken string

Refresh token for the refresh token server

clientId string

Client ID for authentication with the authorization server

clientSecret string

Client secret for authentication with the authorization server

scopes string[]

Scope of the access request

credentialBearer AUTH_HEADER_BEARER|POST_BODY_BEARER|NO_BEARER AUTH_HEADER_BEARER

How authentication credentials are sent to the authorization server

public type FailoverClientEndpointConfiguration record

Provides a set of HTTP related configurations and failover related configurations.

Field Name Data Type Default Value Description
circuitBreaker http:CircuitBreakerConfig? ()

Circuit Breaker behaviour configurations

timeoutMillis int 60000

The maximum time to wait (in milliseconds) for a response before closing the connection

httpVersion string 1.1

The HTTP version supported by the endpoint

forwarded string disable

The choice of setting forwarded/x-forwarded header

keepAlive AUTO|ALWAYS|NEVER KEEPALIVE_AUTO

Specifies whether to reuse a connection for multiple requests

chunking AUTO|ALWAYS|NEVER AUTO

The chunking behaviour of the request

followRedirects http:FollowRedirects? ()

Redirect related options

retryConfig http:RetryConfig? ()

Retry related options

proxy http:ProxyConfig? ()

Proxy related options

poolConfig http:PoolConfiguration? ()
targets http:TargetService[] []

The upstream HTTP endpoints among which the incoming HTTP traffic load should be sent on failover

cache http:CacheConfig {}

The configurations for controlling the caching behaviour

compression AUTO|ALWAYS|NEVER COMPRESSION_AUTO

Specifies the way of handling compression (accept-encoding) header

auth http:AuthConfig? ()

HTTP authentication releated configurations

failoverCodes int[] [501, 502, 503, 504]

Array of HTTP response status codes for which the failover behaviour should be triggered

intervalMillis int 0

Failover delay interval in milliseconds

public type FailoverConfig record

Provides a set of configurations for controlling the failover behaviour of the endpoint.

Field Name Data Type Default Value Description
failoverCodes int[] []

Array of HTTP response status codes for which the failover mechanism triggers

interval int 0

Failover delay interval in milliseconds

public type FailoverInferredConfig record

Inferred failover configurations passed into the failover client.

Field Name Data Type Default Value Description
failoverClientsArray http:Client?[] []

Array of HTTP Clients that needs to be Failover

failoverCodesIndex boolean[] []

An indexed array of HTTP response status codes for which the failover mechanism triggers

failoverInterval int 0

Failover delay interval in milliseconds

public type FollowRedirects record

Provides configurations for controlling the endpoint's behaviour in response to HTTP redirect related responses.

Field Name Data Type Default Value Description
enabled boolean false

Enable/disable redirection

maxCount int 5

Maximum number of redirects to follow

public type HttpResourceConfig record

Configuration for an HTTP resource.

Field Name Data Type Default Value Description
methods string[] []

The array of allowed HTTP methods

path string

The path of resource

body string

Inbound request entity body name which declared in signature

consumes string[] []

The media types which are accepted by resource

produces string[] []

The media types which are produced by resource

cors http:CorsConfig {}

The cross origin resource sharing configurations for the resource. If not set, the resource will inherit the CORS behaviour of the enclosing service.

transactionInfectable boolean true

Allow to participate in the distributed transactions if value is true

webSocketUpgrade http:WebSocketUpgradeConfig? ()

Annotation to define HTTP to WebSocket upgrade

authConfig http:ListenerAuthConfig? ()

Authentication Configs to secure the resource

public type HttpServiceConfig record

Contains the configurations for an HTTP service.

Field Name Data Type Default Value Description
endpoints http:Listener?[] []

An array of endpoints the service would be attached to

host string b7a.default

Domain name of the service

basePath string

Service base path

compression http:CompressionConfig {}

The status of compression

chunking AUTO|ALWAYS|NEVER CHUNKING_AUTO

Configures the chunking behaviour for the service

cors http:CorsConfig {}

The cross origin resource sharing configurations for the service

versioning http:Versioning {}

The version of the service to be used

authConfig http:ListenerAuthConfig? {}

Authentication configurations for securing the service

public type HttpTimeoutError record

Defines a timeout error occurred during service invocation.

Field Name Data Type Default Value Description
message string

An explanation on what went wrong

cause error? ()

The error which caused the HttpTimeoutError

statusCode int 0

HTTP status code

public type JwtAuthConfig record

The `JwtAuthConfig` record can be used to configure JWT based authentication used by the HTTP endpoint.

Field Name Data Type Default Value Description
inferredJwtIssuerConfig auth:InferredJwtIssuerConfig

JWT issuer configuration used to issue JWT with specific configuration

public type ListenerAuthConfig record

Configures the authentication scheme for a service or a resource.

Field Name Data Type Default Value Description
authentication http:Authentication? ()

Enables/disables authentication

authProviders string[]? ()

Array of authentication provider IDs

scopes string[]? ()

Array of scopes

public type LoadBalanceActionErrorData record

Represents an error occurred in an remote function of the Load Balance connector.

Field Name Data Type Default Value Description
message string

An error message explaining about the error

statusCode int 0

HTTP status code of the LoadBalanceActionError

httpActionErr error?[] []

Array of errors occurred at each endpoint

public type LoadBalanceClientEndpointConfiguration record

The configurations related to the load balance client endpoint.

Field Name Data Type Default Value Description
circuitBreaker http:CircuitBreakerConfig? ()

Circuit Breaker configuration

timeoutMillis int 60000

The maximum time to wait (in milli seconds) for a response before closing the connection

httpVersion string 1.1

The HTTP version to be used to communicate with the endpoint

forwarded string disable

The choice of setting forwarded/x-forwarded header

keepAlive AUTO|ALWAYS|NEVER KEEPALIVE_AUTO

Specifies whether to keep the connection alive (or not) for multiple request/response pairs

chunking AUTO|ALWAYS|NEVER AUTO

The chunking behaviour of the request

followRedirects http:FollowRedirects? ()

Redirect related options

retryConfig http:RetryConfig? ()

Retry related options

proxy http:ProxyConfig? ()

Proxy related options

poolConfig http:PoolConfiguration? ()
targets http:TargetService[] []

The upstream HTTP endpoints among which the incoming HTTP traffic load should be distributed

cache http:CacheConfig {}

The configurations for controlling the caching behaviour

compression AUTO|ALWAYS|NEVER COMPRESSION_AUTO

Specifies the way of handling compression (accept-encoding) header

auth http:AuthConfig? ()

HTTP authentication releated configurations

lbRule http:LoadBalancerRule? ()

LoadBalancing rule

failover boolean true

Configuration for load balancer whether to fail over in case of a failure

public type Local record

Presents a read-only view of the local address.

Field Name Data Type Default Value Description
host string

The local host name/IP

port int 0

The local port

public type MutualSslHandshake record

A record for providing mutual ssl handshake results.

Field Name Data Type Default Value Description
status passed|failed? ()

Status of the handshake.

public type OAuth2AuthConfig record

The `OAuth2AuthConfig` record can be used to configure OAuth2 based authentication used by the HTTP endpoint.

Field Name Data Type Default Value Description
grantType CLIENT_CREDENTIALS_GRANT|PASSWORD_GRANT|DIRECT_TOKEN

OAuth2 grant type

config http:ClientCredentialsGrantConfig|http:PasswordGrantConfig|http:DirectTokenConfig

Configurations for the given grant type

public type PasswordGrantConfig record

The `PasswordGrantConfig` record can be used to configue OAuth2 password grant type

Field Name Data Type Default Value Description
tokenUrl string

Token URL for the authorization server

username string

Username for password grant authentication

password string

Password for password grant authentication

clientId string

Client ID for password grant authentication

clientSecret string

Client secret for password grant authentication

scopes string[]

Scope of the access request

refreshConfig http:RefreshConfig

Configurations for refreshing the access token

clockSkew int 0

Clock skew in seconds

retryRequest boolean true

Retry the request if the initial request returns a 401 response

credentialBearer AUTH_HEADER_BEARER|POST_BODY_BEARER|NO_BEARER AUTH_HEADER_BEARER

How authentication credentials are sent to the authorization server

public type PoolConfiguration record

Configurations for managing HTTP client connection pool.

Field Name Data Type Default Value Description
maxActiveConnections int config:getAsInt(b7a.http.pool.maxActiveConnections, defaultValue=-1)

Max active connections per route(host:port). Default value is -1 which indicates unlimited.

maxIdleConnections int config:getAsInt(b7a.http.pool.maxIdleConnections, defaultValue=100)

Maximum number of idle connections allowed per pool.

waitTimeinMillis int config:getAsInt(b7a.http.pool.waitTimeinMillis, defaultValue=30000)

Maximum amount of time, the client should wait for an idle connection before it sends an error when the pool is exhausted

maxActiveStreamsPerConnection int config:getAsInt(b7a.http.pool.maxActiveStreamsPerConnection, defaultValue=50)

Maximum active streams per connection. This only applies to HTTP/2.

public type Protocols record

A record for configuring SSL/TLS protocol and version to be used.

Field Name Data Type Default Value Description
name string

SSL Protocol to be used (e.g.: TLS1.2)

versions string[] []

SSL/TLS protocols to be enabled (e.g.: TLSv1,TLSv1.1,TLSv1.2)

public type ProxyConfig record

Proxy server configurations to be used with the HTTP client endpoint.

Field Name Data Type Default Value Description
host string

Host name of the proxy server

port int 0

Proxy server port

userName string

Proxy server username

password string

proxy server password

public type RefreshConfig record

The `RefreshConfig` record can be used to pass the configurations for refreshing the access token of password grant type.

Field Name Data Type Default Value Description
refreshUrl string

Refresh token URL for the refresh token server

scopes string[]

Scope of the access request

credentialBearer AUTH_HEADER_BEARER|POST_BODY_BEARER|NO_BEARER AUTH_HEADER_BEARER

How authentication credentials are sent to the authorization server

public type Remote record

Presents a read-only view of the remote address.

Field Name Data Type Default Value Description
host string

The remote host name/IP

port int 0

The remote port

public type RequestLimits record

Configures limits for requests. If these limits are violated, the request is rejected.

Field Name Data Type Default Value Description
maxUriLength int -1

Maximum allowed length for a URI. Exceeding this limit will result in a 414 - URI Too Long response.

maxHeaderSize int -1

Maximum allowed size for headers. Exceeding this limit will result in a 413 - Payload Too Large response.

maxEntityBodySize int -1

Maximum allowed size for the entity body. Exceeding this limit will result in a 413 - Payload Too Large response.

public type RetryConfig record

Provides configurations for controlling the retrying behavior in failure scenarios.

Field Name Data Type Default Value Description
count int 0

Number of retry attempts before giving up

interval int 0

Retry interval in milliseconds

backOffFactor float 0.0

Multiplier of the retry interval to exponentailly increase retry interval

maxWaitInterval int 0

Maximum time of the retry interval in milliseconds

statusCodes int[] []

HTTP response status codes which are considered as failures

public type RetryInferredConfig record

Derived set of configurations from the `RetryConfig`.

Field Name Data Type Default Value Description
count int 0

Number of retry attempts before giving up

interval int 0

Retry interval in milliseconds

backOffFactor float 0.0

Multiplier of the retry interval to exponentailly increase retry interval

maxWaitInterval int 0

Maximum time of the retry interval in milliseconds

statusCodes boolean[] []

HTTP response status codes which are considered as failures

public type RollingWindow record

Represents a rolling window in the Circuit Breaker.

Field Name Data Type Default Value Description
requestVolumeThreshold int 10

Minimum number of requests in a RollingWindow that will trip the circuit.

timeWindowMillis int 60000

Time period in milliseconds for which the failure threshold is calculated

bucketSizeMillis int 10000

The granularity at which the time window slides. This is measured in milliseconds.

public type SecureSocket record

Provides configurations for facilitating secure communication with a remote HTTP endpoint.

Field Name Data Type Default Value Description
trustStore crypto:TrustStore? ()

Configurations associated with TrustStore

keyStore crypto:KeyStore? ()

Configurations associated with KeyStore

certFile string

A file containing the certificate of the client

keyFile string

A file containing the private key of the client

keyPassword string

Password of the private key if it is encrypted

trustedCertFile string

A file containing a list of certificates or a single certificate that the client trusts

protocol http:Protocols? ()

SSL/TLS protocol related options

certValidation http:ValidateCert? ()

Certificate validation against CRL or OCSP related options

ciphers string[] []

List of ciphers to be used eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

verifyHostname boolean true

Enable/disable host name verification

shareSession boolean true

Enable/disable new SSL session creation

ocspStapling boolean false

Enable/disable OCSP stapling

handshakeTimeout int

SSL handshake time out

sessionTimeout int

SSL session time out

public type ServiceEndpointConfiguration record

Provides a set of configurations for HTTP service endpoints.

Field Name Data Type Default Value Description
host string 0.0.0.0

The host name/IP of the endpoint

keepAlive AUTO|ALWAYS|NEVER KEEPALIVE_AUTO

Can be set to either KEEPALIVE_AUTO, which respects the connection header, or KEEPALIVE_ALWAYS, which always keeps the connection alive, or KEEPALIVE_NEVER, which always closes the connection

secureSocket http:ServiceSecureSocket? ()

The SSL configurations for the service endpoint. This needs to be configured in order to communicate through HTTPS.

httpVersion string 1.1

Highest HTTP version supported by the endpoint

requestLimits http:RequestLimits? ()

Configures the parameters for request validation

filters http:Filter[] []

If any pre-processing needs to be done to the request before dispatching the request to the resource, filters can applied

timeoutMillis int DEFAULT_LISTENER_TIMEOUT

Period of time in milliseconds that a connection waits for a read/write operation. Use value 0 to disable timeout

maxPipelinedRequests int MAX_PIPELINED_REQUESTS

Defines the maximum number of requests that can be processed at a given time on a single connection. By default 10 requests can be pipelined on a single cinnection and user can change this limit appropriately. This will be applicable only for HTTP 1.1

authProviders http:AuthProvider[]? ()

The array of authentication providers which are used to authenticate the users

positiveAuthzCache http:AuthCacheConfig {}

Caching configurations for positive authorizations

negativeAuthzCache http:AuthCacheConfig {}

Caching configurations for negative authorizations

public type ServiceOcspStapling record

A record for providing configurations for certificate revocation status checks.

Field Name Data Type Default Value Description
enable boolean false

The status of OCSP stapling

cacheSize int 0

Maximum size of the cache

cacheValidityPeriod int 0

The time period for which a cache entry is valid

public type ServiceSecureSocket record

Configures the SSL/TLS options to be used for HTTP service.

Field Name Data Type Default Value Description
trustStore crypto:TrustStore? ()

Configures the trust store to be used

keyStore crypto:KeyStore? ()

Configures the key store to be used

certFile string

A file containing the certificate of the server

keyFile string

A file containing the private key of the server

keyPassword string

Password of the private key if it is encrypted

trustedCertFile string

A file containing a list of certificates or a single certificate that the server trusts

protocol http:Protocols? ()

SSL/TLS protocol related options

certValidation http:ValidateCert? ()

Certificate validation against CRL or OCSP related options

ciphers string[] [TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_DHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256]

List of ciphers to be used (e.g.: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA)

sslVerifyClient string

The type of client certificate verification

shareSession boolean true

Enable/disable new SSL session creation

handshakeTimeout int? ()

SSL handshake time out

sessionTimeout int? ()

SSL session time out

ocspStapling http:ServiceOcspStapling? ()

Enable/disable OCSP stapling

public type TargetService record

Represents a single service and its related configurations.

Field Name Data Type Default Value Description
url string

URL of the target service

secureSocket http:SecureSocket? ()

Configurations for secure communication with the remote HTTP endpoint

public type ValidateCert record

A record for providing configurations for certificate revocation status checks.

Field Name Data Type Default Value Description
enable boolean false

The status of validateCertEnabled

cacheSize int 0

Maximum size of the cache

cacheValidityPeriod int 0

The time period for which a cache entry is valid

public type Versioning record

Configurations for service versioning.

Field Name Data Type Default Value Description
pattern string v{major}.{minor}

Expected version pattern in the request URL

allowNoVersion boolean false

Allow requests with missing version path segment in the URL to be dispatched

matchMajorVersion boolean false

Allow requests with only the major version specified in the URL to be dispatched

public type WSServiceConfig record

Configurations for a WebSocket service.

Field Name Data Type Default Value Description
endpoints http:Listener?[] []

An array of endpoints the service would be attached to

path string

Path of the WebSocket service

subProtocols string[] []

Negotiable sub protocol by the service

idleTimeoutInSeconds int 0

Idle timeout for the client connection. Upon timeout, onIdleTimeout resource (if defined) in the server service will be triggered. Note that this overrides the timeoutMillis config in the http:Listener.

maxFrameSize int 0

The maximum payload size of a WebSocket frame in bytes. If this is not set or is negative or zero, the default frame size will be used.

public type WebSocketClientEndpointConfig record

Configuration for the WebSocket client endpoint.

Field Name Data Type Default Value Description
callbackService service? ()

The callback service for the client. Resources in this service gets called on receipt of messages from the server.

subProtocols string[] []

Negotiable sub protocols for the client

customHeaders map {}

Custom headers which should be sent to the server

idleTimeoutInSeconds int -1

Idle timeout of the client. Upon timeout, onIdleTimeout resource (if defined) in the client service will be triggered.

readyOnConnect boolean true

true if the client is ready to receive messages as soon as the connection is established. This is true by default. If changed to false the function ready() of the WebSocketClientneeds to be called once to start receiving messages.

secureSocket http:SecureSocket? ()

SSL/TLS related options

maxFrameSize int 0

The maximum payload size of a WebSocket frame in bytes. If this is not set or is negative or zero the default frame size of 65536 will be used.

public type WebSocketUpgradeConfig record

Resource configuration to upgrade from HTTP to WebSocket.

Field Name Data Type Default Value Description
upgradePath string

Path which is used to upgrade from HTTP to WebSocket

upgradeService service

Callback service for a successful upgrade

public function createHttpCachingClient(string url, http:ClientEndpointConfig config, http:CacheConfig cacheConfig) returns (Client|error<>)

Creates an HTTP client capable of caching HTTP responses.

Parameter Name Data Type Default Value Description
url string

The URL of the HTTP endpoint to connect to

config http:ClientEndpointConfig

The configurations for the client endpoint associated with the caching client

cacheConfig http:CacheConfig

The configurations for the HTTP cache to be used with the caching client

Return Type Description
Client|error<>

An HttpCachingClient instance which wraps the base Client with a caching layer

public function createHttpSecureClient(string url, http:ClientEndpointConfig config) returns (Client|error<>)

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

Parameter Name Data Type Default Value Description
url string

Base URL

config http:ClientEndpointConfig

Client endpoint configurations

Return Type Description
Client|error<>

Created secure HTTP client

public function decode(string url, string charset) returns (string|error<>)

Decodes the given URL.

Parameter Name Data Type Default Value Description
url string

URL to be decoded

charset string

Charactor set that URL to be decoded from

Return Type Description
string|error<>

The string Value of the decoded url or an error that occured during decoding

public function encode(string url, string charset) returns (string|error<>)

Encodes the given URL.

Parameter Name Data Type Default Value Description
url string

URL to be encoded

charset string

Charactor set that URL to be encoded in

Return Type Description
string|error<>

The string Value of the encoded url or an error that occured during encoding

public function extractBasicAuthHeaderValue(http:Request req) returns (string|null)

Extracts the basic authentication header value from the request.

Parameter Name Data Type Default Value Description
req http:Request

Request instance

Return Type Description
string|null

Value of the basic authentication header, or nil if not found

public function invokeEndpoint(string path, http:Request outRequest, FORWARD|GET|POST|DELETE|OPTIONS|PUT|PATCH|HEAD|NONE requestAction, http:Client httpClient) returns (Response|error<>)

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

Parameter Name Data Type Default Value Description
path string

Resource path

outRequest http:Request

A Request struct

requestAction FORWARD|GET|POST|DELETE|OPTIONS|PUT|PATCH|HEAD|NONE

HttpOperation related to the request

httpClient http:Client

HTTP client which uses to call the relavant functions

Return Type Description
Response|error<>

The response for the request or an error if failed to establish communication with the upstream server

public function parseHeader(string headerValue) returns ((string,map<any>)|error<>)

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

Parameter Name Data Type Default Value Description
headerValue string

The header value

Return Type Description
(string,map)|error<>

Returns a tuple containing the value and its parameter map

public type AuthHandlerRegistry object

Representation of the Http Auth Handler Registry.

  • <AuthHandlerRegistry> add(string id, http:HttpAuthnHandler authnHandler)

    Add an HttpAuthnHandler to HttpAuthHandlerRegistry

    Parameter Name Data Type Default Value Description
    id string

    Auth provider id

    authnHandler http:HttpAuthnHandler

    HttpAuthnHandler instance

  • <AuthHandlerRegistry> get(string id) returns (HttpAuthnHandler)

    Retrieves an HttpAuthnHandler from HttpAuthHandlerRegistry which corresponds to the given id

    Parameter Name Data Type Default Value Description
    id string

    Auth provider id

    Return Type Description
    HttpAuthnHandler

    HttpAuthnHandler instance or nil if not found

  • <AuthHandlerRegistry> getAll() returns (map<HttpAuthnHandler>)

    Retrieve the HttpAuthnHandler map

    Return Type Description
    map

    map of HttpAuthnHandler

  • <AuthHandlerRegistry> remove(string id)

    Removes a specific authn handler from the HttpAuthnHandler map

    Parameter Name Data Type Default Value Description
    id string
  • <AuthHandlerRegistry> clear()

    Removes all authn handler from the HttpAuthnHandler map

public type AuthnFilter object

Representation of the Authentication filter.

Field Name Data Type Default Value Description
authnHandlerChain http:AuthnHandlerChain

The Authentication handler chain

  • <AuthnFilter> __init(http:AuthnHandlerChain authnHandlerChain)

    Parameter Name Data Type Default Value Description
    authnHandlerChain http:AuthnHandlerChain
  • <AuthnFilter> filterRequest(http:Caller caller, http:Request request, http:FilterContext context) returns (boolean)

    Request filter method which attempts to authenticated the request.

    Parameter Name Data Type Default Value Description
    caller http:Caller

    Caller for outbound HTTP responses

    request http:Request

    An inboud HTTP request message

    context http:FilterContext

    A filter context

    Return Type Description
    boolean

    True if the filter succeeds

  • <AuthnFilter> filterResponse(http:Response response, http:FilterContext context) returns (boolean)

    Parameter Name Data Type Default Value Description
    response http:Response
    context http:FilterContext
    Return Type Description
    boolean

public type AuthnHandlerChain object

Representation of Authentication handler chain

  • <AuthnHandlerChain> __init(http:AuthHandlerRegistry authHandlerRegistry)

    Parameter Name Data Type Default Value Description
    authHandlerRegistry http:AuthHandlerRegistry
  • <AuthnHandlerChain> handle(http:Request req) returns (boolean)

    Tries to authenticate against any one of the available authentication handlers

    Parameter Name Data Type Default Value Description
    req http:Request

    Request instance

    Return Type Description
    boolean

    true if authenticated successfully, else false

  • <AuthnHandlerChain> handleWithSpecificAuthnHandlers(string[] authProviderIds, http:Request req) returns (boolean)

    Tries to authenticate against a specifc sub set of the authentication handlers, using the given array of auth provider ids

    Parameter Name Data Type Default Value Description
    authProviderIds string[]

    array of auth provider ids

    req http:Request

    Request instance

    Return Type Description
    boolean

    true if authenticated successfully, else false

public type AuthzFilter object

Representation of the Authorization filter

Field Name Data Type Default Value Description
authzHandler http:HttpAuthzHandler

HttpAuthzHandler instance for handling authorization

  • <AuthzFilter> __init(http:HttpAuthzHandler authzHandler)

    Parameter Name Data Type Default Value Description
    authzHandler http:HttpAuthzHandler
  • <AuthzFilter> filterRequest(http:Caller caller, http:Request request, http:FilterContext context) returns (boolean)

    Filter function implementation which tries to authorize the request

    Parameter Name Data Type Default Value Description
    caller http:Caller

    Caller for outbound HTTP responses

    request http:Request

    Request instance

    context http:FilterContext

    FilterContext instance

    Return Type Description
    boolean

    A flag to indicate if the request flow should be continued(true) or aborted(false), a code and a message

  • <AuthzFilter> filterResponse(http:Response response, http:FilterContext context) returns (boolean)

    Parameter Name Data Type Default Value Description
    response http:Response
    context http:FilterContext
    Return Type Description
    boolean

public type CircuitBreakerClient object

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

Field Name Data Type Default Value Description
url string

The URL of the target service

config http:ClientEndpointConfig

The configurations of the client endpoint associated with this CircuitBreaker instance

circuitBreakerInferredConfig http:CircuitBreakerInferredConfig

Configurations derived from CircuitBreakerConfig

httpClient http:Client

The underlying HttpActions instance which will be making the actual network calls

circuitHealth http:CircuitHealth

The circuit health monitor

currentCircuitState OPEN|HALF_OPEN|CLOSED CB_CLOSED_STATE

The current state the cicuit is in

  • <CircuitBreakerClient> __init(string url, http:ClientEndpointConfig config, http:CircuitBreakerInferredConfig circuitBreakerInferredConfig, http:Client httpClient, http:CircuitHealth circuitHealth)

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

    Parameter Name Data Type Default Value Description
    url string

    The URL of the target service

    config http:ClientEndpointConfig

    The configurations of the client endpoint associated with this CircuitBreaker instance

    circuitBreakerInferredConfig http:CircuitBreakerInferredConfig

    Configurations derived from CircuitBreakerConfig

    httpClient http:Client

    The underlying HttpActions instance which will be making the actual network calls

    circuitHealth http:CircuitHealth

    The circuit health monitor

  • <CircuitBreakerClient> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The POST remote function implementation of the Circuit Breaker. This wraps the post() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The PUT remote function implementation of the Circuit Breaker. This wraps the put() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the post() function of the underlying HTTP remote functions provider. The execute() function can be used to invoke an HTTP call with the given HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string

    HTTP verb to be used for the request

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The PATCH remote function implementation of the Circuit Breaker. This wraps the patch() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The DELETE remote function implementation of the Circuit Breaker. This wraps the delete() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The GET remote function implementation of the Circuit Breaker. This wraps the get() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The OPTIONS remote function implementation of the Circuit Breaker. This wraps the options() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> forward(string path, http:Request request) returns (Response|error<>)

    This wraps the forward() function of the underlying HTTP remote functions provider. The Forward remote function can be used to forward an incoming request to an upstream service as it is.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    request http:Request

    A Request struct

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <CircuitBreakerClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Circuit breaking not supported. Defaults to the submit() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <CircuitBreakerClient> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    Circuit breaking not supported. Defaults to the getResponse() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture related to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <CircuitBreakerClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    Circuit breaking not supported. Defaults to the hasPromise() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <CircuitBreakerClient> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    Circuit breaking not supported. Defaults to the getNextPromise() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP PushPromise message, or an error if the invocation fails

  • <CircuitBreakerClient> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    Circuit breaking not supported. Defaults to the getPromisedResponse() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <CircuitBreakerClient> rejectPromise(http:PushPromise promise)

    Circuit breaking not supported. Defaults to the rejectPromise() function of the underlying HTTP remote functions provider.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The PushPromise to be rejected

  • <CircuitBreakerClient> forceClose()

    Force the circuit into a closed state in which it will allow requests regardless of the error percentage until the failure threshold exceeds.

  • <CircuitBreakerClient> forceOpen()

    Force the circuit into a open state in which it will suspend all requests until resetTimeMillis interval exceeds.

  • <CircuitBreakerClient> getCurrentState() returns (CircuitState)

    Provides CircuitState of the circuit breaker.

    Return Type Description
    CircuitState

    The current CircuitState of circuit breaker

public type Filter object

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

  • <Filter> filterRequest(http:Caller caller, http:Request request, http:FilterContext context) returns (boolean)

    Request filter function. If a false is returned the response should have been sent from this function as it will not be dispatched to the next filter or the resource.

    Parameter Name Data Type Default Value Description
    caller http:Caller

    The http caller

    request http:Request

    An inboud HTTP request message

    context http:FilterContext

    A filter context

    Return Type Description
    boolean

    True if the filter succeeds

  • <Filter> filterResponse(http:Response response, http:FilterContext context) returns (boolean)

    Response filter function. If a false is returned a 500 Internal Server Error would be sent to the client.

    Parameter Name Data Type Default Value Description
    response http:Response

    An outbound HTTP response message

    context http:FilterContext

    A filter context

    Return Type Description
    boolean

    True if the filter succeeds

public type FilterContext object

Representation of request filter Context.

Field Name Data Type Default Value Description
serviceRef service

The service

serviceName string

Name of the service

resourceName string

Name of the resource

attributes map {}

Attributes to share between filters

  • <FilterContext> __init(service serviceRef, string serviceName, string resourceName)

    Parameter Name Data Type Default Value Description
    serviceRef service
    serviceName string
    resourceName string

public type HttpAuthnHandler object

Representation of Authentication handler for HTTP traffic.

Field Name Data Type Default Value Description
name string

Name of the http authn handler

  • <HttpAuthnHandler> canHandle(http:Request req) returns (boolean)

    Checks if the request can be authenticated with the relevant HttpAuthnHandler implementation

    Parameter Name Data Type Default Value Description
    req http:Request

    Request instance

    Return Type Description
    boolean

    true if can be authenticated, else false

  • <HttpAuthnHandler> handle(http:Request req) returns (boolean)

    Tries to authenticate the request with the relevant HttpAuthnHandler implementation

    Parameter Name Data Type Default Value Description
    req http:Request

    Request instance

    Return Type Description
    boolean

    true if authenticated successfully, else false

public type HttpAuthzHandler object

Representation of Authorization Handler for HTTP

Field Name Data Type Default Value Description
authStoreProvider auth:AuthStoreProvider

AuthStoreProvider instance

positiveAuthzCache cache:Cache

Cache instance, which is cache positive authorizations

negativeAuthzCache cache:Cache

Cache instance, which is cache negative authorizations

  • <HttpAuthzHandler> __init(auth:AuthStoreProvider authStoreProvider, cache:Cache positiveAuthzCache, cache:Cache negativeAuthzCache)

    Parameter Name Data Type Default Value Description
    authStoreProvider auth:AuthStoreProvider
    positiveAuthzCache cache:Cache
    negativeAuthzCache cache:Cache

public type HttpBasicAuthnHandler object

Defines Basic Auth handler for HTTP traffic.

Field Name Data Type Default Value Description
name string basic

Authentication handler name

authStoreProvider auth:AuthStoreProvider BLangTypeInit: new null ([])

AuthStoreProvider instance

  • <HttpBasicAuthnHandler> __init(auth:AuthStoreProvider authStoreProvider)

    Parameter Name Data Type Default Value Description
    authStoreProvider auth:AuthStoreProvider
  • <HttpBasicAuthnHandler> canHandle(http:Request req) returns (boolean)

    Checks if the provided request can be authenticated with basic auth.

    Parameter Name Data Type Default Value Description
    req http:Request

    Request object

    Return Type Description
    boolean

    true if it is possible authenticate with basic auth, else false

  • <HttpBasicAuthnHandler> handle(http:Request req) returns (boolean)

    Intercept requests for authentication.

    Parameter Name Data Type Default Value Description
    req http:Request

    Request object

    Return Type Description
    boolean

    true if authentication is a success, else false

public type HttpCache object

Field Name Data Type Default Value Description
cache cache:Cache BLangTypeInit: new null ([])
policy CACHE_CONTROL_AND_VALIDATORS|RFC_7234 CACHE_CONTROL_AND_VALIDATORS
isShared boolean false

public type HttpFuture object

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.

public type HttpJwtAuthnHandler object

Representation of JWT Auth handler for HTTP traffic

Field Name Data Type Default Value Description
name string jwt

Name of the auth handler

jwtAuthenticator auth:JWTAuthProvider

JWTAuthenticator instance

  • <HttpJwtAuthnHandler> __init(auth:JWTAuthProvider jwtAuthenticator)

    Parameter Name Data Type Default Value Description
    jwtAuthenticator auth:JWTAuthProvider
  • <HttpJwtAuthnHandler> canHandle(http:Request req) returns (boolean)

    Checks if the request can be authenticated with JWT

    Parameter Name Data Type Default Value Description
    req http:Request

    Request instance

    Return Type Description
    boolean

    true if can be authenticated, else false

  • <HttpJwtAuthnHandler> handle(http:Request req) returns (boolean)

    Authenticates the incoming request using JWT authentication

    Parameter Name Data Type Default Value Description
    req http:Request

    Request instance

    Return Type Description
    boolean

    true if authenticated successfully, else false

public type Listener object

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.

  • <Listener> __init(int port, http:ServiceEndpointConfiguration? config)

    Parameter Name Data Type Default Value Description
    port int
    config http:ServiceEndpointConfiguration? ()
  • <Listener> __start() returns (error?<>)

    Return Type Description
    error?<>
  • <Listener> __stop() returns (error?<>)

    Return Type Description
    error?<>
  • <Listener> __attach(service s, string? name) returns (error?<>)

    Parameter Name Data Type Default Value Description
    s service
    name string? ()
    Return Type Description
    error?<>
  • <Listener> init(http:ServiceEndpointConfiguration c)

    Gets invoked during module initialization to initialize the endpoint.

    Parameter Name Data Type Default Value Description
    c http:ServiceEndpointConfiguration

    Configurations for HTTP service endpoints

  • <Listener> initEndpoint() returns (error?<>)

    Return Type Description
    error?<>

public type LoadBalancerRounRobinRule object

Implementation of round robin load balancing strategy.

Field Name Data Type Default Value Description
index int 0

Keep tracks the current point of the Client[]

  • <LoadBalancerRounRobinRule> getNextClient(http:Client?[] loadBalanceCallerActionsArray) returns (Client|error<>)

    Provides an HTTP client which is choosen according to the round robin algorithm.

    Parameter Name Data Type Default Value Description
    loadBalanceCallerActionsArray http:Client?[]

    Array of HTTP clients which needs to be load balanced

    Return Type Description
    Client|error<>

    Choosen Client from the algorithm or an error for a failure in the algorithm implementation

public type LoadBalancerRule object

LoadBalancerRule provides a required interfaces to implement different algorithms.

  • <LoadBalancerRule> getNextClient(http:Client?[] loadBalanceCallerActionsArray) returns (Client|error<>)

    Provides an HTTP client which is choosen according to the algorithm.

    Parameter Name Data Type Default Value Description
    loadBalanceCallerActionsArray http:Client?[]

    Array of HTTP clients which needs to be load balanced

    Return Type Description
    Client|error<>

    Choosen Client from the algorithm or an error for the failure in the algorithm implementation

public type MockListener object

Mock server endpoint which does not open a listening port.

  • <MockListener> __init(int port, http:ServiceEndpointConfiguration? config)

    Parameter Name Data Type Default Value Description
    port int
    config http:ServiceEndpointConfiguration? ()
  • <MockListener> __start() returns (error?<>)

    Return Type Description
    error?<>
  • <MockListener> __stop() returns (error?<>)

    Return Type Description
    error?<>
  • <MockListener> __attach(service s, string? name) returns (error?<>)

    Parameter Name Data Type Default Value Description
    s service
    name string? ()
    Return Type Description
    error?<>
  • <MockListener> init(http:ServiceEndpointConfiguration c)

    Parameter Name Data Type Default Value Description
    c http:ServiceEndpointConfiguration
  • <MockListener> initEndpoint() returns (error?<>)

    Return Type Description
    error?<>
  • <MockListener> register(service s, string? name) returns (error?<>)

    Parameter Name Data Type Default Value Description
    s service
    name string?
    Return Type Description
    error?<>
  • <MockListener> start()

  • <MockListener> stop()

public type PushPromise object

Represents an HTTP/2 PUSH_PROMISE frame.

Field Name Data Type Default Value Description
path string

The resource path

method string

The HTTP method

  • <PushPromise> __init(string path, string method)

    Constructs a PushPromise from a given path and a method.

    Parameter Name Data Type Default Value Description
    path string /

    The resource path

    method string GET

    The HTTP method

  • <PushPromise> hasHeader(string headerName) returns (boolean)

    Checks whether the requested header exists.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    boolean

    A boolean representing the existence of a given header

  • <PushPromise> getHeader(string headerName) returns (string)

    Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    string

    The header value, or null if there is no such header

  • <PushPromise> getHeaders(string headerName) returns (string[])

    Gets transport headers from the PushPromise.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    string[]

    The array of header values

  • <PushPromise> addHeader(string headerName, string headerValue)

    Adds the specified key/value pair as an HTTP header to the PushPromise.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    headerValue string

    The header value

  • <PushPromise> setHeader(string headerName, string headerValue)

    Sets the value of a transport header in PushPromise.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    headerValue string

    The header value

  • <PushPromise> removeHeader(string headerName)

    Removes a transport header from the PushPromise.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

  • <PushPromise> removeAllHeaders()

    Removes all transport headers from the PushPromise.

  • <PushPromise> getHeaderNames() returns (string[])

    Gets all transport header names from the PushPromise.

    Return Type Description
    string[]

    An array of all transport header names

public type Request object

Represents an HTTP request.

Field Name Data Type Default Value Description
rawPath string

Resource path of the request URL

method string

The HTTP request method

httpVersion string

The HTTP version supported by the client

userAgent string

The user-agent. This value is used when setting the user-agent header

extraPathInfo string

Additional information associated with the URL provided by the client

cacheControl http:RequestCacheControl? ()

The cache-control directives for the request. This needs to be explicitly initialized if intending on utilizing HTTP caching.

mutualSslHandshake http:MutualSslHandshake? ()

A record providing mutual ssl handshake results.

  • <Request> setEntity(mime:Entity e)

    Sets the provided Entity to the request.

    Parameter Name Data Type Default Value Description
    e mime:Entity

    The Entity to be set to the request

  • <Request> getQueryParams() returns (map<string>)

    Gets the query parameters of the request, as a map.

    Return Type Description
    map

    String map of query params

  • <Request> getMatrixParams(string path) returns (map<any>)

    Gets the matrix parameters of the request.

    Parameter Name Data Type Default Value Description
    path string

    Path to the location of matrix parameters

    Return Type Description
    map

    A map of matrix paramters which can be found for the given path

  • <Request> getEntity() returns (mime:Entity|error<>)

    Gets the Entity associated with the request.

    Return Type Description
    mime:Entity|error<>

    The Entity of the request. An error is returned, if entity construction fails

  • <Request> hasHeader(string headerName) returns (boolean)

    Checks whether the requested header key exists in the header map.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    boolean

    Returns true if the specified header key exists

  • <Request> getHeader(string headerName) returns (string)

    Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    string

    The first header value for the specified header name. An exception is thrown if no header is found. Use hasHeader() beforehand to check the existence of header.

  • <Request> getHeaders(string headerName) returns (string[])

    Gets all the header values to which the specified header key maps to.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    string[]

    The header values the specified header key maps to. An exception is thrown if no header is found. Use hasHeader() beforehand to check the existence of header.

  • <Request> setHeader(string headerName, string headerValue)

    Sets the specified header to the request. If a mapping already exists for the specified header key, the existing header value is replaced with the specfied header value.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    headerValue string

    The header value

  • <Request> addHeader(string headerName, string headerValue)

    Adds the specified header to the request. Existing header values are not replaced.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    headerValue string

    The header value

  • <Request> removeHeader(string key)

    Removes the specified header from the request.

    Parameter Name Data Type Default Value Description
    key string

    The header name

  • <Request> removeAllHeaders()

    Removes all the headers from the request.

  • <Request> getHeaderNames() returns (string[])

    Gets all the names of the headers of the request.

    Return Type Description
    string[]

    An array of all the header names

  • <Request> expects100Continue() returns (boolean)

    Checks whether the client expects a 100-continue response.

    Return Type Description
    boolean

    Returns true if the client expects a 100-continue response

  • <Request> setContentType(string contentType) returns (error?<>)

    Sets the content-type header to the request.

    Parameter Name Data Type Default Value Description
    contentType string

    Content type value to be set as the content-type header

    Return Type Description
    error?<>

    Nil if successful, error in case of invalid content-type

  • <Request> getContentType() returns (string)

    Gets the type of the payload of the request (i.e: the content-type header value).

    Return Type Description
    string

    Returns the content-type header value as a string

  • <Request> getJsonPayload() returns (json|error<>)

    Extracts json payload from the request. If the content type is not JSON, an error is returned.

    Return Type Description
    json|error<>

    The json payload or error in case of errors

  • <Request> getXmlPayload() returns (xml|error<>)

    Extracts xml payload from the request. If the content type is not XML, an error is returned.

    Return Type Description
    xml|error<>

    The xml payload or error in case of errors

  • <Request> getTextPayload() returns (string|error<>)

    Extracts text payload from the request. If the content type is not of type text, an error is returned.

    Return Type Description
    string|error<>

    The text payload or error in case of errors

  • <Request> getByteChannel() returns (io:ReadableByteChannel|error<>)

    Gets the request payload as a ByteChannel except in the case of multiparts. To retrieve multiparts, use getBodyParts().

    Return Type Description
    io:ReadableByteChannel|error<>

    A byte channel from which the message payload can be read or error in case of errors

  • <Request> getBinaryPayload() returns (byte[]|error<>)

    Gets the request payload as a byte[].

    Return Type Description
    byte[]|error<>

    The byte[] representation of the message payload or error in case of errors

  • <Request> getFormParams() returns (map<string>|error<>)

    Gets the form parameters from the HTTP request as a map when content type is application/x-www-form-urlencoded.

    Return Type Description
    map|error<>

    The map of form params or error in case of errors

  • <Request> getBodyParts() returns (Entity[]|error<>)

    Extracts body parts from the request. If the content type is not a composite media type, an error is returned.

    Return Type Description
    Entity[]|error<>

    Returns the body parts as an array of entities or an error if there were any errors in constructing the body parts from the request

  • <Request> setJsonPayload(json payload, string contentType)

    Sets a json as the payload.

    Parameter Name Data Type Default Value Description
    payload json

    The json payload

    contentType string application/json

    The content type of the payload. Set this to override the default content-type header value for json

  • <Request> setXmlPayload(xml payload, string contentType)

    Sets an xml as the payload.

    Parameter Name Data Type Default Value Description
    payload xml

    The xml payload

    contentType string application/xml

    The content type of the payload. Set this to override the default content-type header value for xml

  • <Request> setTextPayload(string payload, string contentType)

    Sets a string as the payload.

    Parameter Name Data Type Default Value Description
    payload string

    The string payload

    contentType string text/plain

    The content type of the payload. Set this to override the default content-type header value for string

  • <Request> setBinaryPayload(byte[] payload, string contentType)

    Sets a byte[] as the payload.

    Parameter Name Data Type Default Value Description
    payload byte[]

    The byte[] payload

    contentType string application/octet-stream

    The content type of the payload. Set this to override the default content-type header value for byte[]

  • <Request> setBodyParts(mime:Entity[] bodyParts, string contentType)

    Set multiparts as the payload.

    Parameter Name Data Type Default Value Description
    bodyParts mime:Entity[]

    The entities which make up the message body

    contentType string multipart/form-data

    The content type of the top level message. Set this to override the default content-type header value

  • <Request> setFileAsPayload(string filePath, string contentType)

    Sets the content of the specified file as the entity body of the request.

    Parameter Name Data Type Default Value Description
    filePath string

    Path to the file to be set as the payload

    contentType string application/octet-stream

    The content type of the specified file. Set this to override the default content-type header value

  • <Request> setByteChannel(io:ReadableByteChannel payload, string contentType)

    Sets a ByteChannel as the payload.

    Parameter Name Data Type Default Value Description
    payload io:ReadableByteChannel

    A ByteChannel through which the message payload can be read

    contentType string application/octet-stream

    The content type of the payload. Set this to override the default content-type header value

  • <Request> setPayload(string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] payload)

    Sets the request payload.

    Parameter Name Data Type Default Value Description
    payload string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    Payload can be of type string, xml, json, byte[], ByteChannel or Entity[] (i.e: a set of body parts)

public type RequestCacheControl object

Configures cache control directives for a Request.

Field Name Data Type Default Value Description
noCache boolean false

Sets the no-cache directive

noStore boolean false

Sets the no-store directive

noTransform boolean false

Sets the no-transform directive

onlyIfCached boolean false

Sets the only-if-cached directive

maxAge int -1

Sets the max-age directive

maxStale int -1

Sets the max-stale directive

minFresh int -1

Sets the min-fresh directive

  • <RequestCacheControl> buildCacheControlDirectives() returns (string)

    Builds the cache control directives string from the current RequestCacheControl configurations.

    Return Type Description
    string

    The cache control directives string to be used in the cache-control header

public type Response object

Represents an HTTP response.

Field Name Data Type Default Value Description
statusCode int 200

The response status code

reasonPhrase string

The status code reason phrase

server string

The server header

resolvedRequestedURI string

The ultimate request URI that was made to receive the response when redirect is on

cacheControl http:ResponseCacheControl? ()

The cache-control directives for the response. This needs to be explicitly initialized if intending on utilizing HTTP caching. For incoming responses, this will already be populated if the response was sent with cache-control directives

  • <Response> getEntity() returns (mime:Entity|error<>)

    Gets the Entity associated with the response.

    Return Type Description
    mime:Entity|error<>

    The Entity of the response. An error is returned, if entity construction fails

  • <Response> setEntity(mime:Entity e)

    Sets the provided Entity to the response.

    Parameter Name Data Type Default Value Description
    e mime:Entity

    The Entity to be set to the response

  • <Response> hasHeader(string headerName) returns (boolean)

    Checks whether the requested header key exists in the header map.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    boolean

    Returns true if the specified header key exists

  • <Response> getHeader(string headerName) returns (string)

    Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    string

    The first header value for the specified header name. An exception is thrown if no header is found. Use hasHeader() beforehand to check the existence of header.

  • <Response> addHeader(string headerName, string headerValue)

    Adds the specified header to the response. Existing header values are not replaced.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    headerValue string

    The header value

  • <Response> getHeaders(string headerName) returns (string[])

    Gets all the header values to which the specified header key maps to.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    Return Type Description
    string[]

    The header values the specified header key maps to. An exception is thrown if no header is found. Use hasHeader() beforehand to check the existence of header.

  • <Response> setHeader(string headerName, string headerValue)

    Sets the specified header to the response. If a mapping already exists for the specified header key, the existing header value is replaced with the specfied header value.

    Parameter Name Data Type Default Value Description
    headerName string

    The header name

    headerValue string

    The header value

  • <Response> removeHeader(string key)

    Removes the specified header from the response.

    Parameter Name Data Type Default Value Description
    key string

    The header name

  • <Response> removeAllHeaders()

    Removes all the headers from the response.

  • <Response> getHeaderNames() returns (string[])

    Gets all the names of the headers of the response.

    Return Type Description
    string[]

    An array of all the header names

  • <Response> setContentType(string contentType)

    Sets the content-type header to the response.

    Parameter Name Data Type Default Value Description
    contentType string

    Content type value to be set as the content-type header

  • <Response> getContentType() returns (string)

    Gets the type of the payload of the response (i.e: the content-type header value).

    Return Type Description
    string

    Returns the content-type header value as a string

  • <Response> getJsonPayload() returns (json|error<>)

    Extract json payload from the response. If the content type is not JSON, an error is returned.

    Return Type Description
    json|error<>

    The json payload or error in case of errors

  • <Response> getXmlPayload() returns (xml|error<>)

    Extracts xml payload from the response. If the the content type is not XML, an error is returned.

    Return Type Description
    xml|error<>

    The xml payload or error in case of errors

  • <Response> getTextPayload() returns (string|error<>)

    Extracts text payload from the response. If the content type is not of type text, an error is returned.

    Return Type Description
    string|error<>

    The string representation of the message payload or error in case of errors

  • <Response> getByteChannel() returns (io:ReadableByteChannel|error<>)

    Gets the response payload as a ByteChannel, except in the case of multiparts. To retrieve multiparts, use getBodyParts().

    Return Type Description
    io:ReadableByteChannel|error<>

    A byte channel from which the message payload can be read or error in case of errors

  • <Response> getBinaryPayload() returns (byte[]|error<>)

    Gets the response payload as a byte[].

    Return Type Description
    byte[]|error<>

    The byte[] representation of the message payload or error in case of errors

  • <Response> getBodyParts() returns (Entity[]|error<>)

    Extracts body parts from the response. If the content type is not a composite media type, an error is returned.

    Return Type Description
    Entity[]|error<>

    Returns the body parts as an array of entities or an error if there were any errors in constructing the body parts from the response

  • <Response> setETag(json|xml|string|byte[] payload)

    Sets the etag header for the given payload. The ETag is generated using a CRC32 hash function.

    Parameter Name Data Type Default Value Description
    payload json|xml|string|byte[]

    The payload for which the ETag should be set

  • <Response> setLastModified()

    Sets the current time as the last-modified header.

  • <Response> setJsonPayload(json payload, string contentType)

    Sets a json as the payload.

    Parameter Name Data Type Default Value Description
    payload json

    The json payload

    contentType string application/json

    The content type of the payload. Set this to override the default content-type header value for json

  • <Response> setXmlPayload(xml payload, string contentType)

    Sets an xml as the payload

    Parameter Name Data Type Default Value Description
    payload xml

    The xml payload

    contentType string application/xml

    The content type of the payload. Set this to override the default content-type header value for xml

  • <Response> setTextPayload(string payload, string contentType)

    Sets a string as the payload.

    Parameter Name Data Type Default Value Description
    payload string

    The string payload

    contentType string text/plain

    The content type of the payload. Set this to override the default content-type header value for string

  • <Response> setBinaryPayload(byte[] payload, string contentType)

    Sets a byte[] as the payload.

    Parameter Name Data Type Default Value Description
    payload byte[]

    The byte[] payload

    contentType string application/octet-stream

    The content type of the payload. Set this to override the default content-type header value for byte[]

  • <Response> setBodyParts(mime:Entity[] bodyParts, string contentType)

    Set multiparts as the payload.

    Parameter Name Data Type Default Value Description
    bodyParts mime:Entity[]

    The entities which make up the message body

    contentType string multipart/form-data

    The content type of the top level message. Set this to override the default content-type header value

  • <Response> setFileAsPayload(string filePath, string contentType)

    Sets the content of the specified file as the entity body of the response.

    Parameter Name Data Type Default Value Description
    filePath string

    Path to the file to be set as the payload

    contentType string application/octet-stream

    The content type of the specified file. Set this to override the default content-type header value

  • <Response> setByteChannel(io:ReadableByteChannel payload, string contentType)

    Sets a ByteChannel as the payload.

    Parameter Name Data Type Default Value Description
    payload io:ReadableByteChannel

    A ByteChannel through which the message payload can be read

    contentType string application/octet-stream

    The content type of the payload. Set this to override the default content-type header value

  • <Response> setPayload(string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] payload)

    Sets the response payload.

    Parameter Name Data Type Default Value Description
    payload string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    Payload can be of type string, xml, json, byte[], ByteChannel or Entity[] (i.e: a set of body parts)

public type ResponseCacheControl object

Configures cache control directives for a Response.

Field Name Data Type Default Value Description
mustRevalidate boolean false

Sets the must-revalidate directive

noCache boolean false

Sets the no-cache directive

noStore boolean false

Sets the no-store directive

noTransform boolean false

Sets the no-transform directive

isPrivate boolean false

Sets the private and public directives

proxyRevalidate boolean false

Sets the proxy-revalidate directive

maxAge int -1

Sets the max-age directive

sMaxAge int -1

Sets the s-maxage directive

noCacheFields string[] []

Optional fields for the no-cache directive. Before sending a listed field in a response, it must be validated with the origin server.

privateFields string[] []

Optional fields for the private directive. A cache can omit the fields specified and store the rest of the response.

  • <ResponseCacheControl> buildCacheControlDirectives() returns (string)

    Builds the cache control directives string from the current ResponseCacheControl configurations.

    Return Type Description
    string

    The cache control directives string to be used in the cache-control header

public type WebSocketListener object

Represents a WebSocket service endpoint.

  • <WebSocketListener> __init(int port, http:ServiceEndpointConfiguration? config)

    Gets invoked during module initialization to initialize the endpoint.

    Parameter Name Data Type Default Value Description
    port int

    The port of the endpoint

    config http:ServiceEndpointConfiguration? ()

    The ServiceEndpointConfiguration of the endpoint

  • <WebSocketListener> __start() returns (error?<>)

    Return Type Description
    error?<>
  • <WebSocketListener> __stop() returns (error?<>)

    Return Type Description
    error?<>
  • <WebSocketListener> __attach(service s, string? name) returns (error?<>)

    Parameter Name Data Type Default Value Description
    s service
    name string? ()
    Return Type Description
    error?<>

Endpoint Caller

The caller actions for responding to client requests.

Field Name Data Type Default Value Description
remoteAddress http:Remote {}

The remote address

localAddress http:Local {}

The local address

protocol string

The protocol associated with the service endpoint

  • <Caller> respond(http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (error?<>)

    Sends the outbound response to the caller.

    Parameter Name Data Type Default Value Description
    message http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    The outbound response or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    error?<>

    Returns an error if failed to respond

  • <Caller> promise(http:PushPromise promise) returns (error?<>)

    Pushes a promise to the caller.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    Push promise message

    Return Type Description
    error?<>

    An error in case of failures

  • <Caller> pushPromisedResponse(http:PushPromise promise, http:Response response) returns (error?<>)

    Sends a promised push response to the caller.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    Push promise message

    response http:Response

    The outbound response

    Return Type Description
    error?<>

    An error in case of failures while responding with the promised response

  • <Caller> acceptWebSocketUpgrade(map<string> headers) returns (WebSocketCaller)

    Sends an upgrade request with custom headers.

    Parameter Name Data Type Default Value Description
    headers map

    A map of custom headers for handshake

    Return Type Description
    WebSocketCaller

    WebSocket service endpoint

  • <Caller> cancelWebSocketUpgrade(int status, string reason) returns (error?<>)

    Cancels the handshake.

    Parameter Name Data Type Default Value Description
    status int

    Error Status code for cancelling the upgrade and closing the connection. This error status code need to be 4xx or 5xx else the default status code would be 400.

    reason string

    Reason for cancelling the upgrade

    Return Type Description
    error?<>

    An error if an error occurs during cancelling the upgrade or nil

  • <Caller> continue() returns (error?<>)

    Sends a 100-continue response to the caller.

    Return Type Description
    error?<>

    Returns an error if failed to send the 100-continue response

  • <Caller> redirect(http:Response response, 300|301|302|303|304|305|307|308 code, string[] locations) returns (error?<>)

    Sends a redirect response to the user with the specified redirection status code.

    Parameter Name Data Type Default Value Description
    response http:Response

    Response to be sent to the caller

    code 300|301|302|303|304|305|307|308

    The redirect status code to be sent

    locations string[]

    An array of URLs to which the caller can redirect to

    Return Type Description
    error?<>

    Returns an error if failed to send the redirect response

  • <Caller> ok(http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (error?<>)

    Sends the outbound response to the caller with the status 200 OK.

    Parameter Name Data Type Default Value Description
    message http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    The outbound response or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    error?<>

    Returns an error if failed to respond

  • <Caller> created(string uri, http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (error?<>)

    Sends the outbound response to the caller with the status 201 Created.

    Parameter Name Data Type Default Value Description
    uri string

    Represents the most specific URI for the newly created resource

    message http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    The outbound response or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]. This message is optional.

    Return Type Description
    error?<>

    Returns an error if failed to respond

  • <Caller> accepted(http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (error?<>)

    Sends the outbound response to the caller with the status 202 Accepted.

    Parameter Name Data Type Default Value Description
    message http:Response|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    The outbound response or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]. This message is optional.

    Return Type Description
    error?<>

    Returns an error if failed to respond

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

Field Name Data Type Default Value Description
config http:ClientEndpointConfig {}

The configurations associated with the client

httpClient http:Client

Chain of different HTTP clients which provides the capability for initiating contact with a remote HTTP service in resilient manner

  • <Client> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The post() function can be used to send HTTP POST requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The head() function can be used to send HTTP HEAD requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The put() function can be used to send HTTP PUT requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Invokes an HTTP call with the specified HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string

    HTTP verb value

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The patch() function can be used to send HTTP PATCH requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The delete() function can be used to send HTTP DELETE requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The get() function can be used to send HTTP GET requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The options() function can be used to send HTTP OPTIONS requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> forward(string path, http:Request request) returns (Response|error<>)

    The forward() function can be used to invoke an HTTP call with inbound request's HTTP verb

    Parameter Name Data Type Default Value Description
    path string

    Request path

    request http:Request

    An HTTP inbound request message

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <Client> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Submits an HTTP request to a service with the specified HTTP verb. The submit() function does not give out a Response as the result, rather it returns an HttpFuture which can be used to do further interactions with the endpoint.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <Client> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <Client> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <Client> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP Push Promise message, or an error if the invocation fails

  • <Client> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <Client> rejectPromise(http:PushPromise promise)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The Push Promise to be rejected

Endpoint FailoverClient

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

Field Name Data Type Default Value Description
failoverClientConfig http:FailoverClientEndpointConfiguration

The configurations for the failover client endpoint

failoverInferredConfig http:FailoverInferredConfig

Configurations derived from FailoverConfig

succeededEndpointIndex int

Index of the CallerActions[] array which given a successful response

  • <FailoverClient> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The POST remote function implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The HEAD remote function implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The PATCH remote function implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The PUT remote function implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The OPTIONS remote function implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> forward(string path, http:Request request) returns (Response|error<>)

    Invokes an HTTP call using the incoming request's HTTP method.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    request http:Request

    An HTTP request

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Invokes an HTTP call with the specified HTTP method.

    Parameter Name Data Type Default Value Description
    httpVerb string

    HTTP method to be used for the request

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The DELETE remote function implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The GET remote function implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <FailoverClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Submits an HTTP request to a service with the specified HTTP verb. The submit() function does not return a Response as the result, rather it returns an HttpFuture which can be used for subsequent interactions with the HTTP endpoint.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <FailoverClient> getResponse(http:HttpFuture httpFuture) returns (error<>)

    Retrieves the Response for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture related to a previous asynchronous invocation

    Return Type Description
    error<>

    An HTTP response message, or an error if the invocation fails

  • <FailoverClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    Checks whether a PushPromise exists for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <FailoverClient> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    Retrieves the next available PushPromise for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP Push Promise message, or an error if the invocation fails

  • <FailoverClient> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    Retrieves the promised server push Response message.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <FailoverClient> rejectPromise(http:PushPromise promise)

    Rejects a PushPromise. When a PushPromise is rejected, there is no chance of fetching a promised response using the rejected promise.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The Push Promise to be rejected

Endpoint HttpCachingClient

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

Field Name Data Type Default Value Description
url string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig {}

The configurations of the client endpoint associated with this CachingActions instance

httpClient http:Client

The underlying HttpActions instance which will be making the actual network calls

cache http:HttpCache

The cache storage for the HTTP responses

cacheConfig http:CacheConfig {}

Configurations for the underlying cache storage and for controlling the HTTP caching behaviour

  • <HttpCachingClient> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Responses returned for POST requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for POST requests invalidate the cached responses for the same resource.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Responses for HEAD requests are cacheable and as such, will be routed through the HTTP cache. Only if a suitable response cannot be found will the request be directed to the origin server.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Responses returned for PUT requests are not cacheable. Therefore, the requests are simply directed to the origin server. In addition, PUT requests invalidate the currently stored responses for the given path.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> execute(string httpMethod, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Invokes an HTTP call with the specified HTTP method. This is not a cacheable operation, unless the HTTP method used is GET or HEAD.

    Parameter Name Data Type Default Value Description
    httpMethod string

    HTTP method to be used for the request

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Responses returned for PATCH requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for PATCH requests invalidate the cached responses for the same resource.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Responses returned for DELETE requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for DELETE requests invalidate the cached responses for the same resource.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Responses for GET requests are cacheable and as such, will be routed through the HTTP cache. Only if a suitable response cannot be found will the request be directed to the origin server.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Responses returned for OPTIONS requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for OPTIONS requests invalidate the cached responses for the same resource.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> forward(string path, http:Request request) returns (Response|error<>)

    Forward remote function can be used to invoke an HTTP call with inbound request's HTTP method. Only inbound requests of GET and HEAD HTTP method types are cacheable.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    request http:Request

    The HTTP request to be forwarded

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCachingClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Submits an HTTP request to a service with the specified HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <HttpCachingClient> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    Retrieves the Response for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture related to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <HttpCachingClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    Checks whether a PushPromise exists for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <HttpCachingClient> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    Retrieves the next available PushPromise for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP Push Promise message, or an error if the invocation fails

  • <HttpCachingClient> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    Retrieves the promised server push Response message.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <HttpCachingClient> rejectPromise(http:PushPromise promise)

    Rejects a PushPromise. When a PushPromise is rejected, there is no chance of fetching a promised response using the rejected promise.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The Push Promise to be rejected

Endpoint HttpCaller

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.

Field Name Data Type Default Value Description
config http:ClientEndpointConfig {}

The configurations associated with the HttpCaller

url string

The URL of the remote HTTP endpoint

  • <HttpCaller> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The post() function can be used to send HTTP POST requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The head() function can be used to send HTTP HEAD requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The put() function can be used to send HTTP PUT requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Invokes an HTTP call with the specified HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string

    HTTP verb value

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The patch() function can be used to send HTTP PATCH requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The delete() function can be used to send HTTP DELETE requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The get() function can be used to send HTTP GET requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The options() function can be used to send HTTP OPTIONS requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> forward(string path, http:Request request) returns (Response|error<>)

    The forward() function can be used to invoke an HTTP call with inbound request's HTTP verb

    Parameter Name Data Type Default Value Description
    path string

    Request path

    request http:Request

    An HTTP inbound request message

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpCaller> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Submits an HTTP request to a service with the specified HTTP verb. The submit() function does not give out a Response as the result, rather it returns an HttpFuture which can be used to do further interactions with the endpoint.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <HttpCaller> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    Retrieves the Response for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture related to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <HttpCaller> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    Checks whether a PushPromise exists for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <HttpCaller> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    Retrieves the next available PushPromise for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP Push Promise message, or an error if the invocation fails

  • <HttpCaller> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    Retrieves the promised server push Response message.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <HttpCaller> rejectPromise(http:PushPromise promise)

    Rejects a PushPromise. When a PushPromise is rejected, there is no chance of fetching a promised response using the rejected promise.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The Push Promise to be rejected

Endpoint HttpClient

Provides the HTTP remote functions 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 remote functions implementation.

Field Name Data Type Default Value Description
url string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig

HTTP ClientEndpointConfig to be used for HTTP client invocation

httpCaller http:HttpCaller

HTTP client for outbound HTTP requests

httpClient http:Client

Chain of different HTTP clients which provides the capability for initiating contact with a remote HTTP service in resilient manner.

  • <HttpClient> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The post() function can be used to send HTTP POST requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The head() function can be used to send HTTP HEAD requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The put() function can be used to send HTTP PUT requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    Invokes an HTTP call with the specified HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string

    HTTP verb to be used for the request

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The patch() function can be used to send HTTP PATCH requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The delete() function can be used to send HTTP DELETE requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    A Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The get() function can be used to send HTTP GET requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The options() function can be used to send HTTP OPTIONS requests to HTTP endpoints.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP Request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> forward(string path, http:Request request) returns (Response|error<>)

    The forward() function can be used to invoke an HTTP call with inbound request's HTTP verb

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    request http:Request

    A Request struct

    Return Type Description
    Response|error<>

    The response for the request or an error if failed to establish communication with the upstream server

  • <HttpClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Submits an HTTP request to a service with the specified HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <HttpClient> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    Retrieves the Response for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture related to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <HttpClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    Retrieves the next available PushPromise for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <HttpClient> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    Retrieves the promised server push Response message.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP PushPromise message, or an error if the invocation fails

  • <HttpClient> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    Retrieves the promised server push Response message.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <HttpClient> rejectPromise(http:PushPromise promise)

    Rejects a PushPromise. When a PushPromise is rejected, there is no chance of fetching a promised response using the rejected promise.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The PushPromise to be rejected

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

Field Name Data Type Default Value Description
url string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig {}

The configurations of the client endpoint associated with this HttpActions instance

httpClient http:Client

The underlying HttpActions instance, which will make the actual network calls

tokenCache http:CachedToken

Cached token configurations

  • <HttpSecureClient> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the post() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or the error if one occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the head() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or the error if one occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the put() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or an error occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the execute() function of the underlying HTTP remote functions provider. Add relevant authentication headers o the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpVerb string

    HTTP verb value

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or an error occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the patch() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or an error occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the delete() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or the error if one occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the get() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or the error if one occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    This wraps the options() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The inbound response message or the error if one occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> forward(string path, http:Request request) returns (Response|error<>)

    This wraps the forward() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    path string

    Request path

    request http:Request

    An HTTP inbound request message

    Return Type Description
    Response|error<>

    The inbound response message or the error if one occurred while attempting to fulfill the HTTP request

  • <HttpSecureClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    This wraps the submit() function of the underlying HTTP remote functions provider. Add relevant authentication headers to the request and send the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <HttpSecureClient> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <HttpSecureClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <HttpSecureClient> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP Push Promise message, or an error if the invocation fails

  • <HttpSecureClient> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <HttpSecureClient> rejectPromise(http:PushPromise promise)

    This just pass the request to actual network call.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The Push Promise to be rejected

Endpoint LoadBalanceClient

LoadBalanceClient endpoint provides load balancing functionality over multiple HTTP clients.

Field Name Data Type Default Value Description
loadBalanceClientConfig http:LoadBalanceClientEndpointConfiguration

The configurations for the load balance client endpoint

loadBalanceClientsArray http:Client?[]

Array of HTTP clients for load balancing

lbRule http:LoadBalancerRule

Load balancing rule

failover boolean

Whether to fail over in case of a failure

  • <LoadBalanceClient> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The POST remote function implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The HEAD remote function implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The PATCH remote function implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The PUT remote function implementation of the Load Balance Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The OPTIONS remote function implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> forward(string path, http:Request request) returns (Response|error<>)

    The FORWARD remote function implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    request http:Request

    An optional HTTP request

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The EXECUTE remote function implementation of the LoadBalancer Connector. The Execute remote function can be used to invoke an HTTP call with the given HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string

    HTTP method to be used for the request

    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The DELETE remote function implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The GET remote function implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The response or an error if failed to fulfill the request

  • <LoadBalanceClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    The submit implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <LoadBalanceClient> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    The getResponse implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture related to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <LoadBalanceClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    The hasPromise implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <LoadBalanceClient> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    The getNextPromise implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP Push Promise message, or an error if the invocation fails

  • <LoadBalanceClient> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    The getPromisedResponse implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <LoadBalanceClient> rejectPromise(http:PushPromise promise)

    The rejectPromise implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The Push Promise to be rejected

Endpoint RedirectClient

Provides redirect functionality for HTTP client remote functions.

Field Name Data Type Default Value Description
url string

Target service url

config http:ClientEndpointConfig

HTTP ClientEndpointConfig to be used for HTTP client invocation

redirectConfig http:FollowRedirects

Configurations associated with redirect

httpClient http:Client

HTTP client for outbound HTTP requests

currentRedirectCount int 0

Current redirect count of the HTTP client

  • <RedirectClient> forward(string path, http:Request request) returns (Response|error<>)

    The forward() function is used to invoke an HTTP call with inbound request's HTTP verb.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    request http:Request

    An HTTP inbound request message

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RedirectClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The execute() sends an HTTP request to a service with the specified HTTP verb. Redirect will be performed only for HTTP methods.

    Parameter Name Data Type Default Value Description
    httpVerb string
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RedirectClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Submits an HTTP request to a service with the specified HTTP verb. The submit() function does not give out a Response as the result, rather it returns an HttpFuture which can be used to do further interactions with the endpoint.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

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

Field Name Data Type Default Value Description
url string

Target service url

config http:ClientEndpointConfig

HTTP ClientEndpointConfig to be used for HTTP client invocation

retryInferredConfig http:RetryInferredConfig

Derived set of configurations associated with retry

httpClient http:Client

Chain of different HTTP clients which provides the capability for initiating contact with a remote HTTP service in resilient manner.

  • <RetryClient> post(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The post() function wraps the underlying HTTP remote functions in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> head(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The head() function wraps the underlying HTTP remote functions in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> put(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The put() function wraps the underlying HTTP remote function in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> forward(string path, http:Request request) returns (Response|error<>)

    The forward() function wraps the underlying HTTP remote function in a way to provide retrying functionality for a given endpoint with inbound request's HTTP verb to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    request http:Request

    An HTTP inbound request message

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The execute() sends an HTTP request to a service with the specified HTTP verb. The function wraps the underlying HTTP remote function in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    httpVerb string
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> patch(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The patch() function wraps the undeline underlying HTTP remote function in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> delete(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The delete() function wraps the underlying HTTP remote function in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> get(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The get() function wraps the underlying HTTP remote function in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> options(string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (Response|error<>)

    The options() function wraps the underlying HTTP remote function in a way to provide retrying functionality for a given endpoint to recover from network level failures.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] ()

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    Response|error<>

    The HTTP Response message, or an error if the invocation fails

  • <RetryClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[] message) returns (HttpFuture|error<>)

    Submits an HTTP request to a service with the specified HTTP verb. cThe submit() function does not give out a Response as the result, crather it returns an HttpFuture which can be used to do further interactions with the endpoint.

    Parameter Name Data Type Default Value Description
    httpVerb string

    The HTTP verb value

    path string

    The resource path

    message http:Request|string|xml|json|byte[]|io:ReadableByteChannel|mime:Entity[]

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ReadableByteChannel or mime:Entity[]

    Return Type Description
    HttpFuture|error<>

    An HttpFuture that represents an asynchronous service invocation, or an error if the submission fails

  • <RetryClient> getResponse(http:HttpFuture httpFuture) returns (Response|error<>)

    Retrieves the Response for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    Response|error<>

    An HTTP response message, or an error if the invocation fails

  • <RetryClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    Checks whether a PushPromise exists for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    boolean

    A boolean that represents whether a PushPromise exists

  • <RetryClient> getNextPromise(http:HttpFuture httpFuture) returns (PushPromise|error<>)

    Retrieves the next available PushPromise for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture

    The HttpFuture relates to a previous asynchronous invocation

    Return Type Description
    PushPromise|error<>

    An HTTP Push Promise message, or an error if the invocation fails

  • <RetryClient> getPromisedResponse(http:PushPromise promise) returns (Response|error<>)

    Retrieves the promised server push Response message.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The related PushPromise

    Return Type Description
    Response|error<>

    A promised HTTP Response message, or an error if the invocation fails

  • <RetryClient> rejectPromise(http:PushPromise promise)

    Rejects a PushPromise. When a PushPromise is rejected, there is no chance of fetching a promised response using the rejected promise.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise

    The Push Promise to be rejected

Endpoint WebSocketCaller

Represents a WebSocket caller.

Field Name Data Type Default Value Description
id string

The connection id

negotiatedSubProtocol string

The subprotocols that are negotiated with the client

isSecure boolean false

true if the connection is secure

isOpen boolean false

true if the connection is open

attributes map {}

A map to store connection related attributes

  • <WebSocketCaller> pushText(string|json|xml|boolean|int|float|byte|byte[] data, boolean finalFrame) returns (error?<>)

    Push text to the connection.

    Parameter Name Data Type Default Value Description
    data string|json|xml|boolean|int|float|byte|byte">byte[]

    Data to be sent, if byte[] it is converted to a UTF-8 string for sending

    finalFrame boolean true

    Set to true if this is a final frame of a (long) message

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketCaller> pushBinary(byte[] data, boolean finalFrame) returns (error?<>)

    Push binary data to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]

    Binary data to be sent

    finalFrame boolean true

    Set to true if this is a final frame of a (long) message

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketCaller> ping(byte[] data) returns (error?<>)

    Ping the connection.

    Parameter Name Data Type Default Value Description
    data byte[]

    Binary data to be sent.

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketCaller> pong(byte[] data) returns (error?<>)

    Send pong message to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]

    Binary data to be sent

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketCaller> close(int? statusCode, string? reason, int timeoutInSecs) returns (error?<>)

    Close the connection.

    Parameter Name Data Type Default Value Description
    statusCode int? 1000

    Status code for closing the connection

    reason string? ()

    Reason for closing the connection

    timeoutInSecs int 60

    Time to wait for the close frame to be received from the remote endpoint before closing the connection. If the timeout exceeds, then the connection is terminated even though a close frame is not received from the remote endpoint. If the value < 0 (e.g., -1), then the connection waits until a close frame is received. If WebSocket frame is received from the remote endpoint, within waiting period the connection is terminated immediately.

    Return Type Description
    error?<>

    error if an error occurs when sending

Endpoint WebSocketClient

Represents a WebSocket client endpoint.

Field Name Data Type Default Value Description
id string

The connection id

negotiatedSubProtocol string

The subprotocols that are negotiated with the server

isSecure boolean false

true if the connection is secure

isOpen boolean false

true if the connection is open

response http:Response BLangTypeInit: new null ([])

Represents the HTTP response

attributes map {}

A map to store connection related attributes

  • <WebSocketClient> pushText(string|json|xml|boolean|int|float|byte|byte[] data, boolean finalFrame) returns (error?<>)

    Push text to the connection.

    Parameter Name Data Type Default Value Description
    data string|json|xml|boolean|int|float|byte|byte">byte[]

    Data to be sent, if byte[] it is converted to a UTF-8 string for sending

    finalFrame boolean true

    Set to true if this is a final frame of a (long) message

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketClient> pushBinary(byte[] data, boolean finalFrame) returns (error?<>)

    Push binary data to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]

    Binary data to be sent

    finalFrame boolean true

    Set to true if this is a final frame of a (long) message

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketClient> ping(byte[] data) returns (error?<>)

    Ping the connection.

    Parameter Name Data Type Default Value Description
    data byte[]

    Binary data to be sent.

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketClient> pong(byte[] data) returns (error?<>)

    Send pong message to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]

    Binary data to be sent

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketClient> close(int? statusCode, string? reason, int timeoutInSecs) returns (error?<>)

    Close the connection.

    Parameter Name Data Type Default Value Description
    statusCode int? 1000

    Status code for closing the connection

    reason string? ()

    Reason for closing the connection

    timeoutInSecs int 60

    Time to wait for the close frame to be received from the remote endpoint before closing the connection. If the timeout exceeds, then the connection is terminated even though a close frame is not received from the remote endpoint. If the value < 0 (e.g., -1), then the connection waits until a close frame is received. If WebSocket frame is received from the remote endpoint, within waiting period the connection is terminated immediately.

    Return Type Description
    error?<>

    error if an error occurs when sending

  • <WebSocketClient> ready() returns (error?<>)

    Called when the endpoint is ready to receive messages. Can be called only once per endpoint. For the WebSocketListener can be called only in upgrade or onOpen resources.

    Return Type Description
    error?<>

    error if an error occurs when sending