ballerina/http package

Package overview

This package provides an implementation for connecting and interacting with HTTP, HTTP2, and WebSocket endpoints. The package 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.

WebSockets

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

There are also two types of services for WebSocket: WebSocketService and WebSocketClientService. The callback service for WebSocketClient is always a WebSocketClientService. 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 is an HTTP request. To intercept this request and make 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
        }
    }
    upgrader(endpoint caller, http:Request req, string name) {
    }
}

Here upgradeService is a WebSocketService.

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

onText resource: Received Text messages are dispatched to this resource.

onBinary resource: Received Binary messages are dispatched to this resource.

onPing and onPong resources: Received ping and pong messages are dispatched to these resources respectively as a blob

onIdleTimeout: This resource is dispatched when idle timeout is reached. idleTimeout has to be configured by the user in WebSocket service configuration.

onClose: This resource is dispatched when a close message is received.

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

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

Logging

This package 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:

endpoint http:Client clientEndpoint {
      url: "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.
endpoint http:Listener helloWorldEP {
   port:9090
};

Then a Service can be defined and bound 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 bind helloWorldEP {

   // All resources are invoked with arguments of server connector and request.
   @http:ResourceConfig {
        methods:["POST"],
        path:"/{name}",
        body:"message"
    }
   sayHello (endpoint 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.
       caller->respond(res) but { error e => 
                            log:printError("Error sending response", err = e) };
   }
}

Type Definitions

Type Values Description
AuthScheme OAuth2 | JWT | Basic
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 NEVER | AUTO | 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 OPEN | HALF_OPEN | CLOSED

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 NEVER | AUTO | 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 option ALWAYS: Always set accept-encoding in outbound request/response NEVER: Never set accept-encoding header in outbound request/response

HttpOperation PUT | POST | PATCH | OPTIONS | NONE | HEAD | GET | FORWARD | 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

KeepAlive NEVER | AUTO | ALWAYS

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

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

Defines the HTTP redirect codes as a type.

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
AuthConfig 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.
Bucket Represents a discrete sub-part of the time window (Bucket).
CacheConfig Provides a set of configurations for controlling the caching behaviour of the endpoint.
CircuitBreakerConfig Provides a set of configurations for controlling the behaviour of the Circuit Breaker.
CircuitBreakerInferredConfig Derived set of configurations from the `CircuitBreakerConfig`.
CircuitHealth Maintains the health of the Circuit Breaker.
ClientEndpointConfig Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
ConnectionThrottling Provides configurations for throttling connections of the endpoint.
CorsConfig Configurations for CORS support.
FailoverActionError Defines an error which occurred during an attempt to failover.
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.
KeyStore A record for providing key store related configurations.
ListenerAuthConfig Configures the authentication scheme for a service or a resource.
LoadBalanceActionError Represents an error occurred in an action 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.
Protocols A record for configuring SSL/TLS protocol and version to be used.
ProxyConfig Proxy server configurations to be used with the HTTP client endpoint.
Remote Presents a read-only view of the remote address.
RequestLimits Configures limits for requests. If these limits are violated, the request is rejected.
RetryConfig Provides configurations for controlling the retry behaviour in failure scenarios.
RollingWindow Represents a rolling window in the Circuit Breaker.
SecureEndpointConfiguration Configuration for secure HTTP service endpoint.
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.
TrustStore A record for providing trust store 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 struct for WebSocket client endpoint.
WebSocketUpgradeConfig Configures the HTTP to WebSocket upgrade.

Objects Summary

Object Description
APIListenerActions

The caller actions for responding to client requests to api listener.

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

CallerActions

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.

CircuitBreakerClient

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

Connection

The caller actions for responding to client requests.

FailoverActions

Failover caller actions which provides failover capabilities to the failover client endpoint.

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

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

HttpCachingClient

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

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

HttpSecureClient

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

LoadBalancerActions

LoadBalancer caller actions which provides load balancing and failover capabilities to the load balance client endpoint.

PushPromise

Represents an HTTP/2 PUSH_PROMISE frame.

RedirectClient

Provides redirect functionality for HTTP client actions.

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.

RetryClient

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

SecureListenerActions

The caller actions for responding to client requests to secure listener.

Service

A representation of an HTTP service instance.

WebSocketClientService

Represents the WebSocket client service.

WebSocketConnector

Represents a WebSocket connector in ballerina. This include all connector oriented operations.

WebSocketService

Represents the WebSocket client service.

Endpoints Summary

Endpoint Description
APIListener

Representation of an API Listener.

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.

Listener

This is used for creating HTTP service endpoints. An HTTP service endpoint is capable of responding to remote callers. The Listener is responsible for initializing the endpoint using the provided configurations and providing the actions for communicating with the caller.

LoadBalanceClient

LoadBalanceClient endpoint provides load balancing functionality over multiple HTTP clients.

NonListener Mock service endpoint which does not open a listening port.
SecureListener

Defines Secure Listener endpoint.

WebSocketClient

Represents a WebSocket client endpoint.

WebSocketListener

Represents a WebSocket service endpoint.

Functions Summary

Return Type Function and Description
CallerActions createHttpCachingClient(string url, http:ClientEndpointConfig config, http:CacheConfig cacheConfig)

Creates an HTTP client capable of caching HTTP responses.

CallerActions 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, DELETE|HEAD|PUT|GET|POST|PATCH|NONE|OPTIONS|FORWARD requestAction, http:CallerActions httpClient)

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

(string,map) | error parseHeader(string headerValue)

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

CallerActions roundRobin(http:LoadBalancerActions lb, http:CallerActions[] loadBalanceConfigArray)

Round Robin Algorithm implementation with respect to load balancing endpoints.

Global Variables

Name Data Type Description
ACCEPTED_202 int

The HTTP response status code: 202 Accepted

AGE string

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

AUTHORIZATION string

HTTP header key authorization

BAD_GATEWAY_502 int

The HTTP response status code: 502 Bad Gateway

BAD_REQUEST_400 int

The HTTP response status code: 400 Bad Request

BASIC_AUTH AuthScheme
CACHE_CONTROL string

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

CACHE_CONTROL_AND_VALIDATORS CachingPolicy

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.

CB_CLOSED_STATE CircuitState

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.

CB_HALF_OPEN_STATE CircuitState

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_OPEN_STATE CircuitState

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

CHUNKING_ALWAYS Chunking

Always set chunking header in the response.

