Module http
API
Declarations
Definitions
ballerina/http Ballerina library
Overview
This module provides APIs for connecting and interacting with HTTP and HTTP2 endpoints. It
facilitates two types of network entry points as the Client
and Listener
.
Client
The Client
is 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. The Client
activates connection eviction after a given idle period and also supports follow-redirects so that you do not
have to manually handle 3xx HTTP status codes.
Resiliency
The Client
handles resilience in multiple ways such as load balancing, circuit breaking, endpoint timeouts, and via 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). The Client
also supports a retry
mechanism that allows it to resend failed requests periodically for a given number of times.
Security
The Client
supports Server Name Indication (SNI), Certificate Revocation List (CRL), Online Certificate Status
Protocol (OCSP), and OCSP Stapling for SSL/TLS connections.
Also, the Client
can be configured to send authentication information to the endpoint being invoked. Ballerina has
built-in support for Basic authentication, JWT authentication, and OAuth2 authentication.
In addition to that, it supports both HTTP/1.1 and HTTP2 protocols and connection keep-alive, content
chunking, HTTP caching, data compression/decompression, response payload binding, and authorization can be highlighted as the features of the Clients
.
A Client
can be defined using the URL of the remote service that it needs to connect with as shown below:
http:Client clientEndpoint = check new("https://my-simple-backend.com");
The defined Client
endpoint can be used to call a remote service as follows:
// Send a GET request to the specified endpoint. http:Response response = check clientEndpoint->get("/get?id=123");
The payload can be retrieved as the return value from the remote function as follows:
// Retrieve payload as json. json payload = check clientEndpoint->post("/backend/Json", "foo");
Listener
The Listener
is the underneath server connector that binds the given IP/Port to the network and it's behavior can
be changed using the http:ListenerConfiguration
. In HTTP, the http:Service
-typed services can be attached to
the Listener
. The service type precisely describes the syntax for both the service and resource.
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, the HTTP method and resource path are mandatory parameters and
the String literal and path parameters can be stated as the path. The resource function accepts the http:Caller
, http:Request
,
http:Headers
, query parameters, header parameters, and payload parameters as arguments. However, they are optional.
When a Service
receives a request, it is dispatched to the best-matched resource.
A Listener
endpoint can be defined as follows:
// Attributes associated with the `Listener` endpoint are defined here. listener http:Listener helloWorldEP = new(9090);
Then a Service
can be defined and attached to the above Listener
endpoint as shown below:
// By default, Ballerina assumes that the service is to be exposed via HTTP/1.1. service /helloWorld on helloWorldEP { resource function post [string name](@http:Payload string message) returns string { // Sends the response back to the client along with a string payload. return "Hello, World! I’m " + name + ". " + message; } }
Security
Listener
endpoints can be exposed via SSL. They support Mutual SSL, Hostname Verification, and Application Layer
Protocol Negotiation (ALPN) for HTTP2. Listener
endpoints also support Certificate Revocation List (CRL), Online
Certificate Status Protocol (OCSP), and OCSP Stapling.
Also, The listener
can be configured to authenticate and authorize the inbound requests. Ballerina has
built-in support for basic authentication, JWT authentication, and OAuth2 authentication.
In addition to that, supports both the HTTP/1.1 and HTTP2 protocols and connection keep-alive, content
chunking, HTTP caching, data compression/decompression, payload binding, and authorization can be highlighted as the features of a Service
.
Functions
authenticateResource
Uses for declarative auth design, where the authentication/authorization decision is taken
by reading the auth annotations provided in service/resource and the Authorization
header of request.
createHttpCachingClient
function createHttpCachingClient(string url, ClientConfiguration config, CacheConfig cacheConfig) returns HttpClient|ClientError
Creates an HTTP client capable of caching HTTP responses.
Parameters
- url string - The URL of the HTTP endpoint to connect
- config ClientConfiguration - The configurations for the client endpoint associated with the caching client
- cacheConfig CacheConfig - The configurations for the HTTP cache to be used with the caching client
Return Type
- HttpClient|ClientError - An
http:HttpCachingClient
instance, which wraps the basehttp:Client
with a caching layer or else anhttp:ClientError
createHttpSecureClient
function createHttpSecureClient(string url, ClientConfiguration config) returns HttpClient|ClientError
Creates an HTTP client capable of securing HTTP requests with authentication.
Return Type
- HttpClient|ClientError - Created secure HTTP client
parseHeader
function parseHeader(string headerValue) returns HeaderValue[]|ClientError
Parses the header value which contains multiple values or parameters.
http:HeaderValue[] values = check http:parseHeader("text/plain;level=1;q=0.6, application/xml;level=2");
Parameters
- headerValue string - The header value
Return Type
- HeaderValue[]|ClientError - An array of
http:HeaderValue
typed record containing the value and its parameter map or else anhttp:ClientError
if the header parsing fails
Classes
http: ClientBasicAuthHandler
Defines the Basic Auth handler for client authentication.
Constructor
Initializes the http:ClientBasicAuthHandler
object.
init (CredentialsConfig config)
- config CredentialsConfig - The
http:CredentialsConfig
instance
enrich
function enrich(Request req) returns Request|ClientAuthError
Enrich the request with the relevant authentication requirements.
Parameters
- req Request - The
http:Request
instance
Return Type
- Request|ClientAuthError - The updated
http:Request
instance or else anhttp:ClientAuthError
in case of an error
enrichHeaders
Enrich the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
getSecurityHeaders
function getSecurityHeaders() returns map<string|string[]>|ClientAuthError
Returns the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
http: ClientBearerTokenAuthHandler
Defines the Bearer token auth handler for client authentication.
Constructor
Initializes the http:ClientBearerTokenAuthHandler
object.
init (BearerTokenConfig config)
- config BearerTokenConfig - The
http:BearerTokenConfig
instance
enrich
function enrich(Request req) returns Request|ClientAuthError
Enrich the request with the relevant authentication requirements.
Parameters
- req Request - The
http:Request
instance
Return Type
- Request|ClientAuthError - The updated
http:Request
instance or else anhttp:ClientAuthError
in case of an error
enrichHeaders
Enrich the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
getSecurityHeaders
function getSecurityHeaders() returns map<string|string[]>|ClientAuthError
Returns the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
http: ClientSelfSignedJwtAuthHandler
Defines the self signed JWT handler for client authentication.
Constructor
Initializes the http:ClientSelfSignedJwtAuthProvider
object.
init (JwtIssuerConfig config)
- config JwtIssuerConfig - The
http:JwtIssuerConfig
instance
enrich
function enrich(Request req) returns Request|ClientAuthError
Enrich the request with the relevant authentication requirements.
Parameters
- req Request - The
http:Request
instance
Return Type
- Request|ClientAuthError - The updated
http:Request
instance or else anhttp:ClientAuthError
in case of an error
enrichHeaders
Enrich the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
getSecurityHeaders
function getSecurityHeaders() returns map<string|string[]>|ClientAuthError
Returns the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
http: Cookie
Represents a Cookie.
Constructor
Initializes the http:Cookie
object.
init (string name, string value, *CookieOptions options)
- name string - Name of the
http:Cookie
- value string - Value of the
http:Cookie
- options *CookieOptions - The options to be used when initializing the
http:Cookie
isPersistent
function isPersistent() returns boolean
Checks the persistence of the cookie.
Return Type
- boolean -
false
if the cookie will be discarded at the end of the "session" or elsetrue
.
isValid
function isValid() returns boolean|InvalidCookieError
Checks the validity of the attributes of the cookie.
Return Type
- boolean|InvalidCookieError -
true
if the attributes of the cookie are in the correct format or else anhttp:InvalidCookieError
toStringValue
function toStringValue() returns string
Gets the Cookie object in its string representation to be used in the ‘Set-Cookie’ header of the response.
Return Type
- string - The string value of the
http:Cookie
Fields
- name string - Name of the cookie
- value string - Value of the cookie
- path string? - URI path to which the cookie belongs
- domain string? - Host to which the cookie will be sent
- expires string? - Maximum lifetime of the cookie represented as the date and time at which the cookie expires
- maxAge int - Maximum lifetime of the cookie represented as the number of seconds until the cookie expires
- httpOnly boolean - Cookie is sent only to HTTP requests
- secure boolean - Cookie is sent only to secure channels
- createdTime Utc - At what time the cookie was created
- lastAccessedTime Utc - Last-accessed time of the cookie
- hostOnly boolean - Cookie is sent only to the requested host
http: CookieStore
Represents the cookie store.
addCookie
function addCookie(Cookie cookie, CookieConfig cookieConfig, string url, string requestPath) returns CookieHandlingError?
Adds a cookie to the cookie store according to the rules in RFC-6265.
Parameters
- cookie Cookie - Cookie to be added
- cookieConfig CookieConfig - Configurations associated with the cookies
- url string - Target service URL
- requestPath string - Resource path
Return Type
- CookieHandlingError? - An
http:CookieHandlingError
if there is any error occurred when adding a cookie or else()
addCookies
function addCookies(Cookie[] cookiesInResponse, CookieConfig cookieConfig, string url, string requestPath)
Adds an array of cookies.
Parameters
- cookiesInResponse Cookie[] - Cookies to be added
- cookieConfig CookieConfig - Configurations associated with the cookies
- url string - Target service URL
- requestPath string - Resource path
getCookies
Gets the relevant cookies for the given URL and the path according to the rules in RFC-6265.
Return Type
- Cookie[] - Array of the matched cookies stored in the cookie store
getAllCookies
function getAllCookies() returns Cookie[]
Gets all the cookies in the cookie store.
Return Type
- Cookie[] - Array of all the cookie objects
getCookiesByName
Gets all the cookies, which have the given name as the name of the cookie.
Parameters
- cookieName string - Name of the cookie
Return Type
- Cookie[] - Array of all the matched cookie objects
getCookiesByDomain
Gets all the cookies, which have the given name as the domain of the cookie.
Parameters
- domain string - Name of the domain
Return Type
- Cookie[] - Array of all the matched cookie objects
removeCookie
function removeCookie(string name, string domain, string path) returns CookieHandlingError?
Removes a specific cookie.
Parameters
- name string - Name of the cookie to be removed
- domain string - Domain of the cookie to be removed
- path string - Path of the cookie to be removed
Return Type
- CookieHandlingError? - An
http:CookieHandlingError
if there is any error occurred during the removal of the cookie or else()
removeCookiesByDomain
function removeCookiesByDomain(string domain) returns CookieHandlingError?
Removes cookies, which match with the given domain.
Parameters
- domain string - Domain of the cookie to be removed
Return Type
- CookieHandlingError? - An
http:CookieHandlingError
if there is any error occurred during the removal of cookies by domain or else()
removeExpiredCookies
function removeExpiredCookies() returns CookieHandlingError?
Removes all expired cookies.
Return Type
- CookieHandlingError? - An
http:CookieHandlingError
if there is any error occurred during the removal of expired cookies or else()
removeAllCookies
function removeAllCookies() returns CookieHandlingError?
Removes all the cookies.
Return Type
- CookieHandlingError? - An
http:CookieHandlingError
if there is any error occurred during the removal of all the cookies or else()
http: CsvPersistentCookieHandler
Represents a default persistent cookie handler, which stores persistent cookies in a CSV file.
storeCookie
function storeCookie(Cookie cookie) returns CookieHandlingError?
Adds a persistent cookie to the cookie store.
Parameters
- cookie Cookie - Cookie to be added
Return Type
- CookieHandlingError? - An error will be returned if there is any error occurred during the storing process of the cookie or else nil is returned
getAllCookies
function getAllCookies() returns Cookie[]|CookieHandlingError
Gets all the persistent cookies.
Return Type
- Cookie[]|CookieHandlingError - Array of persistent cookies stored in the cookie store or else an error is returned if one occurred during the retrieval of the cookies
removeCookie
function removeCookie(string name, string domain, string path) returns CookieHandlingError?
Removes a specific persistent cookie.
Parameters
- name string - Name of the persistent cookie to be removed
- domain string - Domain of the persistent cookie to be removed
- path string - Path of the persistent cookie to be removed
Return Type
- CookieHandlingError? - An error will be returned if there is any error occurred during the removal of the cookie or else nil is returned
removeAllCookies
function removeAllCookies() returns CookieHandlingError?
Removes all persistent cookies.
Return Type
- CookieHandlingError? - An error will be returned if there is any error occurred during the removal of all the cookies or else nil is returned
http: Headers
Represents the headers of the inbound request.
hasHeader
Checks whether the requested header key exists in the header map.
Parameters
- headerName string - The header name
Return Type
- boolean -
true
if the specified header key exists
getHeader
function getHeader(string headerName) returns string|HeaderNotFoundError
Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.
Parameters
- headerName string - The header name
Return Type
- string|HeaderNotFoundError - The first header value for the specified header name or the
HeaderNotFoundError
if the header is not found.
getHeaders
function getHeaders(string headerName) returns string[]|HeaderNotFoundError
Gets all the header values to which the specified header key maps to.
Parameters
- headerName string - The header name
Return Type
- string[]|HeaderNotFoundError - The header values the specified header key maps to or the
HeaderNotFoundError
if the header is not found.
getHeaderNames
function getHeaderNames() returns string[]
Gets all the names of the headers of the request.
Return Type
- string[] - An array of all the header names
http: 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.
Constructor
Creates the HTTP cache.
init (CacheConfig cacheConfig)
- cacheConfig CacheConfig - The configurations for the HTTP cache
http: 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.
http: ListenerFileUserStoreBasicAuthHandler
Defines the file store Basic Auth handler for listener authentication.
Constructor
Initializes the http:ListenerFileUserStoreBasicAuthHandler
object.
init (FileUserStoreConfig config)
- config FileUserStoreConfig {} - The
http:FileUserStoreConfig
instance
authenticate
function authenticate(Request|Headers|string data) returns UserDetails|Unauthorized
Authenticates with the relevant authentication requirements.
Parameters
Return Type
- UserDetails|Unauthorized - The
auth:UserDetails
instance or elseUnauthorized
type in case of an error
authorize
function authorize(UserDetails userDetails, string|string[] expectedScopes) returns Forbidden?
Authorizes with the relevant authorization requirements.
Parameters
- userDetails UserDetails - The
auth:UserDetails
instance which is received from authentication results
Return Type
- Forbidden? -
()
, if it is successful or elseForbidden
type in case of an error
http: ListenerJwtAuthHandler
Defines the JWT auth handler for listener authentication.
Constructor
Initializes the http:ListenerJwtAuthHandler
object.
init (JwtValidatorConfig config)
- config JwtValidatorConfig - The
http:JwtValidatorConfig
instance
authenticate
function authenticate(Request|Headers|string data) returns Payload|Unauthorized
Authenticates with the relevant authentication requirements.
Parameters
Return Type
- Payload|Unauthorized - The
jwt:Payload
instance or elseUnauthorized
type in case of an error
authorize
Authorizes with the relevant authorization requirements.
Parameters
- jwtPayload Payload - The
jwt:Payload
instance which is received from authentication results
Return Type
- Forbidden? -
()
, if it is successful or elseForbidden
type in case of an error
http: LoadBalancerRoundRobinRule
Implementation of round robin load balancing strategy.
getNextClient
function getNextClient(Client?[] loadBalanceCallerActionsArray) returns Client|ClientError
Provides an HTTP client, which is chosen according to the round robin algorithm.
Parameters
- loadBalanceCallerActionsArray Client?[] - Array of HTTP clients, which needs to be load balanced
Return Type
- Client|ClientError - Chosen
http:Client
from the algorithm or else anhttp:ClientError
for a failure in the algorithm implementation
http: PushPromise
Represents an HTTP/2 PUSH_PROMISE
frame.
Constructor
Constructs an http:PushPromise
from a given path and a method.
init (string path, string method)
hasHeader
Checks whether the requested header exists.
Parameters
- headerName string - The header name
Return Type
- boolean - A
boolean
representing the existence of a given header
getHeader
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.
Parameters
- headerName string - The header name
Return Type
- string - The header value or
()
if there is no such header
getHeaders
Gets transport headers from the PushPromise
.
Parameters
- headerName string - The header name
Return Type
- string[] - The array of header values
addHeader
Adds the specified key/value pair as an HTTP header to the http:PushPromise
.
setHeader
Sets the value of a transport header in the http:PushPromise
.
removeHeader
function removeHeader(string headerName)
Removes a transport header from the http:PushPromise
.
Parameters
- headerName string - The header name
removeAllHeaders
function removeAllHeaders()
Removes all transport headers from the http:PushPromise
.
getHeaderNames
function getHeaderNames() returns string[]
Gets all transport header names from the http:PushPromise
.
Return Type
- string[] - An array of all transport header names
Fields
- path string - The resource path
- method string - The HTTP method
http: Request
Represents an HTTP request.
setEntity
function setEntity(Entity e)
Sets the provided Entity
to the request.
Parameters
- e Entity - The
Entity
to be set to the request
getQueryParams
Gets the query parameters of the request as a map consisting of a string array.
getQueryParamValue
Gets the query param value associated with the given key.
Parameters
- key string - Represents the query param key
Return Type
- string? - The query param value associated with the given key as a string. If multiple param values are
present, then the first value is returned.
()
is returned if no key is found.
getQueryParamValues
Gets all the query param values associated with the given key.
Parameters
- key string - Represents the query param key
Return Type
- string[]? - All the query param values associated with the given key as a
string[]
.()
is returned if no key is found.
getMatrixParams
Gets the matrix parameters of the request.
Parameters
- path string - Path to the location of matrix parameters
Return Type
- map<any> - A map of matrix parameters which can be found for the given path
getEntity
function getEntity() returns Entity|ClientError
Gets the Entity
associated with the request.
Return Type
- Entity|ClientError - The
Entity
of the request. Anhttp:ClientError
is returned, if entity construction fails
hasHeader
Checks whether the requested header key exists in the header map.
Parameters
- headerName string - The header name
Return Type
- boolean -
true
if the specified header key exists
getHeader
function getHeader(string headerName) returns string|HeaderNotFoundError
Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.
Parameters
- headerName string - The header name
Return Type
- string|HeaderNotFoundError - The first header value for the specified header name or the
HeaderNotFoundError
if the header is not found.
getHeaders
function getHeaders(string headerName) returns string[]|HeaderNotFoundError
Gets all the header values to which the specified header key maps to.
Parameters
- headerName string - The header name
Return Type
- string[]|HeaderNotFoundError - The header values the specified header key maps to or the
HeaderNotFoundError
if the header is not found.
setHeader
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 specified header value. Panic if an illegal header is passed.
addHeader
Adds the specified header to the request. Existing header values are not replaced. Panic if an illegal header is passed.
removeHeader
function removeHeader(string headerName)
Removes the specified header from the request.
Parameters
- headerName string - The header name
removeAllHeaders
function removeAllHeaders()
Removes all the headers from the request.
getHeaderNames
function getHeaderNames() returns string[]
Gets all the names of the headers of the request.
Return Type
- string[] - An array of all the header names
expects100Continue
function expects100Continue() returns boolean
Checks whether the client expects a 100-continue
response.
Return Type
- boolean -
true
if the client expects a100-continue
response
setContentType
Sets the content-type
header to the request.
Parameters
- contentType string - Content type value to be set as the
content-type
header
Return Type
- error? - Nil if successful, error in case of invalid content-type
getContentType
function getContentType() returns string
Gets the type of the payload of the request (i.e: the content-type
header value).
Return Type
- string - The
content-type
header value as a string
getJsonPayload
function getJsonPayload() returns json|ClientError
Extract json
payload from the request. For an empty payload, http:NoContentError
is returned.
If the content type is not JSON, an http:ClientError
is returned.
Return Type
- json|ClientError - The
json
payload orhttp:ClientError
in case of errors
getXmlPayload
function getXmlPayload() returns xml|ClientError
Extracts xml
payload from the request. For an empty payload, http:NoContentError
is returned.
If the content type is not XML, an http:ClientError
is returned.
Return Type
- xml|ClientError - The
xml
payload orhttp:ClientError
in case of errors
getTextPayload
function getTextPayload() returns string|ClientError
Extracts text
payload from the request. For an empty payload, http:NoContentError
is returned.
If the content type is not of type text, an http:ClientError
is returned.
Return Type
- string|ClientError - The
text
payload orhttp:ClientError
in case of errors
getByteStream
function getByteStream(int arraySize) returns stream<byte[], Error?>|ClientError
Gets the request payload as a stream of byte[], except in the case of multiparts. To retrieve multiparts, use
Request.getBodyParts()
.
Parameters
- arraySize int (default 8192) - A defaultable parameter to state the size of the byte array. Default size is 8KB
Return Type
- stream<byte[], Error?>|ClientError - A byte stream from which the message payload can be read or
http:ClientError
in case of errors
getBinaryPayload
function getBinaryPayload() returns byte[]|ClientError
Gets the request payload as a byte[]
.
Return Type
- byte[]|ClientError - The byte[] representation of the message payload or
http:ClientError
in case of errors
getFormParams
function getFormParams() returns map<string>|ClientError
Gets the form parameters from the HTTP request as a map
when content type is application/x-www-form-urlencoded.
Return Type
- map<string>|ClientError - The map of form params or
http:ClientError
in case of errors
getBodyParts
function getBodyParts() returns Entity[]|ClientError
Extracts body parts from the request. If the content type is not a composite media type, an error is returned.
Return Type
- Entity[]|ClientError - The body parts as an array of entities or else an
http:ClientError
if there were any errors constructing the body parts from the request
setJsonPayload
function setJsonPayload(json payload, string? contentType)
Sets a json
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/json
. Any existing content-type can be
overridden by passing the content-type as an optional parameter.
Parameters
- payload json - The
json
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
application/json
is the default value
setXmlPayload
Sets an xml
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/xml
. Any existing content-type can be
overridden by passing the content-type as an optional parameter.
Parameters
- payload xml - The
xml
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
application/xml
is the default value
setTextPayload
Sets a string
as the payload. If the content-type header is not set then this method set
content-type headers with the default content-type, which is text/plain
. Any
existing content-type can be overridden by passing the content-type as an optional parameter.
Parameters
- payload string - The
string
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
text/plain
is the default value
setBinaryPayload
function setBinaryPayload(byte[] payload, string? contentType)
Sets a byte[]
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/octet-stream
. Any existing content-type
can be overridden by passing the content-type as an optional parameter.
Parameters
- payload byte[] - The
byte[]
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
application/octet-stream
is the default value
setBodyParts
Set multiparts as the payload. If the content-type header is not set then this method
set content-type headers with the default content-type, which is multipart/form-data
.
Any existing content-type can be overridden by passing the content-type as an optional parameter.
Parameters
- bodyParts Entity[] - The entities which make up the message body
- contentType string? (default ()) - The content type of the top level message. This is an optional parameter.
The
multipart/form-data
is the default value
setFileAsPayload
Sets the content of the specified file as the entity body of the request. If the content-type header
is not set then this method set content-type headers with the default content-type, which is
application/octet-stream
. Any existing content-type can be overridden by passing the content-type
as an optional parameter.
Parameters
- filePath string - Path to the file to be set as the payload
- contentType string? (default ()) - The content type of the specified file. This is an optional parameter.
The
application/octet-stream
is the default value
setByteStream
Sets a Stream
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/octet-stream
. Any existing content-type can
be overridden by passing the content-type as an optional parameter.
Parameters
- contentType string? (default ()) - Content-type to be used with the payload. This is an optional parameter.
The
application/octet-stream
is the default value
setPayload
function setPayload(string|xml|json|byte[]|Entity[]|stream<byte[], Error?> payload, string? contentType)
Sets the request payload. This method overrides any existing content-type by passing the content-type as an optional parameter. If the content type parameter is not provided then the default value derived from the payload will be used as content-type only when there are no existing content-type header.
Parameters
- contentType string? (default ()) - Content-type to be used with the payload. This is an optional parameter
addCookies
function addCookies(Cookie[] cookiesToAdd)
Adds cookies to the request.
Parameters
- cookiesToAdd Cookie[] - Represents the cookies to be added
getCookies
function getCookies() returns Cookie[]
Gets cookies from the request.
Return Type
- Cookie[] - An array of cookie objects, which are included in the request
Fields
- rawPath string(default "") - Resource path of the request URL
- method string(default "") - The HTTP request method
- httpVersion string(default "") - The HTTP version supported by the client
- userAgent string(default "") - The user-agent. This value is used when setting the
user-agent
header
- extraPathInfo string(default "") - The part of the URL, which matched to '*' if the request is dispatched to a wildcard resource
- cacheControl RequestCacheControl?(default ()) - The cache-control directives for the request. This needs to be explicitly initialized if intending on utilizing HTTP caching.
- mutualSslHandshake MutualSslHandshake?(default ()) - A record providing mutual ssl handshake results.
http: RequestCacheControl
Configures the cache control directives for an http:Request
.
buildCacheControlDirectives
function buildCacheControlDirectives() returns string
Builds the cache control directives string from the current http:RequestCacheControl
configurations.
Return Type
- string - The cache control directives string to be used in the
cache-control
header
Fields
- noCache boolean(default false) - Sets the
no-cache
directive
- noStore boolean(default false) - Sets the
no-store
directive
- noTransform boolean(default false) - Sets the
no-transform
directive
- onlyIfCached boolean(default false) - Sets the
only-if-cached
directive
- maxAge decimal(default -1) - Sets the
max-age
directive
- maxStale decimal(default -1) - Sets the
max-stale
directive
- minFresh decimal(default -1) - Sets the
min-fresh
directive
http: RequestContext
Represents an HTTP Context that allows user to pass data between interceptors.
set
Sets an attribute to the request context object.
Parameters
- key string - Represents the attribute key
- value Cloneable|isolated object {} - Represents the attribute value
get
Gets an attribute value from the request context object.
Parameters
- key string - Represents the attribute key
Return Type
- Cloneable|isolated object {} - Attribute value
remove
function remove(string key)
Removes an attribute from the request context object. It panics if there is no such member.
Parameters
- key string - Represents the attribute key
next
function next() returns NextService|error?
Calls the next service in the interceptor pipeline.
Return Type
- NextService|error? - The next service object in the pipeline. An error is returned, if the call fails
http: Response
Represents an HTTP response.
getEntity
function getEntity() returns Entity|ClientError
Gets the Entity
associated with the response.
Return Type
- Entity|ClientError - The
Entity
of the response. Anhttp:ClientError
is returned, if entity construction fails
setEntity
function setEntity(Entity e)
Sets the provided Entity
to the response.
Parameters
- e Entity - The
Entity
to be set to the response
hasHeader
function hasHeader(string headerName, HeaderPosition position) returns boolean
Checks whether the requested header key exists in the header map.
Parameters
- headerName string - The header name
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter
Return Type
- boolean -
true
if the specified header key exists
getHeader
function getHeader(string headerName, HeaderPosition position) returns string|HeaderNotFoundError
Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.
Parameters
- headerName string - The header name
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter. If the position is
http:TRAILING
, the entity-body of theResponse
must be accessed initially.
Return Type
- string|HeaderNotFoundError - The first header value for the specified header name or the
HeaderNotFoundError
if the header is not found.
addHeader
function addHeader(string headerName, string headerValue, HeaderPosition position)
Adds the specified header to the response. Existing header values are not replaced. Panic if an illegal header is passed.
Parameters
- headerName string - The header name
- headerValue string - The header value
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter. If the position is
http:TRAILING
, the entity-body of theResponse
must be accessed initially.
getHeaders
function getHeaders(string headerName, HeaderPosition position) returns string[]|HeaderNotFoundError
Gets all the header values to which the specified header key maps to.
Parameters
- headerName string - The header name
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter. If the position is
http:TRAILING
, the entity-body of theResponse
must be accessed initially.
Return Type
- string[]|HeaderNotFoundError - The header values the specified header key maps to or the
HeaderNotFoundError
if the header is not found.
setHeader
function setHeader(string headerName, string headerValue, HeaderPosition position)
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 specified header value. Panic if an illegal header is passed.
Parameters
- headerName string - The header name
- headerValue string - The header value
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter. If the position is
http:TRAILING
, the entity-body of theResponse
must be accessed initially.
removeHeader
function removeHeader(string headerName, HeaderPosition position)
Removes the specified header from the response.
Parameters
- headerName string - The header name
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter. If the position is
http:TRAILING
, the entity-body of theResponse
must be accessed initially.
removeAllHeaders
function removeAllHeaders(HeaderPosition position)
Removes all the headers from the response.
Parameters
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter. If the position is
http:TRAILING
, the entity-body of theResponse
must be accessed initially.
getHeaderNames
function getHeaderNames(HeaderPosition position) returns string[]
Gets all the names of the headers of the response.
Parameters
- position HeaderPosition (default LEADING) - Represents the position of the header as an optional parameter. If the position is
http:TRAILING
, the entity-body of theResponse
must be accessed initially.
Return Type
- string[] - An array of all the header names
setContentType
Sets the content-type
header to the response.
Parameters
- contentType string - Content type value to be set as the
content-type
header
Return Type
- error? - Nil if successful, error in case of invalid content-type
getContentType
function getContentType() returns string
Gets the type of the payload of the response (i.e., the content-type
header value).
Return Type
- string - The
content-type
header value as a string
getJsonPayload
function getJsonPayload() returns json|ClientError
Extract json
payload from the response. For an empty payload, http:NoContentError
is returned.
If the content type is not JSON, an http:ClientError
is returned.
Return Type
- json|ClientError - The
json
payload orhttp:ClientError
in case of errors
getXmlPayload
function getXmlPayload() returns xml|ClientError
Extracts xml
payload from the response. For an empty payload, http:NoContentError
is returned.
If the content type is not XML, an http:ClientError
is returned.
Return Type
- xml|ClientError - The
xml
payload orhttp:ClientError
in case of errors
getTextPayload
function getTextPayload() returns string|ClientError
Extracts text
payload from the response. For an empty payload, http:NoContentError
is returned.
If the content type is not of type text, an http:ClientError
is returned.
Return Type
- string|ClientError - The string representation of the message payload or
http:ClientError
in case of errors
getByteStream
function getByteStream(int arraySize) returns stream<byte[], Error?>|ClientError
Gets the response payload as a stream of byte[], except in the case of multiparts. To retrieve multiparts, use
Response.getBodyParts()
.
Parameters
- arraySize int (default 8192) - A defaultable parameter to state the size of the byte array. Default size is 8KB
Return Type
- stream<byte[], Error?>|ClientError - A byte stream from which the message payload can be read or
http:ClientError
in case of errors
getBinaryPayload
function getBinaryPayload() returns byte[]|ClientError
Gets the response payload as a byte[]
.
Return Type
- byte[]|ClientError - The byte[] representation of the message payload or
http:ClientError
in case of errors
getBodyParts
function getBodyParts() returns Entity[]|ClientError
Extracts body parts from the response. If the content type is not a composite media type, an error is returned.
Return Type
- Entity[]|ClientError - The body parts as an array of entities or else an
http:ClientError
if there were any errors in constructing the body parts from the response
setETag
Sets the etag
header for the given payload. The ETag is generated using a CRC32 hash isolated function.
setLastModified
function setLastModified()
Sets the current time as the last-modified
header.
setJsonPayload
function setJsonPayload(json payload, string? contentType)
Sets a json
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/json
. Any existing content-type can be
overridden by passing the content-type as an optional parameter.
Parameters
- payload json - The
json
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
application/json
is the default value
setXmlPayload
Sets an xml
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/xml
. Any existing content-type can be
overridden by passing the content-type as an optional parameter.
Parameters
- payload xml - The
xml
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
application/xml
is the default value
setTextPayload
Sets a string
as the payload. If the content-type header is not set then this method set
content-type headers with the default content-type, which is text/plain
. Any
existing content-type can be overridden by passing the content-type as an optional parameter.
Parameters
- payload string - The
string
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
text/plain
is the default value
setBinaryPayload
function setBinaryPayload(byte[] payload, string? contentType)
Sets a byte[]
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/octet-stream
. Any existing content-type
can be overridden by passing the content-type as an optional parameter.
Parameters
- payload byte[] - The
byte[]
payload
- contentType string? (default ()) - The content type of the payload. This is an optional parameter.
The
application/octet-stream
is the default value
setBodyParts
Set multiparts as the payload. If the content-type header is not set then this method
set content-type headers with the default content-type, which is multipart/form-data
.
Any existing content-type can be overridden by passing the content-type as an optional parameter.
Parameters
- bodyParts Entity[] - The entities which make up the message body
- contentType string? (default ()) - The content type of the top level message. This is an optional parameter.
The
multipart/form-data
is the default value
setFileAsPayload
Sets the content of the specified file as the entity body of the response. If the content-type header
is not set then this method set content-type headers with the default content-type, which is
application/octet-stream
. Any existing content-type can be overridden by passing the content-type
as an optional parameter.
Parameters
- filePath string - Path to the file to be set as the payload
- contentType string? (default ()) - The content type of the specified file. This is an optional parameter.
The
application/octet-stream
is the default value
setByteStream
Sets a Stream
as the payload. If the content-type header is not set then this method set content-type
headers with the default content-type, which is application/octet-stream
. Any existing content-type can
be overridden by passing the content-type as an optional parameter.
Parameters
- contentType string? (default ()) - Content-type to be used with the payload. This is an optional parameter.
The
application/octet-stream
is the default value
setPayload
function setPayload(string|xml|json|byte[]|Entity[]|stream<byte[], Error?> payload, string? contentType)
Sets the response payload. This method overrides any existing content-type by passing the content-type as an optional parameter. If the content type parameter is not provided then the default value derived from the payload will be used as content-type only when there are no existing content-type header.
Parameters
- contentType string? (default ()) - Content-type to be used with the payload. This is an optional parameter
addCookie
function addCookie(Cookie cookie)
Adds the cookie to response.
Parameters
- cookie Cookie - The cookie, which is added to response
removeCookiesFromRemoteStore
function removeCookiesFromRemoteStore(Cookie... cookiesToRemove)
Deletes the cookies in the client's cookie store.
Parameters
- cookiesToRemove Cookie... - Cookies to be deleted
getCookies
function getCookies() returns Cookie[]
Gets cookies from the response.
Return Type
- Cookie[] - An array of cookie objects, which are included in the response
Fields
- statusCode int(default 200) - The response status code
- reasonPhrase string(default "") - The status code reason phrase
- server string(default "") - The server header
- resolvedRequestedURI string(default "") - The ultimate request URI that was made to receive the response when redirect is on
- cacheControl ResponseCacheControl?(default ()) - 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
http: ResponseCacheControl
Configures cache control directives for an http:Response
.
populateFields
function populateFields(HttpCacheConfig cacheConfig)
Parameters
- cacheConfig HttpCacheConfig -
buildCacheControlDirectives
function buildCacheControlDirectives() returns string
Builds the cache control directives string from the current http:ResponseCacheControl
configurations.
Return Type
- string - The cache control directives string to be used in the
cache-control
header
Fields
- mustRevalidate boolean(default false) - Sets the
must-revalidate
directive
- noCache boolean(default false) - Sets the
no-cache
directive
- noStore boolean(default false) - Sets the
no-store
directive
- noTransform boolean(default false) - Sets the
no-transform
directive
- isPrivate boolean(default false) - Sets the
private
andpublic
directives
- proxyRevalidate boolean(default false) - Sets the
proxy-revalidate
directive
- maxAge decimal(default -1) - Sets the
max-age
directive
- sMaxAge decimal(default -1) - Sets the
s-maxage
directive
- noCacheFields string[](default []) - 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[](default []) - Optional fields for the
private
directive. A cache can omit the fields specified and store the rest of the response.
http: StatusAccepted
Represents the status code of STATUS_ACCEPTED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_ACCEPTED(default STATUS_ACCEPTED) - The response status code
http: StatusBadGateway
Represents the status code of STATUS_BAD_GATEWAY
.
Fields
- Fields Included from *Status
- code int
- code STATUS_BAD_GATEWAY(default STATUS_BAD_GATEWAY) - The response status code
http: StatusBadRequest
Represents the status code of STATUS_BAD_REQUEST
.
Fields
- Fields Included from *Status
- code int
- code STATUS_BAD_REQUEST(default STATUS_BAD_REQUEST) - The response status code
http: StatusConflict
Represents the status code of STATUS_CONFLICT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_CONFLICT(default STATUS_CONFLICT) - The response status code
http: StatusContinue
Represents the status code of STATUS_CONTINUE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_CONTINUE(default STATUS_CONTINUE) - The response status code
http: StatusCreated
Represents the status code of STATUS_CREATED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_CREATED(default STATUS_CREATED) - The response status code
http: StatusExpectationFailed
Represents the status code of STATUS_EXPECTATION_FAILED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_EXPECTATION_FAILED(default STATUS_EXPECTATION_FAILED) - The response status code
http: StatusForbidden
Represents the status code of STATUS_FORBIDDEN
.
Fields
- Fields Included from *Status
- code int
- code STATUS_FORBIDDEN(default STATUS_FORBIDDEN) - The response status code
http: StatusFound
Represents the status code of STATUS_FOUND
.
Fields
- Fields Included from *Status
- code int
- code STATUS_FOUND(default STATUS_FOUND) - The response status code
http: StatusGatewayTimeout
Represents the status code of STATUS_GATEWAY_TIMEOUT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_GATEWAY_TIMEOUT(default STATUS_GATEWAY_TIMEOUT) - The response status code
http: StatusGone
Represents the status code of STATUS_GONE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_GONE(default STATUS_GONE) - The response status code
http: StatusHttpVersionNotSupported
Represents the status code of STATUS_HTTP_VERSION_NOT_SUPPORTED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_HTTP_VERSION_NOT_SUPPORTED(default STATUS_HTTP_VERSION_NOT_SUPPORTED) - The response status code
http: StatusInternalServerError
Represents the status code of STATUS_INTERNAL_SERVER_ERROR
.
Fields
- Fields Included from *Status
- code int
- code STATUS_INTERNAL_SERVER_ERROR(default STATUS_INTERNAL_SERVER_ERROR) - The response status code
http: StatusLengthRequired
Represents the status code of STATUS_LENGTH_REQUIRED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_LENGTH_REQUIRED(default STATUS_LENGTH_REQUIRED) - The response status code
http: StatusMethodNotAllowed
Represents the status code of STATUS_METHOD_NOT_ALLOWED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_METHOD_NOT_ALLOWED(default STATUS_METHOD_NOT_ALLOWED) - The response status code
http: StatusMovedPermanently
Represents the status code of STATUS_MOVED_PERMANENTLY
.
Fields
- Fields Included from *Status
- code int
- code STATUS_MOVED_PERMANENTLY(default STATUS_MOVED_PERMANENTLY) - The response status code
http: StatusMultipleChoices
Represents the status code of STATUS_MULTIPLE_CHOICES
.
Fields
- Fields Included from *Status
- code int
- code STATUS_MULTIPLE_CHOICES(default STATUS_MULTIPLE_CHOICES) - The response status code
http: StatusNoContent
Represents the status code of STATUS_NO_CONTENT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_NO_CONTENT(default STATUS_NO_CONTENT) - The response status code
http: StatusNonAuthoritativeInformation
Represents the status code of STATUS_NON_AUTHORITATIVE_INFORMATION
.
Fields
- Fields Included from *Status
- code int
- code STATUS_NON_AUTHORITATIVE_INFORMATION(default STATUS_NON_AUTHORITATIVE_INFORMATION) - The response status code
http: StatusNotAcceptable
Represents the status code of STATUS_NOT_ACCEPTABLE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_NOT_ACCEPTABLE(default STATUS_NOT_ACCEPTABLE) - The response status code
http: StatusNotFound
Represents the status code of STATUS_NOT_FOUND
.
Fields
- Fields Included from *Status
- code int
- code STATUS_NOT_FOUND(default STATUS_NOT_FOUND) - The response status code
http: StatusNotImplemented
Represents the status code of STATUS_NOT_IMPLEMENTED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_NOT_IMPLEMENTED(default STATUS_NOT_IMPLEMENTED) - The response status code
http: StatusNotModified
Represents the status code of STATUS_NOT_MODIFIED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_NOT_MODIFIED(default STATUS_NOT_MODIFIED) - The response status code
http: StatusOK
Represents the status code of STATUS_OK
.
Fields
- Fields Included from *Status
- code int
- code STATUS_OK(default STATUS_OK) - The response status code
http: StatusPartialContent
Represents the status code of STATUS_PARTIAL_CONTENT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_PARTIAL_CONTENT(default STATUS_PARTIAL_CONTENT) - The response status code
http: StatusPayloadTooLarge
Represents the status code of STATUS_PAYLOAD_TOO_LARGE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_PAYLOAD_TOO_LARGE(default STATUS_PAYLOAD_TOO_LARGE) - The response status code
http: StatusPaymentRequired
Represents the status code of STATUS_PAYMENT_REQUIRED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_PAYMENT_REQUIRED(default STATUS_PAYMENT_REQUIRED) - The response status code
http: StatusPermanentRedirect
Represents the status code of STATUS_PERMANENT_REDIRECT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_PERMANENT_REDIRECT(default STATUS_PERMANENT_REDIRECT) - The response status code
http: StatusPreconditionFailed
Represents the status code of STATUS_PRECONDITION_FAILED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_PRECONDITION_FAILED(default STATUS_PRECONDITION_FAILED) - The response status code
http: StatusProxyAuthenticationRequired
Represents the status code of STATUS_PROXY_AUTHENTICATION_REQUIRED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_PROXY_AUTHENTICATION_REQUIRED(default STATUS_PROXY_AUTHENTICATION_REQUIRED) - The response status code
http: StatusRangeNotSatisfiable
Represents the status code of STATUS_RANGE_NOT_SATISFIABLE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_RANGE_NOT_SATISFIABLE(default STATUS_RANGE_NOT_SATISFIABLE) - The response status code
http: StatusRequestHeaderFieldsTooLarge
Represents the status code of STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE(default STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE) - The response status code
http: StatusRequestTimeout
Represents the status code of STATUS_REQUEST_TIMEOUT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_REQUEST_TIMEOUT(default STATUS_REQUEST_TIMEOUT) - The response status code
http: StatusResetContent
Represents the status code of STATUS_RESET_CONTENT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_RESET_CONTENT(default STATUS_RESET_CONTENT) - The response status code
http: StatusSeeOther
Represents the status code of STATUS_SEE_OTHER
.
Fields
- Fields Included from *Status
- code int
- code STATUS_SEE_OTHER(default STATUS_SEE_OTHER) - The response status code
http: StatusServiceUnavailable
Represents the status code of STATUS_SERVICE_UNAVAILABLE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_SERVICE_UNAVAILABLE(default STATUS_SERVICE_UNAVAILABLE) - The response status code
http: StatusSwitchingProtocols
Represents the status code of STATUS_SWITCHING_PROTOCOLS
.
Fields
- Fields Included from *Status
- code int
- code STATUS_SWITCHING_PROTOCOLS(default STATUS_SWITCHING_PROTOCOLS) - The response status code
http: StatusTemporaryRedirect
Represents the status code of STATUS_TEMPORARY_REDIRECT
.
Fields
- Fields Included from *Status
- code int
- code STATUS_TEMPORARY_REDIRECT(default STATUS_TEMPORARY_REDIRECT) - The response status code
http: StatusTooManyRequests
Represents the status code of STATUS_TOO_MANY_REQUESTS
.
Fields
- Fields Included from *Status
- code int
- code STATUS_TOO_MANY_REQUESTS(default STATUS_TOO_MANY_REQUESTS) - The response status code
http: StatusUnauthorized
Represents the status code of STATUS_UNAUTHORIZED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_UNAUTHORIZED(default STATUS_UNAUTHORIZED) - The response status code
http: StatusUnsupportedMediaType
Represents the status code of STATUS_UNSUPPORTED_MEDIA_TYPE
.
Fields
- Fields Included from *Status
- code int
- code STATUS_UNSUPPORTED_MEDIA_TYPE(default STATUS_UNSUPPORTED_MEDIA_TYPE) - The response status code
http: StatusUpgradeRequired
Represents the status code of STATUS_UPGRADE_REQUIRED
.
Fields
- Fields Included from *Status
- code int
- code STATUS_UPGRADE_REQUIRED(default STATUS_UPGRADE_REQUIRED) - The response status code
http: StatusUriTooLong
Represents the status code of STATUS_URI_TOO_LONG
.
Fields
- Fields Included from *Status
- code int
- code STATUS_URI_TOO_LONG(default STATUS_URI_TOO_LONG) - The response status code
http: StatusUseProxy
Represents the status code of STATUS_USE_PROXY
.
Fields
- Fields Included from *Status
- code int
- code STATUS_USE_PROXY(default STATUS_USE_PROXY) - The response status code
Clients
http: Caller
The caller actions for responding to client requests.
respond
function respond(ResponseMessage|StatusCodeResponse|error message) returns ListenerError?
Sends the outbound response to the caller.
Parameters
- message ResponseMessage|StatusCodeResponse|error (default ()) - The outbound response or status code response or error or any allowed payload
Return Type
- ListenerError? - An
http:ListenerError
if failed to respond or else()
promise
function promise(PushPromise promise) returns ListenerError?
Pushes a promise to the caller.
Parameters
- promise PushPromise - Push promise message
Return Type
- ListenerError? - An
http:ListenerError
in case of failures
pushPromisedResponse
function pushPromisedResponse(PushPromise promise, Response response) returns ListenerError?
Sends a promised push response to the caller.
Return Type
- ListenerError? - An
http:ListenerError
in case of failures while responding with the promised response
'continue
function 'continue() returns ListenerError?
Sends a 100-continue
response to the caller.
Return Type
- ListenerError? - An
http:ListenerError
if failed to send the100-continue
response or else()
redirect
function redirect(Response response, RedirectCode code, string[] locations) returns ListenerError?
Sends a redirect response to the user with the specified redirection status code.
Parameters
- response Response - Response to be sent to the caller
- code RedirectCode - The redirect status code to be sent
- locations string[] - An array of URLs to which the caller can redirect to
Return Type
- ListenerError? - An
http:ListenerError
if failed to send the redirect response or else()
getRemoteHostName
function getRemoteHostName() returns string?
Gets the hostname from the remote address. This method may trigger a DNS reverse lookup if the address was created with a literal IP address.
string? remoteHost = caller.getRemoteHostName();
Return Type
- string? - The hostname of the address or else
()
if it is unresolved
http: Client
The HTTP client provides the capability for initiating contact with a remote HTTP service. The API it provides includes the functions for the standard HTTP methods forwarding a received request and sending requests using custom HTTP verbs.
Constructor
Gets invoked to initialize the client
. During initialization, the configurations provided through the config
record is used to determine which type of additional behaviours are added to the endpoint (e.g., caching,
security, circuit breaking).
init (string url, *ClientConfiguration config)
- url string - URL of the target service
- config *ClientConfiguration - The configurations to be used when initializing the
client
post
function post(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.post()
function can be used to send HTTP POST requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
put
function put(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.put()
function can be used to send HTTP PUT requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
patch
function patch(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.patch()
function can be used to send HTTP PATCH requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
delete
function delete(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.delete()
function can be used to send HTTP DELETE requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage (default ()) - An optional HTTP outbound request message or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
head
The Client.head()
function can be used to send HTTP HEAD requests to HTTP endpoints.
Parameters
- path string - Resource path
Return Type
- Response|ClientError - The response or an
http:ClientError
if failed to establish the communication with the upstream server
get
function get(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The Client.get()
function can be used to send HTTP GET requests to HTTP endpoints.
Parameters
- path string - Request path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
options
function options(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The Client.options()
function can be used to send HTTP OPTIONS requests to HTTP endpoints.
Parameters
- path string - Request path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
execute
function execute(string httpVerb, string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
Invokes an HTTP call with the specified HTTP verb.
Parameters
- httpVerb string - HTTP verb value
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
forward
function forward(string path, Request request, TargetType targetType) returns targetType|ClientError
The Client.forward()
function can be used to invoke an HTTP call with inbound request's HTTP verb
Parameters
- path string - Request path
- request Request - An HTTP inbound request message
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
submit
function submit(string httpVerb, string path, RequestMessage message) returns HttpFuture|ClientError
Submits an HTTP request to a service with the specified HTTP verb.
The Client->submit()
function does not give out a http:Response
as the result.
Rather it returns an http:HttpFuture
which can be used to do further interactions with the endpoint.
Parameters
- httpVerb string - The HTTP verb value
- path string - The resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
Return Type
- HttpFuture|ClientError - An
http:HttpFuture
that represents an asynchronous service invocation or else anhttp:ClientError
if the submission fails
getResponse
function getResponse(HttpFuture httpFuture) returns Response|ClientError
This just pass the request to actual network call.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- Response|ClientError - An
http:Response
message or else anhttp: ClientError
if the invocation fails
hasPromise
function hasPromise(HttpFuture httpFuture) returns boolean
This just pass the request to actual network call.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
relates to a previous asynchronous invocation
Return Type
- boolean - A
boolean
, which represents whether anhttp:PushPromise
exists
getNextPromise
function getNextPromise(HttpFuture httpFuture) returns PushPromise|ClientError
This just pass the request to actual network call.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- PushPromise|ClientError - An
http:PushPromise
message or else anhttp:ClientError
if the invocation fails
getPromisedResponse
function getPromisedResponse(PushPromise promise) returns Response|ClientError
Passes the request to an actual network call.
Parameters
- promise PushPromise - The related
http:PushPromise
Return Type
- Response|ClientError - A promised
http:Response
message or else anhttp:ClientError
if the invocation fails
rejectPromise
function rejectPromise(PushPromise promise)
This just pass the request to actual network call.
Parameters
- promise PushPromise - The Push Promise to be rejected
post **
function post **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP POST requests to HTTP endpoints.
Method included from *ClientObject
put **
function put **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP PUT requests to HTTP endpoints.
Method included from *ClientObject
patch **
function patch **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP PATCH requests to HTTP endpoints.
Method included from *ClientObject
delete **
function delete **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP DELETE requests to HTTP endpoints.
Method included from *ClientObject
head **
function head **(map<string|string[]>|() headers, QueryParams params) returns Response|ClientError
The client resource function to send HTTP HEAD requests to HTTP endpoints.
Method included from *ClientObject
get **
function get **(map<string|string[]>|() headers, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP GET requests to HTTP endpoints.
Method included from *ClientObject
options **
function options **(map<string|string[]>|() headers, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP OPTIONS requests to HTTP endpoints.
Method included from *ClientObject
getCookieStore
function getCookieStore() returns CookieStore?
Retrieves the cookie store of the client.
Return Type
- CookieStore? - The cookie store related to the client
circuitBreakerForceClose
function circuitBreakerForceClose()
The circuit breaker client related method to force the circuit into a closed state in which it will allow requests regardless of the error percentage until the failure threshold exceeds.
circuitBreakerForceOpen
function circuitBreakerForceOpen()
The circuit breaker client related method to force the circuit into a open state in which it will suspend all
requests until resetTime
interval exceeds.
getCircuitBreakerCurrentState
function getCircuitBreakerCurrentState() returns CircuitState
The circuit breaker client related method to provides the http:CircuitState
of the circuit breaker.
Return Type
- CircuitState - The current
http:CircuitState
of the circuit breaker
http: ClientOAuth2Handler
Defines the OAuth2 handler for client authentication.
Constructor
Initializes the http:ClientOAuth2Handler
object.
init (OAuth2GrantConfig config)
- config OAuth2GrantConfig - The
http:OAuth2GrantConfig
instance
enrich
function enrich(Request req) returns Request|ClientAuthError
Enrich the request with the relevant authentication requirements.
Parameters
- req Request - The
http:Request
instance
Return Type
- Request|ClientAuthError - The updated
http:Request
instance or else anhttp:ClientAuthError
in case of an error
enrichHeaders
Enrich the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
getSecurityHeaders
function getSecurityHeaders() returns map<string|string[]>|ClientAuthError
Returns the headers map with the relevant authentication requirements.
Return Type
- map<string|string[]>|ClientAuthError - The updated headers map or else an
http:ClientAuthError
in case of an error
http: FailoverClient
An HTTP client endpoint which provides failover support over multiple HTTP clients.
Constructor
Failover caller actions which provides failover capabilities to an HTTP client endpoint.
init (*FailoverClientConfiguration failoverClientConfig)
- failoverClientConfig *FailoverClientConfiguration - The configurations of the client endpoint associated with this
Failover
instance
post
function post(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The POST remote function implementation of the Failover Connector.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
put
function put(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The PUT remote function implementation of the Failover Connector.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
patch
function patch(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The PATCH remote function implementation of the Failover Connector.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
delete
function delete(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The DELETE remote function implementation of the Failover Connector.
Parameters
- path string - Resource path
- message RequestMessage (default ()) - An optional HTTP outbound request message or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
head
The HEAD remote function implementation of the Failover Connector.
Parameters
- path string - Resource path
Return Type
- Response|ClientError - The response or an
http:ClientError
if failed to establish the communication with the upstream server
get
function get(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The GET remote function implementation of the Failover Connector.
Parameters
- path string - Resource path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
options
function options(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The OPTIONS remote function implementation of the Failover Connector.
Parameters
- path string - Resource path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
execute
function execute(string httpVerb, string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
Invokes an HTTP call with the specified HTTP method.
Parameters
- httpVerb string - HTTP verb value
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
forward
function forward(string path, Request request, TargetType targetType) returns targetType|ClientError
Invokes an HTTP call using the incoming request's HTTP method.
Parameters
- path string - Resource path
- request Request - An HTTP request
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
submit
function submit(string httpVerb, string path, RequestMessage message) returns HttpFuture|ClientError
Submits an HTTP request to a service with the specified HTTP verb. The FailoverClient.submit()
function does not
return an http:Response
as the result. Rather it returns an http:HttpFuture
which can be used for subsequent interactions
with the HTTP endpoint.
Parameters
- httpVerb string - The HTTP verb value
- path string - The resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
Return Type
- HttpFuture|ClientError - An
http:HttpFuture
that represents an asynchronous service invocation or else anhttp:ClientError
if the submission fails
getResponse
function getResponse(HttpFuture httpFuture) returns Response|ClientError
Retrieves the http:Response
for a previously-submitted request.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- Response|ClientError - An
http:Response
message or else anhttp:ClientError
if the invocation fails
hasPromise
function hasPromise(HttpFuture httpFuture) returns boolean
Checks whether an http:PushPromise
exists for a previously-submitted request.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- boolean - A
boolean
, which represents whether anhttp:PushPromise
exists
getNextPromise
function getNextPromise(HttpFuture httpFuture) returns PushPromise|ClientError
Retrieves the next available http:PushPromise
for a previously-submitted request.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- PushPromise|ClientError - An
http:PushPromise
message or else anhttp:ClientError
if the invocation fails
getPromisedResponse
function getPromisedResponse(PushPromise promise) returns Response|ClientError
Retrieves the promised server push http:Response
message.
Parameters
- promise PushPromise - The related
http:PushPromise
Return Type
- Response|ClientError - A promised
http:Response
message or else anhttp:ClientError
if the invocation fails
rejectPromise
function rejectPromise(PushPromise promise)
Rejects an http:PushPromise
. When an http:PushPromise
is rejected, there is no chance of fetching a promised
response using the rejected promise.
Parameters
- promise PushPromise - The Push Promise to be rejected
post **
function post **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP POST requests to HTTP endpoints.
Method included from *ClientObject
put **
function put **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP PUT requests to HTTP endpoints.
Method included from *ClientObject
patch **
function patch **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP PATCH requests to HTTP endpoints.
Method included from *ClientObject
delete **
function delete **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP DELETE requests to HTTP endpoints.
Method included from *ClientObject
head **
function head **(map<string|string[]>|() headers, QueryParams params) returns Response|ClientError
The client resource function to send HTTP HEAD requests to HTTP endpoints.
Method included from *ClientObject
get **
function get **(map<string|string[]>|() headers, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP GET requests to HTTP endpoints.
Method included from *ClientObject
options **
function options **(map<string|string[]>|() headers, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP OPTIONS requests to HTTP endpoints.
Method included from *ClientObject
getSucceededEndpointIndex
function getSucceededEndpointIndex() returns int
Gets the index of the TargetService[]
array which given a successful response.
Return Type
- int - The successful target endpoint index
http: ListenerLdapUserStoreBasicAuthHandler
Defines the LDAP store Basic Auth handler for listener authentication.
Constructor
Initializes the http:ListenerLdapUserStoreBasicAuthProvider
object.
init (LdapUserStoreConfig config)
- config LdapUserStoreConfig - The
http:LdapUserStoreConfig
instance
authenticate
function authenticate(Request|Headers|string data) returns UserDetails|Unauthorized
Authenticates with the relevant authentication requirements.
Parameters
Return Type
- UserDetails|Unauthorized - The
auth:UserDetails
instance or elseUnauthorized
type in case of an error
authorize
function authorize(UserDetails userDetails, string|string[] expectedScopes) returns Forbidden?
Authorizes with the relevant authorization requirements.
Parameters
- userDetails UserDetails - The
auth:UserDetails
instance which is received from authentication results
Return Type
- Forbidden? -
()
, if it is successful or elseForbidden
type in case of an error
http: ListenerOAuth2Handler
Defines the OAuth2 handler for listener authentication.
Constructor
Initializes the http:ListenerOAuth2Handler
object.
init (OAuth2IntrospectionConfig config)
- config OAuth2IntrospectionConfig - The
http:OAuth2IntrospectionConfig
instance
authorize
function authorize(Request|Headers|string data, string|string[]? expectedScopes, map<string>? optionalParams) returns IntrospectionResponse|Unauthorized|Forbidden
Authorizes with the relevant authentication & authorization requirements.
Parameters
Return Type
- IntrospectionResponse|Unauthorized|Forbidden - The
oauth2:IntrospectionResponse
instance or elseUnauthorized
orForbidden
type in case of an error
http: LoadBalanceClient
LoadBalanceClient endpoint provides load balancing functionality over multiple HTTP clients.
Constructor
Load Balancer adds an additional layer to the HTTP client to make network interactions more resilient.
init (*LoadBalanceClientConfiguration loadBalanceClientConfig)
- loadBalanceClientConfig *LoadBalanceClientConfiguration - The configurations for the load balance client endpoint
post
function post(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The POST remote function implementation of the LoadBalancer Connector.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
put
function put(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The PUT remote function implementation of the Load Balance Connector.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
patch
function patch(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The PATCH remote function implementation of the LoadBalancer Connector.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
delete
function delete(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The DELETE remote function implementation of the LoadBalancer Connector.
Parameters
- path string - Resource path
- message RequestMessage (default ()) - An optional HTTP outbound request message or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
head
The HEAD remote function implementation of the LoadBalancer Connector.
Parameters
- path string - Resource path
Return Type
- Response|ClientError - The response or an
http:ClientError
if failed to establish the communication with the upstream server
get
function get(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The GET remote function implementation of the LoadBalancer Connector.
Parameters
- path string - Request path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
options
function options(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The OPTIONS remote function implementation of the LoadBalancer Connector.
Parameters
- path string - Request path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
execute
function execute(string httpVerb, string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The EXECUTE remote function implementation of the LoadBalancer Connector.
Parameters
- httpVerb string - HTTP verb value
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
forward
function forward(string path, Request request, TargetType targetType) returns targetType|ClientError
The FORWARD remote function implementation of the LoadBalancer Connector.
Parameters
- path string - Resource path
- request Request - An HTTP request
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
submit
function submit(string httpVerb, string path, RequestMessage message) returns HttpFuture|ClientError
The submit implementation of the LoadBalancer Connector.
Parameters
- httpVerb string - The HTTP verb value
- path string - The resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
Return Type
- HttpFuture|ClientError - An
http:HttpFuture
that represents an asynchronous service invocation or else anhttp:ClientError
if the submission fails
getResponse
function getResponse(HttpFuture httpFuture) returns Response|ClientError
The getResponse implementation of the LoadBalancer Connector.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- Response|ClientError - An
http:Response
message or else anhttp:ClientError
if the invocation fails
hasPromise
function hasPromise(HttpFuture httpFuture) returns boolean
The hasPromise implementation of the LoadBalancer Connector.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- boolean - A
boolean
, which represents whether anhttp:PushPromise
exists
getNextPromise
function getNextPromise(HttpFuture httpFuture) returns PushPromise|ClientError
The getNextPromise implementation of the LoadBalancer Connector.
Parameters
- httpFuture HttpFuture - The
http:HttpFuture
related to a previous asynchronous invocation
Return Type
- PushPromise|ClientError - An
http:PushPromise
message or else anhttp:ClientError
if the invocation fails
getPromisedResponse
function getPromisedResponse(PushPromise promise) returns Response|ClientError
The getPromisedResponse implementation of the LoadBalancer Connector.
Parameters
- promise PushPromise - The related
http:PushPromise
Return Type
- Response|ClientError - A promised
http:Response
message or else anhttp:ClientError
if the invocation fails
rejectPromise
function rejectPromise(PushPromise promise)
The rejectPromise implementation of the LoadBalancer Connector.
Parameters
- promise PushPromise - The Push Promise to be rejected
post **
function post **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP POST requests to HTTP endpoints.
Method included from *ClientObject
put **
function put **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP PUT requests to HTTP endpoints.
Method included from *ClientObject
patch **
function patch **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP PATCH requests to HTTP endpoints.
Method included from *ClientObject
delete **
function delete **(RequestMessage message, map<string|string[]>|() headers, string|() mediaType, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP DELETE requests to HTTP endpoints.
Method included from *ClientObject
head **
function head **(map<string|string[]>|() headers, QueryParams params) returns Response|ClientError
The client resource function to send HTTP HEAD requests to HTTP endpoints.
Method included from *ClientObject
get **
function get **(map<string|string[]>|() headers, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP GET requests to HTTP endpoints.
Method included from *ClientObject
options **
function options **(map<string|string[]>|() headers, TargetType targetType, QueryParams params) returns targetType|ClientError
The client resource function to send HTTP OPTIONS requests to HTTP endpoints.
Method included from *ClientObject
Constants
http: AGE
HTTP header key age
. Gives the current age of a cached HTTP response.
http: AUTH_HEADER
Represents the Authorization header name.
http: AUTH_SCHEME_BASIC
The prefix used to denote the Basic authentication scheme.
http: AUTH_SCHEME_BEARER
The prefix used to denote the Bearer authentication scheme.
http: AUTHORIZATION
HTTP header key authorization
http: CACHE_CONTROL
HTTP header key cache-control
. Specifies the cache control directives required for the function of HTTP caches.
http: CACHE_CONTROL_AND_VALIDATORS
This is a more restricted mode of RFC 7234. Setting this as the caching policy restricts caching to instances
where the cache-control
header and either the etag
or last-modified
header are present.
http: CB_CLOSED_STATE
Represents the closed state of the circuit. When the Circuit Breaker is in CLOSED
state, all requests will be
allowed to go through to the upstream service. If the failures exceed the configured threhold values, the circuit
will trip and move to the OPEN
state.
http: CB_HALF_OPEN_STATE
Represents the half-open state of the circuit. When the Circuit Breaker is in HALF_OPEN
state, a trial request
will be sent to the upstream service. If it fails, the circuit will trip again and move to the OPEN
state. If not,
it will move to the CLOSED
state.
http: CB_OPEN_STATE
Represents the open state of the circuit. When the Circuit Breaker is in OPEN
state, requests will fail
immediately.
http: CHUNKING_ALWAYS
Always set chunking header in the response.
http: CHUNKING_AUTO
If the payload is less than 8KB, content-length header is set in the outbound request/response, otherwise chunking header is set in the outbound request/response.}
http: CHUNKING_NEVER
Never set the chunking header even if the payload is larger than 8KB in the outbound request/response.
http: COMPRESSION_ALWAYS
Always set accept-encoding/content-encoding in outbound request/response.
http: COMPRESSION_AUTO
When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the outbound request/response accept-encoding/content-encoding option.
http: COMPRESSION_NEVER
Never set accept-encoding/content-encoding header in outbound request/response.
http: CONNECTION
HTTP header key connection
. Allows the sender to specify options that are desired for that particular connection.
http: CONTENT_LENGTH
HTTP header key content-length
. Specifies the size of the response body in bytes.
http: CONTENT_TYPE
HTTP header key content-type
. Specifies the type of the message payload.
http: DATE
HTTP header key date
. The timestamp at the time the response was generated/received.
http: ETAG
HTTP header key etag
. A finger print for a resource which is used by HTTP caches to identify whether a
resource representation has changed.
http: EXPECT
HTTP header key expect
. Specifies expectations to be fulfilled by the server.
http: EXPIRES
HTTP header key expires
. Specifies the time at which the response becomes stale.
http: FAILED
Mutual SSL handshake has failed.
http: HTTP_DELETE
Constant for the HTTP DELETE method
http: HTTP_FORWARD
Constant for the HTTP FORWARD method
http: HTTP_GET
Constant for the HTTP GET method
http: HTTP_HEAD
Constant for the HTTP HEAD method
http: HTTP_NONE
Constant for the identify not an HTTP Operation
http: HTTP_OPTIONS
Constant for the HTTP OPTIONS method
http: HTTP_PATCH
Constant for the HTTP PATCH method
http: HTTP_POST
Constant for the HTTP POST method
http: HTTP_PUT
Constant for the HTTP PUT method
http: HTTP_SUBMIT
constant for the HTTP SUBMIT method
http: IF_MATCH
HTTP header key if-match
http: IF_MODIFIED_SINCE
HTTP header key if-modified-since
. Used when validating (with the origin server) whether a cached response
is still valid. If the representation of the resource has modified since the timestamp in this field, a
304 response is returned.
http: IF_NONE_MATCH
HTTP header key if-none-match
. Used when validating (with the origin server) whether a cached response is
still valid. If the ETag provided in this field matches the representation of the requested resource, a
304 response is returned.
http: IF_RANGE
HTTP header key if-range
http: IF_UNMODIFIED_SINCE
HTTP header key if-unmodified-since
http: KEEPALIVE_ALWAYS
Keeps the connection alive irrespective of the connection
header value }
http: KEEPALIVE_AUTO
Decides to keep the connection alive or not based on the connection
header of the client request }
http: KEEPALIVE_NEVER
Closes the connection irrespective of the connection
header value }
http: LAST_MODIFIED
HTTP header key last-modified
. The time at which the resource was last modified.
http: LEADING
Header is placed before the payload of the request/response.
http: LOCATION
HTTP header key location
. Indicates the URL to redirect a request to.
http: MAX_AGE
When used in requests, max-age
implies that clients are not willing to accept responses whose age is greater
than max-age
. When used in responses, the response is to be considered stale after the specified
number of seconds.
http: MAX_STALE
Indicates that the client is willing to accept responses which have exceeded their freshness lifetime by no more than the specified number of seconds.
http: MAX_STALE_ANY_AGE
Setting this as the max-stale
directives indicates that the max-stale
directive does not specify a limit.
http: MIN_FRESH
Indicates that the client is only accepting responses whose freshness lifetime >= current age + min-fresh.
http: MULTIPART_AS_PRIMARY_TYPE
Represents multipart primary type
http: MUST_REVALIDATE
Indicates that once the response has become stale, it should not be reused for subsequent requests without validating with the origin server.
http: NO_CACHE
Forces the cache to validate a cached response with the origin server before serving.
http: NO_STORE
Instructs the cache to not store a response in non-volatile storage.
http: NO_TRANSFORM
Instructs intermediaries not to transform the payload.
http: NONE
Not a mutual ssl connection.
http: ONLY_IF_CACHED
Indicates that the client is only willing to accept a cached response. A cached response is served subject to other constraints posed by the request.
http: PASSED
Mutual SSL handshake is successful.
http: PRAGMA
HTTP header key pragma
. Used in dealing with HTTP 1.0 caches which do not understand the cache-control
header.
http: PRIVATE
Indicates that the response is intended for a single user and should not be stored by shared caches.
http: PROXY_AUTHORIZATION
HTTP header key proxy-authorization
. Contains the credentials to authenticate a user agent to a proxy serve.
http: PROXY_REVALIDATE
Has the same semantics as must-revalidate
, except that this does not apply to private caches.
http: PUBLIC
Indicates that any cache may store the response.
http: REDIRECT_FOUND_302
Represents the HTTP redirect status code 302 - Found
.
http: REDIRECT_MOVED_PERMANENTLY_301
Represents the HTTP redirect status code 301 - Moved Permanently
.
http: REDIRECT_MULTIPLE_CHOICES_300
Represents the HTTP redirect status code 300 - Multiple Choices
.
http: REDIRECT_NOT_MODIFIED_304
Represents the HTTP redirect status code 304 - Not Modified
.
http: REDIRECT_PERMANENT_REDIRECT_308
Represents the HTTP redirect status code 308 - Permanent Redirect
.
http: REDIRECT_SEE_OTHER_303
Represents the HTTP redirect status code 303 - See Other
.
http: REDIRECT_TEMPORARY_REDIRECT_307
Represents the HTTP redirect status code 307 - Temporary Redirect
.
http: REDIRECT_USE_PROXY_305
Represents the HTTP redirect status code 305 - Use Proxy
.
http: REQUEST_METHOD
Constant for the request method reference.
http: RESOURCE_NAME
Constant for the resource name reference.
http: RFC_7234
Caching behaviour is as specified by the RFC 7234 specification.
http: S_MAX_AGE
In shared caches, s-maxage
overrides the max-age
or expires
header field.
http: SERVER
HTTP header key server
. Specifies the details of the origin server.
http: SERVICE_NAME
Constant for the service name reference.
http: STATUS_ACCEPTED
The HTTP response status code: 202 Accepted
http: STATUS_BAD_GATEWAY
The HTTP response status code: 502 Bad Gateway
http: STATUS_BAD_REQUEST
The HTTP response status code: 400 Bad Request
http: STATUS_CONFLICT
The HTTP response status code: 409 Conflict
http: STATUS_CONTINUE
The HTTP response status code: 100 Continue
http: STATUS_CREATED
The HTTP response status code: 201 Created
http: STATUS_EXPECTATION_FAILED
The HTTP response status code: 417 Expectation Failed
http: STATUS_FORBIDDEN
The HTTP response status code: 403 Forbidden
http: STATUS_FOUND
The HTTP response status code: 302 Found
http: STATUS_GATEWAY_TIMEOUT
The HTTP response status code: 504 Gateway Timeout
http: STATUS_GONE
The HTTP response status code: 410 Gone
http: STATUS_HTTP_VERSION_NOT_SUPPORTED
The HTTP response status code: 505 HTTP Version Not Supported
http: STATUS_INTERNAL_SERVER_ERROR
The HTTP response status code: 500 Internal Server Error
http: STATUS_LENGTH_REQUIRED
The HTTP response status code: 411 Length Required
http: STATUS_METHOD_NOT_ALLOWED
The HTTP response status code: 405 Method Not Allowed
http: STATUS_MOVED_PERMANENTLY
The HTTP response status code: 301 Moved Permanently
http: STATUS_MULTIPLE_CHOICES
The HTTP response status code: 300 Multiple Choices
http: STATUS_NO_CONTENT
The HTTP response status code: 204 No Content
http: STATUS_NON_AUTHORITATIVE_INFORMATION
The HTTP response status code: 203 Non Authoritative Information
http: STATUS_NOT_ACCEPTABLE
The HTTP response status code: 406 Not Acceptable
http: STATUS_NOT_FOUND
The HTTP response status code: 404 Not Found
http: STATUS_NOT_IMPLEMENTED
The HTTP response status code: 501 Not Implemented
http: STATUS_NOT_MODIFIED
The HTTP response status code: 304 Not Modified
http: STATUS_OK
The HTTP response status code: 200 OK
http: STATUS_PARTIAL_CONTENT
The HTTP response status code: 206 Partial Content
http: STATUS_PAYLOAD_TOO_LARGE
The HTTP response status code: 413 Payload Too Large
http: STATUS_PAYMENT_REQUIRED
The HTTP response status code: 402 Payment Required
http: STATUS_PERMANENT_REDIRECT
The HTTP response status code: 308 Permanent Redirect
http: STATUS_PRECONDITION_FAILED
The HTTP response status code: 412 Precondition Failed
http: STATUS_PROXY_AUTHENTICATION_REQUIRED
The HTTP response status code: 407 Proxy Authentication Required
http: STATUS_RANGE_NOT_SATISFIABLE
The HTTP response status code: 416 Range Not Satisfiable
http: STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE
The HTTP response status code: 431 Request Header Fields Too Large
http: STATUS_REQUEST_TIMEOUT
The HTTP response status code: 408 Request Timeout
http: STATUS_RESET_CONTENT
The HTTP response status code: 205 Reset Content
http: STATUS_SEE_OTHER
The HTTP response status code: 303 See Other
http: STATUS_SERVICE_UNAVAILABLE
The HTTP response status code: 503 Service Unavailable
http: STATUS_SWITCHING_PROTOCOLS
The HTTP response status code: 101 Switching Protocols
http: STATUS_TEMPORARY_REDIRECT
The HTTP response status code: 307 Temporary Redirect
http: STATUS_TOO_MANY_REQUESTS
The HTTP response status code: 429 Too Many Requests
http: STATUS_UNAUTHORIZED
The HTTP response status code: 401 Unauthorized
http: STATUS_UNSUPPORTED_MEDIA_TYPE
The HTTP response status code: 415 Unsupported Media Type
http: STATUS_UPGRADE_REQUIRED
The HTTP response status code: 426 Upgrade Required
http: STATUS_URI_TOO_LONG
The HTTP response status code: 414 URI Too Long
http: STATUS_USE_PROXY
The HTTP response status code: 305 Use Proxy
http: TRAILING
Header is placed after the payload of the request/response.
http: TRANSFER_ENCODING
HTTP header key transfer-encoding
. Specifies what type of transformation has been applied to entity body.
http: UPGRADE
HTTP header key upgrade
. Allows the client to specify what additional communication protocols it supports and
would like to use, if the server finds it appropriate to switch protocols.
http: WARNING
HTTP header key warning
. Specifies warnings generated when serving stale responses from HTTP caches.
Enums
http: CertValidationType
Represents certification validation type options.
Members
http: HttpVersion
Defines the supported HTTP protocols.
Members
http: Method
Represents HTTP methods.
Members
http: Protocol
Represents protocol options.
Members
http: VerifyClient
Represents client verify options.
Members
Variables
http: CONTINUE
The common status code response constant of Continue
.
http: SWITCHING_PROTOCOLS
The common status code response constant of SwitchingProtocols
.
http: OK
The common status code response constant of Ok
.
http: CREATED
The common status code response constant of Created
.
http: ACCEPTED
The common status code response constant of Accepted
.
http: NON_AUTHORITATIVE_INFORMATION
The common status code response constant of NonAuthoritativeInformation
.
http: NO_CONTENT
The common status code response constant of NoContent
.
http: RESET_CONTENT
The common status code response constant of ResetContent
.
http: PARTIAL_CONTENT
The common status code response constant of PartialContent
.
http: MULTIPLE_CHOICES
The common status code response constant of MultipleChoices
.
http: MOVED_PERMANENTLY
The common status code response constant of MovedPermanently
.
http: FOUND
The common status code response constant of Found
.
http: SEE_OTHER
The common status code response constant of SeeOther
.
http: NOT_MODIFIED
The common status code response constant of NotModified
.
http: USE_PROXY
The common status code response constant of UseProxy
.
http: TEMPORARY_REDIRECT
The common status code response constant of TemporaryRedirect
.
http: PERMANENT_REDIRECT
The common status code response constant of PermanentRedirect
.
http: BAD_REQUEST
The common status code response constant of BadRequest
.
http: UNAUTHORIZED
The common status code response constant of Unauthorized
.
http: PAYMENT_REQUIRED
The common status code response constant of PaymentRequired
.
http: FORBIDDEN
The common status code response constant of Forbidden
.
http: NOT_FOUND
The common status code response constant of NotFound
.
http: METHOD_NOT_ALLOWED
The common status code response constant of MethodNotAllowed
.
http: NOT_ACCEPTABLE
The common status code response constant of NotAcceptable
.
http: PROXY_AUTHENTICATION_REQUIRED
The common status code response constant of ProxyAuthenticationRequired
.
http: REQUEST_TIMEOUT
The common status code response constant of RequestTimeout
.
http: CONFLICT
The common status code response constant of Conflict
.
http: GONE
The common status code response constant of Gone
.
http: LENGTH_REQUIRED
The common status code response constant of LengthRequired
.
http: PRECONDITION_FAILED
The common status code response constant of PreconditionFailed
.
http: PAYLOAD_TOO_LARGE
The common status code response constant of PayloadTooLarge
.
http: URI_TOO_LONG
The common status code response constant of UriTooLong
.
http: UNSUPPORTED_MEDIA_TYPE
The common status code response constant of UnsupportedMediaType
.
http: RANGE_NOT_SATISFIABLE
The common status code response constant of RangeNotSatisfiable
.
http: EXPECTATION_FAILED
The common status code response constant of ExpectationFailed
.
http: UPGRADE_REQUIRED
The common status code response constant of UpgradeRequired
.
http: TOO_MANY_REQUESTS
The common status code response constant of TooManyRequests
.
http: REQUEST_HEADER_FIELDS_TOO_LARGE
The common status code response constant of RequestHeaderFieldsTooLarge
.
http: INTERNAL_SERVER_ERROR
The common status code response constant of InternalServerError
.
http: NOT_IMPLEMENTED
The common status code response constant of NotImplemented
.
http: BAD_GATEWAY
The common status code response constant of BadGateway
.
http: SERVICE_UNAVAILABLE
The common status code response constant of ServiceUnavailable
.
http: GATEWAY_TIMEOUT
The common status code response constant of GatewayTimeout
.
http: HTTP_VERSION_NOT_SUPPORTED
The common status code response constant of HttpVersionNotSupported
.
Listeners
http: Listener
This is used for creating HTTP server endpoints. An HTTP server endpoint is capable of responding to
remote callers. The Listener
is responsible for initializing the endpoint using the provided configurations.
Constructor
Gets invoked during module initialization to initialize the listener.
init (int port, *ListenerConfiguration config)
- port int - Listening port of the HTTP service listener
- config *ListenerConfiguration - Configurations for the HTTP service listener
attach
Attaches a service to the listener.
Parameters
- httpService Service - The service that needs to be attached
Return Type
- error? - An
error
if an error occurred during the service attachment process or else()
'start
function 'start() returns error?
Starts the registered service programmatically.
Return Type
- error? - An
error
if an error occurred during the listener starting process
gracefulStop
function gracefulStop() returns error?
Stops the service listener gracefully. Already-accepted requests will be served before connection closure.
Return Type
- error? - An
error
if an error occurred during the listener stopping process
immediateStop
function immediateStop() returns error?
Stops the service listener immediately. It is not implemented yet.
Return Type
- error? - An
error
if an error occurred during the listener stop process
detach
Detaches an HTTP service from the listener.
Parameters
- httpService Service - The service to be detached
Return Type
- error? - An
error
if one occurred during detaching of a service or else()
getPort
function getPort() returns int
Retrieves the port of the HTTP listener.
Return Type
- int - The HTTP listener port
getConfig
function getConfig() returns readonly & InferredListenerConfiguration
Retrieves the InferredListenerConfiguration
of the HTTP listener.
Return Type
- readonly & InferredListenerConfiguration - The readonly HTTP listener inferred configuration
Annotations
http: Cache
The annotation which is used to define the response cache configuration. This annotation only supports anydata
and
Success(2XX) StatusCodeResponses
return types. Default annotation adds must-revalidate,public,max-age=3600
as
cache-control
header in addition to etag
and last-modified
headers.
http: CallerInfo
The annotation which is used to configure the type of the response.
http: Header
The annotation which is used to define the Header resource signature parameter.
http: Payload
The annotation which is used to define the Payload resource signature parameter and return parameter.
http: ResourceConfig
The annotation which is used to configure an HTTP resource.
http: ServiceConfig
The annotation which is used to configure an HTTP service.
Records
http: Accepted
The status code response record of Accepted
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusAccepted(default StatusAccepted) - The response status code obj
http: AccessLogConfiguration
Represents HTTP access log configuration.
Fields
- console boolean(default false) - Boolean value to enable or disable console access logs
- path string? - Optional file path to store access logs
http: BadGateway
The status code response record of BadGateway
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusBadGateway(default StatusBadGateway) - The response status code obj
http: BadRequest
The status code response record of BadRequest
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusBadRequest(default StatusBadRequest) - The response status code obj
http: BearerTokenConfig
Represents token for Bearer token authentication.
Fields
- token string - Bearer token for authentication
http: Bucket
Represents a discrete sub-part of the time window (Bucket).
Fields
- totalCount int(default 0) - Total number of requests received during the sub-window time frame
- failureCount int(default 0) - Number of failed requests during the sub-window time frame
- rejectedCount int(default 0) - Number of rejected requests during the sub-window time frame
- lastUpdatedTime Utc? - The time that the
Bucket
is last updated.
http: CacheConfig
Provides a set of configurations for controlling the caching behaviour of the endpoint.
Fields
- enabled boolean(default true) - Specifies whether HTTP caching is enabled. Caching is enabled by default.
- isShared boolean(default false) - Specifies whether the HTTP caching layer should behave as a public cache or a private cache
- capacity int(default 16) - The capacity of the cache
- evictionFactor float(default 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 CachingPolicy(default 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 thecache-control
header and either theetag
orlast-modified
header are present.
http: CertKey
Represents combination of certificate, private key and private key password if encrypted.
Fields
- certFile string - A file containing the certificate
- keyFile string - A file containing the private key in PKCS8 format
- keyPassword string? - Password of the private key if it is encrypted
http: CircuitBreakerConfig
Provides a set of configurations for controlling the behaviour of the Circuit Breaker.
Fields
- rollingWindow RollingWindow(default {}) - The
http:RollingWindow
options of theCircuitBreaker
- failureThreshold float(default 0.0) - The threshold for request failures. When this threshold exceeds, the circuit trips. The threshold should be a value between 0 and 1
- resetTime decimal(default 0) - The time period (in seconds) to wait before attempting to make another request to the upstream service
- statusCodes int[](default []) - Array of HTTP response status codes which are considered as failures
http: CircuitBreakerInferredConfig
Derived set of configurations from the CircuitBreakerConfig
.
Fields
- failureThreshold float(default 0.0) - The threshold for request failures. When this threshold exceeds, the circuit trips. The threshold should be a value between 0 and 1
- resetTime decimal(default 0) - The time period (in seconds) to wait before attempting to make another request to the upstream service
- statusCodes int[](default []) - Array of HTTP response status codes which are considered as failures
- noOfBuckets int(default 0) - Number of buckets derived from the
RollingWindow
- rollingWindow RollingWindow(default {}) - The
http:RollingWindow
options provided in thehttp:CircuitBreakerConfig
http: CircuitHealth
Maintains the health of the Circuit Breaker.
Fields
- lastRequestSuccess boolean(default false) - Whether last request is success or not
- totalRequestCount int(default 0) - Total request count received within the
RollingWindow
- lastUsedBucketId int(default 0) - ID of the last bucket used in Circuit Breaker calculations
- startTime Utc(default time:utcNow()) - Circuit Breaker start time
- lastRequestTime Utc? - The time that the last request received
- lastErrorTime Utc? - The time that the last error occurred
- lastForcedOpenTime Utc? - The time that circuit forcefully opened at last
- totalBuckets Bucket?[](default []) - The discrete time buckets into which the time window is divided
http: ClientConfiguration
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
The following fields are inherited from the other configuration records in addition to the Client
-specific
configs.
Fields
- Fields Included from *CommonClientConfiguration
- httpVersion HttpVersion
- http1Settings ClientHttp1Settings
- http2Settings ClientHttp2Settings
- timeout decimal
- forwarded string
- followRedirects FollowRedirects|()
- poolConfig PoolConfiguration|()
- cache CacheConfig
- compression Compression
- auth CredentialsConfig|BearerTokenConfig|JwtIssuerConfig|OAuth2ClientCredentialsGrantConfig|OAuth2PasswordGrantConfig|OAuth2RefreshTokenGrantConfig|OAuth2JwtBearerGrantConfig|()
- circuitBreaker CircuitBreakerConfig|()
- retryConfig RetryConfig|()
- cookieConfig CookieConfig|()
- responseLimits ResponseLimitConfigs
- proxy ProxyConfig|()
- validation boolean
- secureSocket ClientSecureSocket?(default ()) - SSL/TLS-related options
http: ClientHttp1Settings
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
- chunking Chunking(default CHUNKING_AUTO) - The chunking behaviour of the request
- proxy ProxyConfig?(default ()) - Proxy server related options
http: ClientHttp2Settings
Provides settings related to HTTP/2 protocol.
Fields
- http2PriorKnowledge boolean(default false) - Configuration to enable HTTP/2 prior knowledge
http: ClientSecureSocket
Provides configurations for facilitating secure communication with a remote HTTP endpoint.
Fields
- enable boolean(default true) - Enable SSL validation
- cert TrustStore|string? - Configurations associated with
crypto:TrustStore
or single certificate file that the client trusts
- certValidation record {| 'type CertValidationType, cacheSize int, cacheValidityPeriod int |}? - Certificate validation against OCSP_CRL, OCSP_STAPLING 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(default true) - Enable/disable host name verification
- shareSession boolean(default true) - Enable/disable new SSL session creation
- handshakeTimeout decimal? - SSL handshake time out
- sessionTimeout decimal? - SSL session time out
http: CommonClientConfiguration
Common client configurations for the next level clients.
Fields
- httpVersion HttpVersion(default HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded
/x-forwarded
header
- followRedirects FollowRedirects?(default ()) - Configurations associated with Redirection
- poolConfig PoolConfiguration?(default ()) - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding
) header
- auth ClientAuthConfig?(default ()) - Configurations related to client authentication
- circuitBreaker CircuitBreakerConfig?(default ()) - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig RetryConfig?(default ()) - Configurations associated with retrying
- cookieConfig CookieConfig?(default ()) - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- proxy ProxyConfig?(default ()) - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionalty which provided by the constraint package. Enabled by default
http: CommonResponse
The common attributed of response status code record type.
Fields
- mediaType string? - The value of response
Content-type
header
- body anydata? - The response payload
http: CompressionConfig
A record for providing configurations for content compression.
Fields
- enable Compression(default COMPRESSION_AUTO) - The status of compression
- contentTypes string[](default []) - Content types which are allowed for compression
http: Conflict
The status code response record of Conflict
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusConflict(default StatusConflict) - The response status code obj
http: Continue
The status code response record of Continue
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusContinue(default StatusContinue) - The response status code obj
http: CookieConfig
Client configuration for cookies.
Fields
- enabled boolean(default false) - User agents provide users with a mechanism for disabling or enabling cookies
- maxCookiesPerDomain int(default 50) - Maximum number of cookies per domain, which is 50
- maxTotalCookieCount int(default 3000) - Maximum number of total cookies allowed to be stored in cookie store, which is 3000
- blockThirdPartyCookies boolean(default true) - User can block cookies from third party responses and refuse to send cookies for third party requests, if needed
- persistentCookieHandler PersistentCookieHandler? - To manage persistent cookies, users are provided with a mechanism for specifying a persistent cookie store with their own mechanism which references the persistent cookie handler or specifying the CSV persistent cookie handler. If not specified any, only the session cookies are used
http: CookieOptions
The options to be used when initializing the http:Cookie
.
Fields
- path string? - URI path to which the cookie belongs
- domain string? - Host to which the cookie will be sent
- expires string? - Maximum lifetime of the cookie represented as the date and time at which the cookie expires
- maxAge int(default 0) - Maximum lifetime of the cookie represented as the number of seconds until the cookie expires
- httpOnly boolean(default false) - Cookie is sent only to HTTP requests
- secure boolean(default false) - Cookie is sent only to secure channels
- createdTime Utc(default time:utcNow()) - At what time the cookie was created
- lastAccessedTime Utc(default time:utcNow()) - Last-accessed time of the cookie
- hostOnly boolean(default false) - Cookie is sent only to the requested host
http: CorsConfig
Configurations for CORS support.
Fields
- allowHeaders string[](default []) - The array of allowed headers by the service
- allowMethods string[](default []) - The array of allowed methods by the service
- allowOrigins string[](default []) - The array of origins with which the response is shared by the service
- exposeHeaders string[](default []) - The allowlisted headers, which clients are allowed to access
- allowCredentials boolean(default false) - Specifies whether credentials are required to access the service
- maxAge decimal(default -1) - The maximum duration to cache the preflight from client side
http: Created
The status code response record of Created
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusCreated(default StatusCreated) - The response status code obj
http: CredentialsConfig
Represents credentials for Basic Auth authentication.
Fields
- Fields Included from *CredentialsConfig
http: Detail
Represents the details of an HTTP error.
Fields
- statusCode int - The inbound error response status code
- body anydata - The inbound error response body
http: ExpectationFailed
The status code response record of ExpectationFailed
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusExpectationFailed(default StatusExpectationFailed) - The response status code obj
http: FailoverClientConfiguration
Provides a set of HTTP related configurations and failover related configurations. The following fields are inherited from the other configuration records in addition to the failover client-specific configs.
Fields
- Fields Included from *CommonClientConfiguration
- httpVersion HttpVersion
- http1Settings ClientHttp1Settings
- http2Settings ClientHttp2Settings
- timeout decimal
- forwarded string
- followRedirects FollowRedirects|()
- poolConfig PoolConfiguration|()
- cache CacheConfig
- compression Compression
- auth CredentialsConfig|BearerTokenConfig|JwtIssuerConfig|OAuth2ClientCredentialsGrantConfig|OAuth2PasswordGrantConfig|OAuth2RefreshTokenGrantConfig|OAuth2JwtBearerGrantConfig|()
- circuitBreaker CircuitBreakerConfig|()
- retryConfig RetryConfig|()
- cookieConfig CookieConfig|()
- responseLimits ResponseLimitConfigs
- proxy ProxyConfig|()
- validation boolean
- targets TargetService[](default []) - The upstream HTTP endpoints among which the incoming HTTP traffic load should be sent on failover
- failoverCodes int[](default [501, 502, 503, 504]) - Array of HTTP response status codes for which the failover behaviour should be triggered
- interval decimal(default 0) - Failover delay interval in seconds
http: FileUserStoreConfig
Represents file user store configurations for Basic Auth authentication.
http: FileUserStoreConfigWithScopes
Represents the auth annotation for file user store configurations with scopes.
Fields
- fileUserStoreConfig FileUserStoreConfig - File user store configurations for Basic Auth authentication
http: FollowRedirects
Provides configurations for controlling the endpoint's behaviour in response to HTTP redirect related responses. The response status codes of 301, 302, and 303 are redirected using a GET request while 300, 305, 307, and 308 status codes use the original request HTTP method during redirection.
Fields
- enabled boolean(default false) - Enable/disable redirection
- maxCount int(default 5) - Maximum number of redirects to follow
- allowAuthHeaders boolean(default false) - By default Authorization and Proxy-Authorization headers are removed from the redirect requests. Set it to true if Auth headers are needed to be sent during the redirection
http: Forbidden
The status code response record of Forbidden
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusForbidden(default StatusForbidden) - The response status code obj
http: Found
The status code response record of Found
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusFound(default StatusFound) - The response status code obj
http: GatewayTimeout
The status code response record of GatewayTimeout
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusGatewayTimeout(default StatusGatewayTimeout) - The response status code obj
http: Gone
The status code response record of Gone
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusGone(default StatusGone) - The response status code obj
http: HeaderValue
Represents the parsed header value details
Fields
- value string - The header value
http: HttpCacheConfig
Defines the HTTP response cache configuration. By default the no-cache
directive is setted to the cache-control
header. In addition to that etag
and last-modified
headers are also added for cache validation.
Fields
- mustRevalidate boolean(default true) - Sets the
must-revalidate
directive
- noCache boolean(default false) - Sets the
no-cache
directive
- noStore boolean(default false) - Sets the
no-store
directive
- noTransform boolean(default false) - Sets the
no-transform
directive
- isPrivate boolean(default false) - Sets the
private
andpublic
directives
- proxyRevalidate boolean(default false) - Sets the
proxy-revalidate
directive
- maxAge decimal(default 3600) - Sets the
max-age
directive. Default value is 3600 seconds
- sMaxAge decimal(default -1) - Sets the
s-maxage
directive
- noCacheFields string[](default []) - 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[](default []) - Optional fields for the
private
directive. A cache can omit the fields specified and store the rest of the response
- setETag boolean(default true) - Sets the
etag
header for the given payload
- setLastModified boolean(default true) - Sets the current time as the
last-modified
header
http: HttpCallerInfo
Configures the typing details type of the Caller resource signature parameter.
Fields
- respondType typedesc<ResponseMessage|StatusCodeResponse|Error>? - Specifies the type of response
http: HttpHeader
Defines the Header resource signature parameter.
Fields
- name string? - Specifies the name of the required header
http: HttpPayload
Defines the Payload resource signature parameter and return parameter.
Fields
http: HttpResourceConfig
Configuration for an HTTP resource.
Fields
- name string? - The name of the resource
- consumes string[](default []) - The media types which are accepted by resource
- produces string[](default []) - The media types which are produced by resource
- cors CorsConfig(default {}) - 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(default true) - Allow to participate in the distributed transactions if value is true
- auth ListenerAuthConfig[]|Scopes? - Resource auth configurations
- linkedTo LinkedTo[]? - The array of linked resources
http: HttpServiceConfig
Contains the configurations for an HTTP service.
Fields
- host string(default "b7a.default") - Domain name of the service
- compression CompressionConfig(default {}) - The status of compression
- chunking Chunking(default CHUNKING_AUTO) - Configures the chunking behaviour for the service
- cors CorsConfig(default {}) - The cross origin resource sharing configurations for the service
- auth ListenerAuthConfig[]? - Service auth configurations
- mediaTypeSubtypePrefix string? - Service specific media-type subtype prefix
- treatNilableAsOptional boolean(default true) - Treat Nilable parameters as optional
- interceptors Interceptor[]? - An array of interceptor services
- openApiDefinition byte[](default []) - The generated OpenAPI definition for the HTTP service. This is auto-generated at compile-time if OpenAPI doc auto generation is enabled
- validation boolean(default true) - Enables the inbound payload validation functionalty which provided by the constraint package. Enabled by default
http: HttpVersionNotSupported
The status code response record of HttpVersionNotSupported
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusHttpVersionNotSupported(default StatusHttpVersionNotSupported) - The response status code obj
http: InferredListenerConfiguration
Provides a set of cloneable configurations for HTTP listener.
Fields
- host string - The host name/IP of the endpoint
- http1Settings ListenerHttp1Settings - Configurations related to HTTP/1.x protocol
- secureSocket ListenerSecureSocket - The SSL configurations for the service endpoint. This needs to be configured in order to communicate through HTTPS.
- httpVersion HttpVersion - Highest HTTP version supported by the endpoint
- timeout decimal - Period of time in seconds that a connection waits for a read/write operation. Use value 0 to disable timeout
- server string - The server name which should appear as a response header
- requestLimits RequestLimitConfigs - Configurations associated with inbound request size limits
http: InternalServerError
The status code response record of InternalServerError
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusInternalServerError(default StatusInternalServerError) - The response status code obj
http: JwtIssuerConfig
Represents JWT issuer configurations for JWT authentication.
Fields
- Fields Included from *IssuerConfig
http: JwtValidatorConfig
Represents JWT validator configurations for JWT authentication.
Fields
- Fields Included from *ValidatorConfig
- issuer string
- username string
- audience string|string[]
- jwtId string
- keyId string
- customClaims map<json>
- clockSkew decimal
- signatureConfig ValidatorSignatureConfig
- cacheConfig CacheConfig
- anydata...
- scopeKey string(default "scope") - The key used to fetch the scopes
http: JwtValidatorConfigWithScopes
Represents the auth annotation for JWT validator configurations with scopes.
Fields
- jwtValidatorConfig JwtValidatorConfig - JWT validator configurations for JWT authentication
http: LdapUserStoreConfig
Represents LDAP user store configurations for Basic Auth authentication.
Fields
- Fields Included from *LdapUserStoreConfig
- domainName string
- connectionUrl string
- connectionName string
- connectionPassword string
- userSearchBase string
- userEntryObjectClass string
- userNameAttribute string
- userNameSearchFilter string
- userNameListFilter string
- groupSearchBase string[]
- groupEntryObjectClass string
- groupNameAttribute string
- groupNameSearchFilter string
- groupNameListFilter string
- membershipAttribute string
- userRolesCacheEnabled boolean
- connectionPoolingEnabled boolean
- connectionTimeout decimal
- readTimeout decimal
- secureSocket SecureSocket
http: LdapUserStoreConfigWithScopes
Represents the auth annotation for LDAP user store configurations with scopes.
Fields
- ldapUserStoreConfig LdapUserStoreConfig - LDAP user store configurations for Basic Auth authentication
http: LengthRequired
The status code response record of LengthRequired
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusLengthRequired(default StatusLengthRequired) - The response status code obj
http: Link
Represents a server-provided hyperlink
Fields
- rel string? - Names the relationship of the linked target to the current representation
- href string - Target URL
- types string[]? - Expected resource representation media types
- methods Method[]? - Allowed resource methods
http: LinkedTo
Fields
- name string - Name of the linked resource
- relation string(default "self") - Name of the relationship between the linked resource and the current resource.
Defaulted to the IANA link relation
self
- method string? - Method allowed in the linked resource
http: Links
Represents available server-provided links
Fields
http: ListenerConfiguration
Provides a set of configurations for HTTP service endpoints.
Fields
- host string(default "0.0.0.0") - The host name/IP of the endpoint
- http1Settings ListenerHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- secureSocket ListenerSecureSocket?(default ()) - The SSL configurations for the service endpoint. This needs to be configured in order to communicate through HTTPS.
- httpVersion HttpVersion(default HTTP_2_0) - Highest HTTP version supported by the endpoint
- timeout decimal(default DEFAULT_LISTENER_TIMEOUT) - Period of time in seconds that a connection waits for a read/write operation. Use value 0 to disable timeout
- server string?(default ()) - The server name which should appear as a response header
- requestLimits RequestLimitConfigs(default {}) - Configurations associated with inbound request size limits
- interceptors Interceptor[]? - An array of interceptor services
http: ListenerHttp1Settings
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default KEEPALIVE_AUTO) - Can be set to either
KEEPALIVE_AUTO
, which respects theconnection
header, orKEEPALIVE_ALWAYS
, which always keeps the connection alive, orKEEPALIVE_NEVER
, which always closes the connection
- maxPipelinedRequests int(default MAX_PIPELINED_REQUESTS) - Defines the maximum number of requests that can be processed at a given time on a single connection. By default 10 requests can be pipelined on a single connection and user can change this limit appropriately.
http: ListenerSecureSocket
Configures the SSL/TLS options to be used for HTTP service.
Fields
- mutualSsl record {| verifyClient VerifyClient, cert TrustStore|string |}? - Configures associated with mutual SSL operations
- certValidation record {| 'type CertValidationType, cacheSize int, cacheValidityPeriod int |}? - Certificate validation against OCSP_CRL, OCSP_STAPLING related options
- ciphers string[](default ["TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", "TLS_DHE_RSA_WITH_AES_128_CBC_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA", "TLS_DHE_RSA_WITH_AES_128_CBC_SHA", "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"]) - List of ciphers to be used eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- shareSession boolean(default true) - Enable/Disable new SSL session creation
- handshakeTimeout decimal? - SSL handshake time out
- sessionTimeout decimal? - SSL session time out
http: LoadBalanceActionErrorData
Represents the details of the LoadBalanceActionError
.
Fields
- httpActionErr error[]? - Array of errors occurred at each endpoint
http: LoadBalanceClientConfiguration
The configurations related to the load balancing client endpoint. The following fields are inherited from the other configuration records in addition to the load balancing client specific configs.
Fields
- Fields Included from *CommonClientConfiguration
- httpVersion HttpVersion
- http1Settings ClientHttp1Settings
- http2Settings ClientHttp2Settings
- timeout decimal
- forwarded string
- followRedirects FollowRedirects|()
- poolConfig PoolConfiguration|()
- cache CacheConfig
- compression Compression
- auth CredentialsConfig|BearerTokenConfig|JwtIssuerConfig|OAuth2ClientCredentialsGrantConfig|OAuth2PasswordGrantConfig|OAuth2RefreshTokenGrantConfig|OAuth2JwtBearerGrantConfig|()
- circuitBreaker CircuitBreakerConfig|()
- retryConfig RetryConfig|()
- cookieConfig CookieConfig|()
- responseLimits ResponseLimitConfigs
- proxy ProxyConfig|()
- validation boolean
- targets TargetService[](default []) - The upstream HTTP endpoints among which the incoming HTTP traffic load should be distributed
- lbRule LoadBalancerRule?(default ()) - The
LoadBalancing
rule
- failover boolean(default true) - Configuration for the load balancer whether to fail over a failure
http: Local
Presents a read-only view of the local address.
Fields
- host string - The local host name
- port int - The local port
- ip string - The local IP address
http: MethodNotAllowed
The status code response record of MethodNotAllowed
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusMethodNotAllowed(default StatusMethodNotAllowed) - The response status code obj
http: MovedPermanently
The status code response record of MovedPermanently
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusMovedPermanently(default StatusMovedPermanently) - The response status code obj
http: MultipleChoices
The status code response record of MultipleChoices
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusMultipleChoices(default StatusMultipleChoices) - The response status code obj
http: MutualSslHandshake
A record for providing mutual SSL handshake results.
Fields
- status MutualSslStatus(default ()) - Status of the handshake.
- base64EncodedCert string?(default ()) - Base64 encoded certificate.
http: NoContent
The status code response record of NoContent
.
Fields
- statusreadonly StatusNoContent(default StatusNoContent) - The response status code obj
http: NonAuthoritativeInformation
The status code response record of NonAuthoritativeInformation
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusNonAuthoritativeInformation(default StatusNonAuthoritativeInformation) - The response status code obj
http: NotAcceptable
The status code response record of NotAcceptable
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusNotAcceptable(default StatusNotAcceptable) - The response status code obj
http: NotFound
The status code response record of NotFound
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusNotFound(default StatusNotFound) - The response status code obj
http: NotImplemented
The status code response record of NotImplemented
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusNotImplemented(default StatusNotImplemented) - The response status code obj
http: NotModified
The status code response record of NotModified
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusNotModified(default StatusNotModified) - The response status code obj
http: OAuth2ClientCredentialsGrantConfig
Represents OAuth2 client credentials grant configurations for OAuth2 authentication.
Fields
- Fields Included from *ClientCredentialsGrantConfig
- tokenUrl string
- clientId string
- clientSecret string
- scopes string[]
- defaultTokenExpTime decimal
- clockSkew decimal
- optionalParams map<string>
- credentialBearer CredentialBearer
- clientConfig ClientConfiguration
http: OAuth2IntrospectionConfig
Represents OAuth2 introspection server configurations for OAuth2 authentication.
Fields
- Fields Included from *IntrospectionConfig
- url string
- tokenTypeHint string
- optionalParams map<string>
- cacheConfig CacheConfig
- defaultTokenExpTime decimal
- clientConfig ClientConfiguration
- anydata...
- scopeKey string(default "scope") - The key used to fetch the scopes
http: OAuth2IntrospectionConfigWithScopes
Represents the auth annotation for OAuth2 introspection server configurations with scopes.
Fields
- oauth2IntrospectionConfig OAuth2IntrospectionConfig - OAuth2 introspection server configurations for OAuth2 authentication
http: OAuth2JwtBearerGrantConfig
Represents OAuth2 JWT bearer grant configurations for OAuth2 authentication.
Fields
- Fields Included from *JwtBearerGrantConfig
http: OAuth2PasswordGrantConfig
Represents OAuth2 password grant configurations for OAuth2 authentication.
Fields
- Fields Included from *PasswordGrantConfig
- tokenUrl string
- username string
- password string
- clientId string
- clientSecret string
- scopes string[]
- refreshConfig record { refreshUrl string, scopes string[], optionalParams map<string>, credentialBearer CredentialBearer, clientConfig ClientConfiguration }
- defaultTokenExpTime decimal
- clockSkew decimal
- optionalParams map<string>
- credentialBearer CredentialBearer
- clientConfig ClientConfiguration
http: OAuth2RefreshTokenGrantConfig
Represents OAuth2 refresh token grant configurations for OAuth2 authentication.
Fields
- Fields Included from *RefreshTokenGrantConfig
http: Ok
The status code response record of Ok
.
Fields
- Fields Included from *CommonResponse
http: PartialContent
The status code response record of PartialContent
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusPartialContent(default StatusPartialContent) - The response status code obj
http: PayloadTooLarge
The status code response record of PayloadTooLarge
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusPayloadTooLarge(default StatusPayloadTooLarge) - The response status code obj
http: PaymentRequired
The status code response record of PaymentRequired
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusPaymentRequired(default StatusPaymentRequired) - The response status code obj
http: PermanentRedirect
The status code response record of PermanentRedirect
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusPermanentRedirect(default StatusPermanentRedirect) - The response status code obj
http: PoolConfiguration
Configurations for managing HTTP client connection pool.
Fields
- maxActiveConnections int(default maxActiveConnections) - Max active connections per route(host:port). Default value is -1 which indicates unlimited.
- maxIdleConnections int(default maxIdleConnections) - Maximum number of idle connections allowed per pool.
- waitTime decimal(default waitTime) - Maximum amount of time (in seconds), the client should wait for an idle connection before it sends an error when the pool is exhausted
- maxActiveStreamsPerConnection int(default maxActiveStreamsPerConnection) - Maximum active streams per connection. This only applies to HTTP/2. Default value is 100
http: PreconditionFailed
The status code response record of PreconditionFailed
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusPreconditionFailed(default StatusPreconditionFailed) - The response status code obj
http: ProxyAuthenticationRequired
The status code response record of ProxyAuthenticationRequired
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusProxyAuthenticationRequired(default StatusProxyAuthenticationRequired) - The response status code obj
http: ProxyConfig
Proxy server configurations to be used with the HTTP client endpoint.
Fields
- host string(default "") - Host name of the proxy server
- port int(default 0) - Proxy server port
- userName string(default "") - Proxy server username
- password string(default "") - proxy server password
http: QueryParams
Defines the record type of query parameters supported with client resource methods.
Fields
- headers never? - headers which cannot be used as a query field
- targetType never? - targetType which cannot be used as a query field
- message never? - message which cannot be used as a query field
- mediaType never? - mediaType which cannot be used as a query field
- QueryParamType... - Rest field
http: RangeNotSatisfiable
The status code response record of RangeNotSatisfiable
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusRangeNotSatisfiable(default StatusRangeNotSatisfiable) - The response status code obj
http: Remote
Presents a read-only view of the remote address.
Fields
- host string - The remote host name
- port int - The remote port
- ip string - The remote IP address
http: RequestHeaderFieldsTooLarge
The status code response record of RequestHeaderFieldsTooLarge
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusRequestHeaderFieldsTooLarge(default StatusRequestHeaderFieldsTooLarge) - The response status code obj
http: RequestLimitConfigs
Provides inbound request URI, total header and entity body size threshold configurations.
Fields
- maxUriLength int(default 4096) - Maximum allowed length for a URI. Exceeding this limit will result in a
414 - URI Too Long
response
- maxHeaderSize int(default 8192) - Maximum allowed size for headers. Exceeding this limit will result in a
431 - Request Header Fields Too Large
response
- maxEntityBodySize int(default -1) - Maximum allowed size for the entity body. By default it is set to -1 which means there
is no restriction
maxEntityBodySize
, On the Exceeding this limit will result in a413 - Payload Too Large
response
http: RequestTimeout
The status code response record of RequestTimeout
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusRequestTimeout(default StatusRequestTimeout) - The response status code obj
http: ResetContent
The status code response record of ResetContent
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusResetContent(default StatusResetContent) - The response status code obj
http: ResponseLimitConfigs
Provides inbound response status line, total header and entity body size threshold configurations.
Fields
- maxStatusLineLength int(default 4096) - Maximum allowed length for response status line(
HTTP/1.1 200 OK
). Exceeding this limit will result in aClientError
- maxHeaderSize int(default 8192) - Maximum allowed size for headers. Exceeding this limit will result in a
ClientError
- maxEntityBodySize int(default -1) - Maximum allowed size for the entity body. By default it is set to -1 which means there is no
restriction
maxEntityBodySize
, On the Exceeding this limit will result in aClientError
http: RetryConfig
Provides configurations for controlling the retrying behavior in failure scenarios.
Fields
- count int(default 0) - Number of retry attempts before giving up
- interval decimal(default 0) - Retry interval in seconds
- backOffFactor float(default 0.0) - Multiplier, which increases the retry interval exponentially.
- maxWaitInterval decimal(default 0) - Maximum time of the retry interval in seconds
- statusCodes int[](default []) - HTTP response status codes which are considered as failures
http: RollingWindow
Represents a rolling window in the Circuit Breaker.
Fields
- requestVolumeThreshold int(default 10) - Minimum number of requests in a
RollingWindow
that will trip the circuit.
- timeWindow decimal(default 60) - Time period in seconds for which the failure threshold is calculated
- bucketSize decimal(default 10) - The granularity at which the time window slides. This is measured in seconds.
http: Scopes
Represents the annotation used for authorization.
Fields
http: SeeOther
The status code response record of SeeOther
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusSeeOther(default StatusSeeOther) - The response status code obj
http: ServiceUnavailable
The status code response record of ServiceUnavailable
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusServiceUnavailable(default StatusServiceUnavailable) - The response status code obj
http: SwitchingProtocols
The status code response record of SwitchingProtocols
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusSwitchingProtocols(default StatusSwitchingProtocols) - The response status code obj
http: TargetService
Represents a single service and its related configurations.
Fields
- url string(default "") - URL of the target service
- secureSocket ClientSecureSocket?(default ()) - Configurations for secure communication with the remote HTTP endpoint
http: TemporaryRedirect
The status code response record of TemporaryRedirect
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusTemporaryRedirect(default StatusTemporaryRedirect) - The response status code obj
http: TooManyRequests
The status code response record of TooManyRequests
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusTooManyRequests(default StatusTooManyRequests) - The response status code obj
http: TraceLogAdvancedConfiguration
Represents HTTP trace log configuration.
Fields
- console boolean(default false) - Boolean value to enable or disable console trace logs
- path string? - Optional file path to store trace logs
- host string? - Optional socket hostname to publish the trace logs
- port int? - Optional socket port to publish the trace logs
http: Unauthorized
The status code response record of Unauthorized
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusUnauthorized(default StatusUnauthorized) - The response status code obj
http: UnsupportedMediaType
The status code response record of UnsupportedMediaType
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusUnsupportedMediaType(default StatusUnsupportedMediaType) - The response status code obj
http: UpgradeRequired
The status code response record of UpgradeRequired
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusUpgradeRequired(default StatusUpgradeRequired) - The response status code obj
http: UriTooLong
The status code response record of UriTooLong
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusUriTooLong(default StatusUriTooLong) - The response status code obj
http: UseProxy
The status code response record of UseProxy
.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusUseProxy(default StatusUseProxy) - The response status code obj
Errors
http: AllLoadBalanceEndpointsFailedError
Represents a client error that occurred due to all the load balance endpoint failure.
http: AllRetryAttemptsFailed
Represents a client error that occurred due to all the the retry attempts failure.
http: ApplicationResponseError
Represents both 4XX and 5XX application response client error.
http: CircuitBreakerConfigError
Represents a client error that occurred due to circuit breaker configuration error.
http: ClientAuthError
Defines the Auth error types that returned from client.
http: ClientError
Defines the possible client error types.
http: ClientRequestError
Represents an error, which occurred due to bad syntax or incomplete info in the client request(4xx HTTP response).
http: CookieHandlingError
Represents a cookie error that occurred when using the cookies.
http: Error
Defines the common error type for the module.
http: FailoverActionFailedError
Represents a client error that occurred due to failover action failure.
http: FailoverAllEndpointsFailedError
Represents a client error that occurred due to all the failover endpoint failure.
http: GenericClientError
Represents a generic client error.
http: GenericListenerError
Represents a generic listener error.
http: HeaderBindingError
Represents an error, which occurred due to a header binding.
http: HeaderNotFoundError
Represents a header not found error when retrieving headers.
http: Http2ClientError
Represents an HTTP/2 client generic error.
http: IdleTimeoutError
Represents the error that triggered upon a request/response idle timeout.
http: InboundRequestError
Defines the listener error types that returned while receiving inbound request.
http: InboundResponseError
Defines the client error types that returned while receiving inbound response.
http: InitializingInboundRequestError
Represents a listener error that occurred due to inbound request initialization failure.
http: InitializingInboundResponseError
Represents a client error that occurred due to inbound response initialization failure.
http: InitializingOutboundRequestError
Represents a client error that occurred due to outbound request initialization failure.
http: InitializingOutboundResponseError
Represents a listener error that occurred due to outbound response initialization failure.
http: Initiating100ContinueResponseError
Represents an error that occurred due to 100 continue response initialization failure.
http: InterceptorReturnError
Represents an error, which occurred due to a failure in interceptor return.
http: InvalidCookieError
Represents a cookie error that occurred when sending cookies in the response.
http: ListenerAuthError
Defines the auth error types that returned from listener.
http: ListenerAuthnError
Defines the authentication error types that returned from listener.
http: ListenerAuthzError
Defines the authorization error types that returned from listener.
http: ListenerError
Defines the possible listener error types.
http: MaximumWaitTimeExceededError
Represents a client error that occurred exceeding maximum wait time.
http: NoContentError
Represents an error, which occurred due to the absence of the payload.
http: OutboundRequestError
Defines the client error types that returned while sending outbound request.
http: OutboundResponseError
Defines the listener error types that returned while sending outbound response.
http: PathParameterBindingError
Represents an error, which occurred due to a path parameter binding.
http: PayloadBindingError
Represents an error, which occurred due to payload binding.
http: PayloadValidationError
Represents an error, which occurred due to payload constraint validation.
http: QueryParameterBindingError
Represents an error, which occurred due to a query parameter binding.
http: ReadingInboundRequestBodyError
Represents a listener error that occurred while writing the inbound request entity body.
http: ReadingInboundRequestHeadersError
Represents a listener error that occurred while reading inbound request headers.
http: ReadingInboundResponseBodyError
Represents a client error that occurred while reading inbound response entity body.
http: ReadingInboundResponseHeadersError
Represents a client error that occurred while reading inbound response headers.
http: RemoteServerError
Represents an error, which occurred due to a failure of the remote server(5xx HTTP response).
http: RequestDispatchingError
Represents an error, which occurred during the request dispatching.
http: ResiliencyError
Defines the resiliency error types that returned from client.
http: ResourceDispatchingError
Represents an error, which occurred during the resource dispatching.
http: ServiceDispatchingError
Represents an error, which occurred during the service dispatching.
http: SslError
Represents a client error that occurred due to SSL failure.
http: UnsupportedActionError
Represents a client error that occurred due to unsupported action invocation.
http: UpstreamServiceUnavailableError
Represents a client error that occurred due to upstream service unavailability.
http: Writing100ContinueResponseError
Represents an error that occurred while writing 100 continue response.
http: WritingOutboundRequestBodyError
Represents a client error that occurred while writing outbound request entity body.
http: WritingOutboundRequestHeadersError
Represents a client error that occurred while writing outbound request headers.
http: WritingOutboundResponseBodyError
Represents a listener error that occurred while writing outbound response entity body.
http: WritingOutboundResponseHeadersError
Represents a listener error that occurred while writing outbound response headers.
Object types
http: ClientObject
The representation of the http Client object type for managing resilient clients.
post
function post(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.post()
function can be used to send HTTP POST requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
put
function put(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.put()
function can be used to send HTTP PUT requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
patch
function patch(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.patch()
function can be used to send HTTP PATCH requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
delete
function delete(string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
The Client.delete()
function can be used to send HTTP DELETE requests to HTTP endpoints.
Parameters
- path string - Resource path
- message RequestMessage (default ()) - An optional HTTP outbound request message or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
head
The Client.head()
function can be used to send HTTP HEAD requests to HTTP endpoints.
Parameters
- path string - Resource path
Return Type
- Response|ClientError - The response or an
http:ClientError
if failed to establish the communication with the upstream server
get
function get(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The Client.get()
function can be used to send HTTP GET requests to HTTP endpoints.
Parameters
- path string - Request path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
options
function options(string path, map<string|string[]>? headers, TargetType targetType) returns targetType|ClientError
The Client.options()
function can be used to send HTTP OPTIONS requests to HTTP endpoints.
Parameters
- path string - Request path
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
execute
function execute(string httpVerb, string path, RequestMessage message, map<string|string[]>? headers, string? mediaType, TargetType targetType) returns targetType|ClientError
Invokes an HTTP call with the specified HTTP verb.
Parameters
- httpVerb string - HTTP verb value
- path string - Resource path
- message RequestMessage - An HTTP outbound request or any allowed payload
- mediaType string? (default ()) - The MIME type header of the request entity
- targetType TargetType (default <>) - HTTP response or
anydata
, which is expected to be returned after data binding
Return Type
- targetType|ClientError - The response or the payload (if the
targetType
is configured) or anhttp:ClientError
if failed to establish the communication with the upstream server or a data binding failure
forward
function forward(string path, Request request, TargetType targetType) returns targetType|ClientError
The Client.forward()
function can be used to invoke an HTTP call with inbound request's HTTP verb