CHUNKING_AUTO Chunking

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_NEVER Chunking

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

COMPRESSION_ALWAYS Compression

Always set accept-encoding in outbound request/response.

COMPRESSION_AUTO Compression

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

COMPRESSION_NEVER Compression

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

CONFLICT_409 int

The HTTP response status code: 409 Conflict

CONTENT_LENGTH string

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

CONTENT_TYPE string

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

CONTINUE_100 int

The HTTP response status code: 100 Continue

CREATED_201 int

The HTTP response status code: 201 Created

DATE string

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

ETAG string

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

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

EXPECTATION_FAILED_417 int

The HTTP response status code: 417 Expectation Failed

EXPIRES string

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

FORBIDDEN_403 int

The HTTP response status code: 403 Forbidden

FOUND_302 int

The HTTP response status code: 302 Found

GATEWAY_TIMEOUT_504 int

The HTTP response status code: 504 Gateway Timeout

GONE_410 int

The HTTP response status code: 410 Gone

HTTP_DELETE HttpOperation

Constant for the HTTP DELETE method

HTTP_FORWARD HttpOperation

Constant for the HTTP FORWARD method

HTTP_GET HttpOperation

Constant for the HTTP GET method

HTTP_HEAD HttpOperation

Constant for the HTTP HEAD method

HTTP_NONE HttpOperation

Constant for the identify not an HTTP Operation

HTTP_OPTIONS HttpOperation

Constant for the HTTP OPTIONS method

HTTP_PATCH HttpOperation

Constant for the HTTP PATCH method

HTTP_POST HttpOperation

Constant for the HTTP POST method

HTTP_PUT HttpOperation

Constant for the HTTP PUT method

HTTP_VERSION_NOT_SUPPORTED_505 int

The HTTP response status code: 505 HTTP Version Not Supported

IF_MATCH string

HTTP header key if-match

IF_MODIFIED_SINCE string

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

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

HTTP header key if-range

IF_UNMODIFIED_SINCE string

HTTP header key if-unmodified-since

INTERNAL_SERVER_ERROR_500 int

The HTTP response status code: 500 Internal Server Error

JWT_AUTH AuthScheme
KEEPALIVE_ALWAYS KeepAlive

Keeps the connection alive irrespective of the connection header value

KEEPALIVE_AUTO KeepAlive

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

KEEPALIVE_NEVER KeepAlive

Closes the connection irrespective of the connection header value

LAST_MODIFIED string

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

LENGTH_REQUIRED_411 int

The HTTP response status code: 411 Length Required

LOCATION string

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

MAX_AGE string

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

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

MAX_STALE_ANY_AGE int

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

METHOD_NOT_ALLOWED_405 int

The HTTP response status code: 405 Method Not Allowed

MIN_FRESH string

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

MOVED_PERMANENTLY_301 int

The HTTP response status code: 301 Moved Permanently

MULTIPART_AS_PRIMARY_TYPE string

Represents multipart primary type

MULTIPLE_CHOICES_300 int

The HTTP response status code: 300 Multiple Choices

MUST_REVALIDATE string

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

NON_AUTHORITATIVE_INFORMATION_203 int

The HTTP response status code: 203 Non Authoritative Information

NOT_ACCEPTABLE_406 int

The HTTP response status code: 406 Not Acceptable

NOT_FOUND_404 int

The HTTP response status code: 404 Not Found

NOT_IMPLEMENTED_501 int

The HTTP response status code: 501 Not Implemented

NOT_MODIFIED_304 int

The HTTP response status code: 304 Not Modified

NO_CACHE string

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

NO_CONTENT_204 int

The HTTP response status code: 204 No Content

NO_STORE string

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

NO_TRANSFORM string

Instructs intermediaries not to transform the payload.

OAUTH2 AuthScheme
OK_200 int

The HTTP response status code: 200 OK

ONLY_IF_CACHED string

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.

PARTIAL_CONTENT_206 int

The HTTP response status code: 206 Partial Content

PAYLOAD_TOO_LARGE_413 int

The HTTP response status code: 413 Payload Too Large

PAYMENT_REQUIRED_402 int

The HTTP response status code: 402 Payment Required

PERMANENT_REDIRECT_308 int

The HTTP response status code: 308 Permanent Redirect

PRAGMA string

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

PRECONDITION_FAILED_412 int

The HTTP response status code: 412 Precondition Failed

PRIVATE string

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

PROXY_AUTHENTICATION_REQUIRED_407 int

The HTTP response status code: 407 Proxy Authentication Required

PROXY_REVALIDATE string

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

PUBLIC string

Indicates that any cache may store the response.

RANGE_NOT_SATISFIABLE_416 int

The HTTP response status code: 416 Range Not Satisfiable

REDIRECT_FOUND_302 RedirectCode

Represents the HTTP redirect status code 302 - Found.

REDIRECT_MOVED_PERMANENTLY_301 RedirectCode

Represents the HTTP redirect status code 301 - Moved Permanently.

REDIRECT_MULTIPLE_CHOICES_300 RedirectCode

Represents the HTTP redirect status code 300 - Multiple Choices.

REDIRECT_NOT_MODIFIED_304 RedirectCode

Represents the HTTP redirect status code 304 - Not Modified.

REDIRECT_PERMANENT_REDIRECT_308 RedirectCode

Represents the HTTP redirect status code 308 - Permanent Redirect.

REDIRECT_SEE_OTHER_303 RedirectCode

Represents the HTTP redirect status code 303 - See Other.

REDIRECT_TEMPORARY_REDIRECT_307 RedirectCode

Represents the HTTP redirect status code 307 - Temporary Redirect.

REDIRECT_USE_PROXY_305 RedirectCode

Represents the HTTP redirect status code 305 - Use Proxy.

REQUEST_TIMEOUT_408 int

The HTTP response status code: 408 Request Timeout

RESET_CONTENT_205 int

The HTTP response status code: 205 Reset Content

RFC_7234 CachingPolicy

Caching behaviour is as specified by the RFC 7234 specification.

ROUND_ROBIN string

Load balancing algorithm - Round Robin

SEE_OTHER_303 int

The HTTP response status code: 303 See Other

SERVER string

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

SERVICE_UNAVAILABLE_503 int

The HTTP response status code: 503 Service Unavailable

SWITCHING_PROTOCOLS_101 int

The HTTP response status code: 101 Switching Protocols

S_MAX_AGE string

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

TEMPORARY_REDIRECT_307 int

The HTTP response status code: 307 Temporary Redirect

TRANSFER_ENCODING string

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

UNAUTHORIZED_401 int

The HTTP response status code: 401 Unauthorized

UNSUPPORTED_MEDIA_TYPE int

The HTTP response status code: 415 Unsupported Media Type

UPGRADE_REQUIRED_426 int

The HTTP response status code: 426 Upgrade Required

URI_TOO_LONG_414 int

The HTTP response status code: 414 URI Too Long

USE_PROXY_305 int

The HTTP response status code: 305 Use Proxy

WARNING string

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

public type AuthConfig record

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

Field Name Data Type Default Value Description
scheme JWT|Basic|OAuth2

Scheme of the configuration (Basic, OAuth2, JWT etc.)

username string

Username for Basic authentication

password string

Password for Basic authentication

accessToken string

Access token for OAuth2 authentication

refreshToken string

Refresh token for OAuth2 authentication

refreshUrl string

Refresh token URL for OAuth2 authentication

consumerKey string

Consumer key for OAuth2 authentication

consumerSecret string

Consumer secret for OAuth2 authentication

tokenUrl string

Token URL for OAuth2 authentication

clientId string

Clietnt ID for OAuth2 authentication

clientSecret string

Client secret for OAuth2 authentication

public type AuthProvider record

Configuration for authentication providers.

Field Name Data Type Default Value Description
scheme string

Authentication scheme

id string

Authentication provider instance id

authStoreProvider string

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

issuer string

Identifier of the token issuer

audience string

Identifier of the token recipients

trustStore http:TrustStore?

Trustore configurations

certificateAlias string

Token signed key alias

clockSkew int

Time in seconds to mitigate clock skew

keyStore http:KeyStore?

KeyStore instance providing key store related configurations

keyAlias string

The Key Alias

keyPassword string

The Key password

expTime int

Expiry time

signingAlg string

The signing algorithm which is used to sign the JWT token

propagateToken boolean

true if propagating authentication info as JWT

public type Authentication record

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

Field Name Data Type Default Value Description
enabled boolean

Specifies whether authentication is enabled

public type Bucket record

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

Field Name Data Type Default Value Description
totalCount int

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

failureCount int

Number of failed requests during the sub-window time frame

rejectedCount int

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

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

resetTimeMillis int

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

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

resetTimeMillis int

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

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

Whether last request is success or not

totalRequestCount int

Total request count received within the RollingWindow

lastUsedBucketId int

ID of the last bucket used in Circuit Breaker calculations

startTime time:Time

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 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
url string

URL of the target service

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 NEVER|ALWAYS|AUTO 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

connectionThrottling http:ConnectionThrottling?

Configurations for connection throttling

secureSocket http:SecureSocket?

SSL/TLS related options

cache http:CacheConfig

HTTP caching related configurations

compression NEVER|ALWAYS|AUTO COMPRESSION_AUTO

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

auth http:AuthConfig?

HTTP authentication releated configurations

public type ConnectionThrottling record

Provides configurations for throttling connections of the endpoint.

Field Name Data Type Default Value Description
maxActiveConnections int -1

Maximum number of active connections allowed for the endpoint. The default value, -1, indicates that the number of connections are not restricted.

waitTime int 60000

Maximum waiting time for a request to grab an idle connection from the client

maxActiveStreamsPerConnection int -1

Maximum number of active streams allowed per an HTTP/2 connection

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

Specifies whether credentials are required to access the service

maxAge int -1

The maximum duration to cache the preflight from client side

public type FailoverActionError record

Defines an error which occurred during an attempt to failover.

Field Name Data Type Default Value Description
message string

An explanation on what went wrong

cause error?

The cause of the FailoverActionError, if available

statusCode int

HTTP status code to be sent to the caller

httpActionErr error[]

Errors which occurred at each endpoint during the failover

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 NEVER|ALWAYS|AUTO 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

connectionThrottling http:ConnectionThrottling?

The configurations for controlling the number of connections allowed concurrently

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 NEVER|ALWAYS|AUTO 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

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

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:CallerActions[]

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

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 NEVER|ALWAYS|AUTO AUTO

The status of compression

chunking NEVER|ALWAYS|AUTO 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

HTTP status code

public type KeyStore record

A record for providing key store related configurations.

Field Name Data Type Default Value Description
path string

Path to the key store file

password string

Key store password

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 LoadBalanceActionError record

Represents an error occurred in an action of the Load Balance connector.

Field Name Data Type Default Value Description
message string

An error message explaining about the error

cause error?

Cause of the error

statusCode int

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 NEVER|ALWAYS|AUTO 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

connectionThrottling http:ConnectionThrottling?

The configurations for controlling the number of connections allowed concurrently

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 NEVER|ALWAYS|AUTO COMPRESSION_AUTO

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

auth http:AuthConfig?

HTTP authentication releated configurations

algorithm string ROUND_ROBIN

The algorithm to be used for load balancing. The HTTP package provides 'roundRobin()' by default

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

The local port

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

Proxy server port

userName string

Proxy server username

password string

proxy server password

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

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 retry behaviour in failure scenarios.

Field Name Data Type Default Value Description
count int

Number of retry attempts before giving up

interval int

Retry interval in milliseconds

backOffFactor float

Multiplier of the retry interval to exponentailly increase retry interval

maxWaitInterval int

Maximum time of the retry interval in milliseconds

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 SecureEndpointConfiguration record

Configuration for secure HTTP service endpoint.

Field Name Data Type Default Value Description
host string

Host of the endpoint

port int 9090

Port of the endpoint

keepAlive AUTO|ALWAYS|NEVER KEEPALIVE_AUTO

The keepAlive behaviour of the endpoint

secureSocket http:ServiceSecureSocket?

The SSL configurations for the endpoint

httpVersion string 1.1

Highest HTTP version supported

requestLimits http:RequestLimits?

Request validation limits configuration

filters http:Filter[]

Filters to be applied to the request before being dispatched to the actual resource

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

authProviders http:AuthProvider[]?

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

public type SecureSocket record

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

Field Name Data Type Default Value Description
trustStore http:TrustStore?

Configurations associated with TrustStore

keyStore http:KeyStore?

Configurations associated with KeyStore

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

Enable/disable OCSP stapling

public type ServiceEndpointConfiguration record

Provides a set of configurations for HTTP service endpoints.

Field Name Data Type Default Value Description
host string

The host name/IP of the endpoint

port int

The port to which the endpoint should bind to

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

public type ServiceOcspStapling record

A record for providing configurations for certificate revocation status checks.

Field Name Data Type Default Value Description
enable boolean

The status of OCSP stapling

cacheSize int

Maximum size of the cache

cacheValidityPeriod int

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 http:TrustStore?

Configures the trust store to be used

keyStore http:KeyStore?

Configures the key store to be used

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 (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

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 TrustStore record

A record for providing trust store related configurations.

Field Name Data Type Default Value Description
path string

Path to the trust store file

password string

Trust store password

public type ValidateCert record

A record for providing configurations for certificate revocation status checks.

Field Name Data Type Default Value Description
enable boolean

The status of validateCertEnabled

cacheSize int

Maximum size of the cache

cacheValidityPeriod int

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

webSocketEndpoints http:WebSocketListener[]

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

Idle timeout for the client connection. This can be triggered by putting an onIdleTimeout resource in the WebSocket service.

maxFrameSize int

The maximum payload size of a WebSocket frame in bytes

public type WebSocketClientEndpointConfig record

Configuration struct for WebSocket client endpoint.

Field Name Data Type Default Value Description
url string

The url of the server to connect to

callbackService typedesc?

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 in the client service will be triggered (if there is one defined)

readyOnConnect boolean true

true if the client is ready to recieve 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

public type WebSocketUpgradeConfig record

Configures the HTTP to WebSocket upgrade.

Field Name Data Type Default Value Description
upgradePath string

Path which is used to upgrade from HTTP to WebSocket

upgradeService typedesc

WebSocket service which should be used after a successful upgrade

public function createHttpCachingClient(string url, http:ClientEndpointConfig config, http:CacheConfig cacheConfig) returns (CallerActions)

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
CallerActions

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

public function createHttpSecureClient(string url, http:ClientEndpointConfig config) returns (CallerActions)

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
CallerActions

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, DELETE|HEAD|PUT|GET|POST|PATCH|NONE|OPTIONS|FORWARD requestAction, http:CallerActions httpClient) returns (Response | error)

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

Parameter Name Data Type Default Value Description
path string

Resource path

outRequest http:Request

A Request struct

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

HttpOperation related to the request

httpClient http:CallerActions

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) | 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 function roundRobin(http:LoadBalancerActions lb, http:CallerActions[] loadBalanceConfigArray) returns (CallerActions)

Round Robin Algorithm implementation with respect to load balancing endpoints.

Parameter Name Data Type Default Value Description
lb http:LoadBalancerActions

LoadBalancer object

loadBalanceConfigArray http:CallerActions[]

Array of HTTP Clients that needs to be load balanced

Return Type Description
CallerActions

HttpClient elected from the algorithm

public type APIListenerActions object

The caller actions for responding to client requests to api listener.

Field Name Data Type Default Value Description
httpCallerActions http:Connection
  • <APIListenerActions> respond(http:Response|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    error

    Returns an error if failed to respond

  • <APIListenerActions> 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

  • <APIListenerActions> 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

  • <APIListenerActions> acceptWebSocketUpgrade(map headers) returns (WebSocketListener)

    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
    WebSocketListener
  • <APIListenerActions> cancelWebSocketUpgrade(int status, string reason) returns (error | null)

    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 | null

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

  • <APIListenerActions> 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

  • <APIListenerActions> redirect(http:Response response, 305|302|300|303|304|307|308|301 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 305|302|300|303|304|307|308|301

    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

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> new(http:AuthnHandlerChain authnHandlerChain)

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

    Request filter method which attempts to authenticated the request.

    Parameter Name Data Type Default Value Description
    listener http:Listener

    The http endpoint

    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> new(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> new(http:HttpAuthzHandler authzHandler)

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

    Filter function implementation which tries to authorize the request

    Parameter Name Data Type Default Value Description
    listener http:Listener

    Listener instance that is the http endpoint

    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 CallerActions object

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
serviceUri string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig

The configurations of the client endpoint associated with this HttpActions instance

  • <CallerActions> post(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> head(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]? null

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> put(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> patch(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> delete(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> get(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]? null

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> options(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]? null

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

  • <CallerActions> 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

  • <CallerActions> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    HttpFuture | error

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

  • <CallerActions> 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

  • <CallerActions> 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

  • <CallerActions> 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

  • <CallerActions> 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

  • <CallerActions> 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

public type CircuitBreakerClient object

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

Field Name Data Type Default Value Description
serviceUri 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:CallerActions

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

circuitHealth http:CircuitHealth

The circuit health monitor

currentCircuitState CLOSED|HALF_OPEN|OPEN CB_CLOSED_STATE

The current state the cicuit is in

  • <CircuitBreakerClient> new(string serviceUri, http:ClientEndpointConfig config, http:CircuitBreakerInferredConfig circuitBreakerInferredConfig, http:CallerActions httpClient, http:CircuitHealth circuitHealth)

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

    Parameter Name Data Type Default Value Description
    serviceUri 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:CallerActions

    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:ByteChannel|mime:Entity[]? message) returns (Response | error)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

    A Request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

    A Request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

    A Request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    This wraps the post() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    A Request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

    A Request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

    A Request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

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

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

    An optional HTTP Request or any payload of type string, xml, json, byte[], io:ByteChannel 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 actions provider. The Forward action 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:ByteChannel|mime:Entity[]? message) returns (HttpFuture | error)

    Circuit breaking not supported. Defaults to the submit() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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 actions 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 actions 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 actions 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 actions 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 actions 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 Connection object

The caller actions for responding to client requests.

  • <Connection> respond(http:Response|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    error

    Returns an error if failed to respond

  • <Connection> 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

  • <Connection> 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

  • <Connection> acceptWebSocketUpgrade(map headers) returns (WebSocketListener)

    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
    WebSocketListener
  • <Connection> cancelWebSocketUpgrade(int status, string reason) returns (error | null)

    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 | null

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

  • <Connection> 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

  • <Connection> redirect(http:Response response, 305|302|300|303|304|307|308|301 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 305|302|300|303|304|307|308|301

    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

public type FailoverActions object

Failover caller actions which provides failover capabilities to the failover client endpoint.

Field Name Data Type Default Value Description
serviceUri string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig

The configurations of the client endpoint associated with this Failover instance

failoverInferredConfig http:FailoverInferredConfig

Configurations derived from FailoverConfig

succeededEndpointIndex int

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

  • <FailoverActions> new(string serviceUri, http:ClientEndpointConfig config, http:FailoverInferredConfig failoverInferredConfig)

    Failover caller actions which provides failover capabilities to an HTTP client endpoint.

    Parameter Name Data Type Default Value Description
    serviceUri string

    The URL of the remote HTTP endpoint

    config http:ClientEndpointConfig

    The configurations of the client endpoint associated with this Failover instance

    failoverInferredConfig http:FailoverInferredConfig

    Configurations derived from FailoverConfig

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

    The POST action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The HEAD action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The PATCH action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The PUT action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The OPTIONS action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

  • <FailoverActions> 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

  • <FailoverActions> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The DELETE action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The GET action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

  • <FailoverActions> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    HttpFuture | error

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

  • <FailoverActions> 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

  • <FailoverActions> 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

  • <FailoverActions> 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

  • <FailoverActions> 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

  • <FailoverActions> 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

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:Listener listener, 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
    listener http:Listener

    The http endpoint

    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
serviceType typedesc

Type of the service

serviceName string

Name of the service

resourceName string

Name of the resource

attributes map

Attributes to share between filters

  • <FilterContext> new(typedesc serviceType, string serviceName, string resourceName)

    Parameter Name Data Type Default Value Description
    serviceType typedesc
    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

authzCache cache:Cache?

Cache instance, which is optional

  • <HttpAuthzHandler> new(auth:AuthStoreProvider authStoreProvider, cache:Cache? authzCache)

    Parameter Name Data Type Default Value Description
    authStoreProvider auth:AuthStoreProvider
    authzCache cache:Cache?

public type HttpBasicAuthnHandler object

Defines Basic Auth handler for HTTP traffic.

Field Name Data Type Default Value Description
name string

Authentication handler name

authStoreProvider auth:AuthStoreProvider

AuthStoreProvider instance

  • <HttpBasicAuthnHandler> new(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

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

Field Name Data Type Default Value Description
cache cache:Cache
policy CACHE_CONTROL_AND_VALIDATORS|RFC_7234 CACHE_CONTROL_AND_VALIDATORS
isShared boolean

public type HttpCachingClient object

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
serviceUri string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig

The configurations of the client endpoint associated with this CachingActions instance

httpClient http:CallerActions

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> new(string serviceUri, http:ClientEndpointConfig config, http:CacheConfig cacheConfig)

    Takes a service URL, a CliendEndpointConfig and a CacheConfig and builds an HTTP client capable of caching responses. The CacheConfig instance is used for initializing a new HTTP cache for the client and the ClientEndpointConfig is used for creating the underlying HTTP client.

    Parameter Name Data Type Default Value Description
    serviceUri 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

  • <HttpCachingClient> post(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

    HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]? null

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]?

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]? null

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]? null

    An optional HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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 action 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:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP request or any payload of type string, xml, json, byte[], io:ByteChannel 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

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

Name of the auth handler

jwtAuthenticator auth:JWTAuthProvider

JWTAuthenticator instance

  • <HttpJwtAuthnHandler> new(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 HttpSecureClient object

Provides secure HTTP actions 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
serviceUri string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig

The configurations of the client endpoint associated with this HttpActions instance

httpClient http:CallerActions

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

  • <HttpSecureClient> new(string serviceUri, http:ClientEndpointConfig config)

    Parameter Name Data Type Default Value Description
    serviceUri string
    config http:ClientEndpointConfig
  • <HttpSecureClient> post(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (Response | error)

    This wraps the post() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    Response | error

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

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

    This wraps the head() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

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

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

    This wraps the put() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    This wraps the execute() function of the underlying HTTP actions 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

    HTTP verb value

    path string

    Resource path

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

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    This wraps the patch() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    This wraps the delete() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    Response | error

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

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

    This wraps the get() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

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

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

    This wraps the options() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The inbound response message or an error 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 actions 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 an error occurred while attempting to fulfill the HTTP request

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

    This wraps the submit() function of the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

public type LoadBalancerActions object

LoadBalancer caller actions which provides load balancing and failover capabilities to the load balance client endpoint.

Field Name Data Type Default Value Description
serviceUri string

The URL of the remote HTTP endpoint

config http:ClientEndpointConfig

The configurations of the client endpoint associated with this LoadBalancer instance

loadBalanceClientsArray http:CallerActions[]

Array of HTTP clients for load balancing

algorithm string

Load balancing algorithm

nextIndex int

Index of the next load balancing client

failover boolean

Whether to fail over in case of a failure

  • <LoadBalancerActions> new(string serviceUri, http:ClientEndpointConfig config, http:CallerActions[] loadBalanceClientsArray, string algorithm, int nextIndex, boolean failover)

    Load Balancer adds an additional layer to the HTTP client to make network interactions more resilient.

    Parameter Name Data Type Default Value Description
    serviceUri string

    The URL of the remote HTTP endpoint

    config http:ClientEndpointConfig

    The configurations of the client endpoint associated with this LoadBalancer instance

    loadBalanceClientsArray http:CallerActions[]

    Array of HTTP clients for load balancing

    algorithm string

    Load balancing algorithm

    nextIndex int

    Index of the next load balancing client

    failover boolean

    Whether to fail over in case of a failure

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

    The POST action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The HEAD action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The PATCH action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The PUT action 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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The OPTIONS action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The FORWARD action 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

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

    The EXECUTE action implementation of the LoadBalancer Connector. The Execute action 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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The DELETE action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

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

    The GET action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The response or an error if failed to fulfill the request

  • <LoadBalancerActions> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    HttpFuture | error

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

  • <LoadBalancerActions> 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

  • <LoadBalancerActions> 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

  • <LoadBalancerActions> 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

  • <LoadBalancerActions> 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

  • <LoadBalancerActions> 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

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> new(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 RedirectClient object

Provides redirect functionality for HTTP client actions.

Field Name Data Type Default Value Description
serviceUri 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:CallerActions

HTTP client for outbound HTTP requests

currentRedirectCount int 0

Current redirect count of the HTTP client

  • <RedirectClient> new(string serviceUri, http:ClientEndpointConfig config, http:FollowRedirects redirectConfig, http:CallerActions httpClient)

    Create a redirect client with the given configurations.

    Parameter Name Data Type Default Value Description
    serviceUri 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:CallerActions

    HTTP client for outbound HTTP requests

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

    If the received response for the get() action is redirect eligible, redirect will be performed automatically by this get() function.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The HTTP Response message, or an error if the invocation fails

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

    If the received response for the post() action is redirect eligible, redirect will be performed automatically by this post() function.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The HTTP Response message, or an error if the invocation fails

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

    If the received response for the head() action is redirect eligible, redirect will be performed automatically by this head() function.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

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

    Return Type Description
    Response | error

    The HTTP Response message, or an error if the invocation fails

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

    If the received response for the put() action is redirect eligible, redirect will be performed automatically by this put() function.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The HTTP Response message, or an error if the invocation fails

  • <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:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    Response | error

    The HTTP Response message, or an error if the invocation fails

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

    If the received response for the patch() action is redirect eligible, redirect will be performed automatically by this patch() function.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The HTTP Response message, or an error if the invocation fails

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

    If the received response for the delete() action is redirect eligible, redirect will be performed automatically by this delete() function.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

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

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

    Return Type Description
    Response | error

    The HTTP Response message, or an error if the invocation fails

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

    If the received response for the options() action is redirect eligible, redirect will be performed automatically by this options() function.

    Parameter Name Data Type Default Value Description
    path string

    Resource path

    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? null

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    HttpFuture | error

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

  • <RedirectClient> 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

  • <RedirectClient> 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

  • <RedirectClient> 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

  • <RedirectClient> 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

  • <RedirectClient> 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

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.

  • <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)

    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 (mimeEntity | error)

    Gets the Entity associated with the request.

    Return Type Description
    mimeEntity | 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)

    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

  • <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> getPayloadAsString() returns (string | error)

    Gets the request payload as a string. Content type is not checked during payload construction which makes this different from getTextPayload() function.

    Return Type Description
    string | error

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

  • <Request> getByteChannel() returns (ioByteChannel | error)

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

    Return Type Description
    ioByteChannel | 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.

    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:ByteChannel payload, string contentType)

    Sets a ByteChannel as the payload.

    Parameter Name Data Type Default Value Description
    payload io:ByteChannel

    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:ByteChannel|mime:Entity[] payload)

    Sets the request payload.

    Parameter Name Data Type Default Value Description
    payload string|xml|json|byte[]|io:ByteChannel|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 (mimeEntity | error)

    Gets the Entity associated with the response.

    Return Type Description
    mimeEntity | 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> getPayloadAsString() returns (string | error)

    Gets the response payload as a string. Content type is not checked during payload construction which makes this different from getTextPayload() function.

    Return Type Description
    string | error

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

  • <Response> getByteChannel() returns (ioByteChannel | error)

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

    Return Type Description
    ioByteChannel | 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:ByteChannel payload, string contentType)

    Sets a ByteChannel as the payload.

    Parameter Name Data Type Default Value Description
    payload io:ByteChannel

    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:ByteChannel|mime:Entity[] payload)

    Sets the response payload.

    Parameter Name Data Type Default Value Description
    payload string|xml|json|byte[]|io:ByteChannel|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 RetryClient object

Provides the HTTP actions 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
serviceUri string

Target service url

config http:ClientEndpointConfig

HTTP ClientEndpointConfig to be used for HTTP client invocation

retryConfig http:RetryConfig

Configurations associated with retry

httpClient http:CallerActions

HTTP client for outbound HTTP requests

  • <RetryClient> new(string serviceUri, http:ClientEndpointConfig config, http:RetryConfig retryConfig, http:CallerActions httpClient)

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

    Parameter Name Data Type Default Value Description
    serviceUri string

    Target service url

    config http:ClientEndpointConfig

    HTTP ClientEndpointConfig to be used for HTTP client invocation

    retryConfig http:RetryConfig

    Configurations associated with retry

    httpClient http:CallerActions

    HTTP client for outbound HTTP requests

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

    The post() function wraps the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    The head() function wraps the underlying HTTP actions 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:ByteChannel|mime:Entity[]? null

    An optional HTTP outbound request message or or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    The put() function wraps the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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 actions 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:ByteChannel|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 actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    The patch() function wraps the undeline underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    The delete() function wraps the underlying HTTP actions 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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    The get() function wraps the underlying HTTP actions 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:ByteChannel|mime:Entity[]? null

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|mime:Entity[]? message) returns (Response | error)

    The options() function wraps the underlying HTTP actions 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:ByteChannel|mime:Entity[]? null

    An optional HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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:ByteChannel|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:ByteChannel|mime:Entity[]?

    An HTTP outbound request message or any payload of type string, xml, json, byte[], io:ByteChannel 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

public type SecureListenerActions object

The caller actions for responding to client requests to secure listener.

Field Name Data Type Default Value Description
httpCallerActions http:Connection
  • <SecureListenerActions> respond(http:Response|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?

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

    Return Type Description
    error

    Returns an error if failed to respond

  • <SecureListenerActions> 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

  • <SecureListenerActions> 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

  • <SecureListenerActions> acceptWebSocketUpgrade(map headers) returns (WebSocketListener)

    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
    WebSocketListener
  • <SecureListenerActions> cancelWebSocketUpgrade(int status, string reason) returns (error | null)

    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 | null

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

  • <SecureListenerActions> 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

  • <SecureListenerActions> redirect(http:Response response, 305|302|300|303|304|307|308|301 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 305|302|300|303|304|307|308|301

    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

public type Service object

A representation of an HTTP service instance.

  • <Service> getEndpoint() returns (Listener)

    Returns a Listener for the service.

    Return Type Description
    Listener

    A Listener instance for the service

public type WebSocketClientService object

Represents the WebSocket client service.

  • <WebSocketClientService> getEndpoint() returns (WebSocketClient)

    Return Type Description
    WebSocketClient

public type WebSocketConnector object

Represents a WebSocket connector in ballerina. This include all connector oriented operations.

  • <WebSocketConnector> pushText(string text, boolean final) returns (error)

    Push text to the connection.

    Parameter Name Data Type Default Value Description
    text string

    Text to be sent

    final boolean true

    True if this is a final frame of a (long) message

    Return Type Description
    error

    error if an error occurs when sending

  • <WebSocketConnector> pushBinary(byte[] data, boolean final) returns (error)

    Push binary data to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]

    Binary data to be sent

    final boolean true

    True if this is a final frame of a (long) message

    Return Type Description
    error

    error if an error occurs when sending

  • <WebSocketConnector> 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

  • <WebSocketConnector> 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

  • <WebSocketConnector> close(int statusCode, string reason, int timeoutInSecs) returns (error)

    Close the connection.

    Parameter Name Data Type Default Value Description
    statusCode int

    Status code for closing the connection

    reason string

    Reason for closing the connection

    timeoutInSecs int 60

    Time to waits for the close frame 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 (eg: -1) 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

  • <WebSocketConnector> 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

public type WebSocketService object

Represents the WebSocket client service.

  • <WebSocketService> getEndpoint() returns (WebSocketListener)

    Return Type Description
    WebSocketListener

Endpoint APIListener

Representation of an API Listener.

Field Name Data Type Default Value Description
config http:SecureEndpointConfiguration

SecureEndpointConfiguration instance

secureListener http:SecureListener

Secure HTTP Listener instance

  • <APIListener> respond(http:Response|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?
    Return Type Description
    error?
  • <APIListener> promise(http:PushPromise promise) returns (error?)

    Pushes a promise to the caller.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    error?
  • <APIListener> 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
    response http:Response
    Return Type Description
    error?
  • <APIListener> acceptWebSocketUpgrade(map headers) returns (http:WebSocketListener)

    Sends an upgrade request with custom headers.

    Parameter Name Data Type Default Value Description
    headers map
    Return Type Description
    http:WebSocketListener
  • <APIListener> cancelWebSocketUpgrade(int status, string reason) returns (error?)

    Cancels the handshake.

    Parameter Name Data Type Default Value Description
    status int
    reason string
    Return Type Description
    error?
  • <APIListener> continue() returns (error?)

    Sends a `100-continue` response to the caller.

    Return Type Description
    error?
  • <APIListener> redirect(http:Response response, 305|302|300|303|304|307|308|301 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
    code 305|302|300|303|304|307|308|301
    locations string[]
    Return Type Description
    error?

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
epName string

The name of the client

config http:ClientEndpointConfig

The configurations associated with the client

httpClient http:CallerActions

The provider which implements the HTTP methods

  • <Client> post(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> head(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> put(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    Invokes an HTTP call with the specified HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> patch(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> delete(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> get(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> options(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <Client> forward(string path, http:Request request) returns (http: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 http:Request
    Return Type Description
    http:Response|error
  • <Client> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:HttpFuture|error
  • <Client> getResponse(http:HttpFuture httpFuture) returns (http:Response|error)

    Retrieves the `Response` for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture
    Return Type Description
    http:Response|error
  • <Client> 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
    Return Type Description
    boolean
  • <Client> getNextPromise(http:HttpFuture httpFuture) returns (http:PushPromise|error)

    Retrieves the next available `PushPromise` for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture
    Return Type Description
    http:PushPromise|error
  • <Client> getPromisedResponse(http:PushPromise promise) returns (http:Response|error)

    Retrieves the promised server push `Response` message.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    http:Response|error
  • <Client> rejectPromise(http:PushPromise promise) returns (())

    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
    Return Type Description
    ()

Endpoint FailoverClient

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

Field Name Data Type Default Value Description
epName string

Name of the endpoint

failoverClientConfig http:FailoverClientEndpointConfiguration

The configurations for the failover client endpoint

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

    The POST action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> head(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The HEAD action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> patch(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The PATCH action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> put(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The PUT action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> options(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The OPTIONS action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> forward(string path, http:Request request) returns (http:Response|error)

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

    Parameter Name Data Type Default Value Description
    path string
    request http:Request
    Return Type Description
    http:Response|error
  • <FailoverClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    Invokes an HTTP call with the specified HTTP method.

    Parameter Name Data Type Default Value Description
    httpVerb string
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> delete(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The DELETE action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> get(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The GET action implementation of the Failover Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <FailoverClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http: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
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:HttpFuture|error
  • <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
    Return Type Description
    error
  • <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
    Return Type Description
    boolean
  • <FailoverClient> getNextPromise(http:HttpFuture httpFuture) returns (http:PushPromise|error)

    Retrieves the next available `PushPromise` for a previously submitted request.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture
    Return Type Description
    http:PushPromise|error
  • <FailoverClient> getPromisedResponse(http:PushPromise promise) returns (http:Response|error)

    Retrieves the promised server push `Response` message.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    http:Response|error
  • <FailoverClient> rejectPromise(http:PushPromise promise) returns (())

    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
    Return Type Description
    ()

Endpoint Listener

This is used for creating HTTP service endpoints. An HTTP service endpoint is capable of responding to remote callers. The Listener is responsible for initializing the endpoint using the provided configurations and providing the actions for communicating with the caller.

Field Name Data Type Default Value Description
remote http:Remote

The remote address

local http:Local

The local address

protocol string

The protocol associated with the service endpoint

  • <Listener> respond(http:Response|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?
    Return Type Description
    error?
  • <Listener> promise(http:PushPromise promise) returns (error?)

    Pushes a promise to the caller.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    error?
  • <Listener> 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
    response http:Response
    Return Type Description
    error?
  • <Listener> acceptWebSocketUpgrade(map headers) returns (http:WebSocketListener)

    Sends an upgrade request with custom headers.

    Parameter Name Data Type Default Value Description
    headers map
    Return Type Description
    http:WebSocketListener
  • <Listener> cancelWebSocketUpgrade(int status, string reason) returns (error?)

    Cancels the handshake.

    Parameter Name Data Type Default Value Description
    status int
    reason string
    Return Type Description
    error?
  • <Listener> continue() returns (error?)

    Sends a `100-continue` response to the caller.

    Return Type Description
    error?
  • <Listener> redirect(http:Response response, 305|302|300|303|304|307|308|301 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
    code 305|302|300|303|304|307|308|301
    locations string[]
    Return Type Description
    error?

Endpoint LoadBalanceClient

LoadBalanceClient endpoint provides load balancing functionality over multiple HTTP clients.

Field Name Data Type Default Value Description
epName string

Name of the endpoint

loadBalanceClientConfig http:LoadBalanceClientEndpointConfiguration

The configurations for the load balance client endpoint

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

    The POST action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> head(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The HEAD action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> patch(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The PATCH action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> put(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The PUT action implementation of the Load Balance Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> options(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The OPTIONS action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> forward(string path, http:Request request) returns (http:Response|error)

    The FORWARD action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string
    request http:Request
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> execute(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The EXECUTE action implementation of the LoadBalancer Connector. The Execute action can be used to invoke an HTTP call with the given HTTP verb.

    Parameter Name Data Type Default Value Description
    httpVerb string
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> delete(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The DELETE action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> get(string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:Response|error)

    The GET action implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> submit(string httpVerb, string path, http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]? message) returns (http:HttpFuture|error)

    The submit implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpVerb string
    path string
    message http:Request|string|xml|json|byte[]|io:ByteChannel|mime:Entity[]?
    Return Type Description
    http:HttpFuture|error
  • <LoadBalanceClient> getResponse(http:HttpFuture httpFuture) returns (http:Response|error)

    The getResponse implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> hasPromise(http:HttpFuture httpFuture) returns (boolean)

    The hasPromise implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture
    Return Type Description
    boolean
  • <LoadBalanceClient> getNextPromise(http:HttpFuture httpFuture) returns (http:PushPromise|error)

    The getNextPromise implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    httpFuture http:HttpFuture
    Return Type Description
    http:PushPromise|error
  • <LoadBalanceClient> getPromisedResponse(http:PushPromise promise) returns (http:Response|error)

    The getPromisedResponse implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    http:Response|error
  • <LoadBalanceClient> rejectPromise(http:PushPromise promise) returns (())

    The rejectPromise implementation of the LoadBalancer Connector.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    ()

Endpoint NonListener

Mock service endpoint which does not open a listening port.

  • <NonListener> respond(http:Response|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?
    Return Type Description
    error?
  • <NonListener> promise(http:PushPromise promise) returns (error?)

    Pushes a promise to the caller.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    error?
  • <NonListener> 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
    response http:Response
    Return Type Description
    error?
  • <NonListener> acceptWebSocketUpgrade(map headers) returns (http:WebSocketListener)

    Sends an upgrade request with custom headers.

    Parameter Name Data Type Default Value Description
    headers map
    Return Type Description
    http:WebSocketListener
  • <NonListener> cancelWebSocketUpgrade(int status, string reason) returns (error?)

    Cancels the handshake.

    Parameter Name Data Type Default Value Description
    status int
    reason string
    Return Type Description
    error?
  • <NonListener> continue() returns (error?)

    Sends a `100-continue` response to the caller.

    Return Type Description
    error?
  • <NonListener> redirect(http:Response response, 305|302|300|303|304|307|308|301 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
    code 305|302|300|303|304|307|308|301
    locations string[]
    Return Type Description
    error?

Endpoint SecureListener

Defines Secure Listener endpoint.

Field Name Data Type Default Value Description
config http:SecureEndpointConfiguration

SecureEndpointConfiguration instance

httpListener http:Listener

HTTP Listener instance

  • <SecureListener> respond(http:Response|string|xml|json|byte[]|io:ByteChannel|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:ByteChannel|mime:Entity[]?
    Return Type Description
    error?
  • <SecureListener> promise(http:PushPromise promise) returns (error?)

    Pushes a promise to the caller.

    Parameter Name Data Type Default Value Description
    promise http:PushPromise
    Return Type Description
    error?
  • <SecureListener> 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
    response http:Response
    Return Type Description
    error?
  • <SecureListener> acceptWebSocketUpgrade(map headers) returns (http:WebSocketListener)

    Sends an upgrade request with custom headers.

    Parameter Name Data Type Default Value Description
    headers map
    Return Type Description
    http:WebSocketListener
  • <SecureListener> cancelWebSocketUpgrade(int status, string reason) returns (error?)

    Cancels the handshake.

    Parameter Name Data Type Default Value Description
    status int
    reason string
    Return Type Description
    error?
  • <SecureListener> continue() returns (error?)

    Sends a `100-continue` response to the caller.

    Return Type Description
    error?
  • <SecureListener> redirect(http:Response response, 305|302|300|303|304|307|308|301 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
    code 305|302|300|303|304|307|308|301
    locations string[]
    Return Type Description
    error?

Endpoint WebSocketClient

Represents a WebSocket client endpoint.

Field Name Data Type Default Value Description
id string

The connection id

negotiatedSubProtocol string

The subprotocols negoriated with the server

isSecure boolean

true if the connection is secure

isOpen boolean

true if the connection is open

response http:Response
attributes map

A map to store connection related attributes

  • <WebSocketClient> pushText(string text, boolean final) returns (error?)

    Push text to the connection.

    Parameter Name Data Type Default Value Description
    text string
    final boolean
    Return Type Description
    error?
  • <WebSocketClient> pushBinary(byte[] data, boolean final) returns (error?)

    Push binary data to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]
    final boolean
    Return Type Description
    error?
  • <WebSocketClient> ping(byte[] data) returns (error?)

    Ping the connection.

    Parameter Name Data Type Default Value Description
    data byte[]
    Return Type Description
    error?
  • <WebSocketClient> pong(byte[] data) returns (error?)

    Send pong message to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]
    Return Type Description
    error?
  • <WebSocketClient> close(int statusCode, string reason, int timeoutInSecs) returns (error?)

    Close the connection.

    Parameter Name Data Type Default Value Description
    statusCode int
    reason string
    timeoutInSecs int
    Return Type Description
    error?
  • <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?

Endpoint WebSocketListener

Represents a WebSocket service endpoint.

Field Name Data Type Default Value Description
id string

The connection ID

negotiatedSubProtocol string

The subprotocols negotiated with the client

isSecure boolean

true if the connection is secure

isOpen boolean

true if the connection is open

attributes map

A map to store connection related attributes

  • <WebSocketListener> pushText(string text, boolean final) returns (error?)

    Push text to the connection.

    Parameter Name Data Type Default Value Description
    text string
    final boolean
    Return Type Description
    error?
  • <WebSocketListener> pushBinary(byte[] data, boolean final) returns (error?)

    Push binary data to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]
    final boolean
    Return Type Description
    error?
  • <WebSocketListener> ping(byte[] data) returns (error?)

    Ping the connection.

    Parameter Name Data Type Default Value Description
    data byte[]
    Return Type Description
    error?
  • <WebSocketListener> pong(byte[] data) returns (error?)

    Send pong message to the connection.

    Parameter Name Data Type Default Value Description
    data byte[]
    Return Type Description
    error?
  • <WebSocketListener> close(int statusCode, string reason, int timeoutInSecs) returns (error?)

    Close the connection.

    Parameter Name Data Type Default Value Description
    statusCode int
    reason string
    timeoutInSecs int
    Return Type Description
    error?
  • <WebSocketListener> 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?