ballerina/http package
Type Definitions
Type | Values | Description | |
---|---|---|---|
AcceptEncoding | NEVER | AUTO | ALWAYS | ||
CachingPolicy | RFC_7234 | CACHE_CONTROL_AND_VALIDATORS | Used for configuring the caching behaviour. Setting the
|
|
Chunking | NEVER | AUTO | ALWAYS | ||
CircuitState | OPEN | HALF_OPEN | CLOSED | A finite type for modeling the states of the Circuit Breaker. |
|
Compression | NEVER | AUTO | ALWAYS | ||
HttpOperation | PUT | POST | PATCH | OPTIONS | NONE | HEAD | GET | FORWARD | DELETE | ||
HttpServiceLifeTime | SINGLETON | SESSION | REQUEST | CONNECTION | ||
KeepAlive | NEVER | AUTO | ALWAYS | ||
RedirectCode | 308 | 307 | 305 | 304 | 303 | 302 | 301 | 300 | Status codes for HTTP redirect
|
|
TransferEncoding | CHUNKING |
Annotations
Name | Attachement Points | Data Type | Description |
---|---|---|---|
ResourceConfig | resource | HttpResourceConfig | Configurations annotation for an HTTP resource. |
ServiceConfig | service | HttpServiceConfig | Configurations annotation for an HTTP service. |
WebSocketServiceConfig | service | WSServiceConfig | Configurations annotation for a WebSocket service. |
Records Summary
Record | Description | ||
---|---|---|---|
AuthConfig | AuthConfig record can be used to configure the authentication mechanism used by the HTTP endpoint. |
||
AuthProvider | Configuration for authentication providers | ||
Authentication | Representation of Authentication Config. |
||
Bucket | Represents a discrete sub-part of the time window (Bucket). |
||
CacheConfig | Provides a set of configurations for controlling the caching behaviour of the endpoint. |
||
CircuitBreakerConfig | Provides a set of configurations for controlling the behaviour of the Circuit Breaker. |
||
CircuitBreakerInferredConfig | |||
CircuitHealth | Maintains the health of the Circuit Breaker. |
||
ClientEndpointConfig | Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint. |
||
ConnectionThrottling | Provides configurations for throttling connections of the endpoint. |
||
CorsConfig | Configurations for CORS support. |
||
FailoverClientEndpointConfiguration | Provides a set of HTTP related configurations and failover related configurations. |
||
FailoverConfig | Provides a set of configurations for controlling the failover behaviour of the endpoint. |
||
FailoverConnectorError |
|
||
FailoverInferredConfig | |||
FilterResult | Represents a filter result. This should be populated and returned by each request and response filter function. |
||
FollowRedirects | Provides configurations for controlling the endpoint's behaviour in response to HTTP redirect related responses. |
||
HttpConnectorError |
|
||
HttpResourceConfig | Configuration for an HTTP resource. |
||
HttpServiceConfig | Contains the configurations for an HTTP service. |
||
HttpTimeoutError |
|
||
KeyStore | A record for providing key store related configurations. |
||
ListenerAuthConfig | Representation of AuthConfig. |
||
LoadBalanceClientEndpointConfiguration | The configurations related to the load balance client endpoint. |
||
LoadBalanceConnectorError | Represents an error occurred in an action of the Load Balance connector. | ||
Local | Represents the details of local address. |
||
Protocols | A record for configuring SSL/TLS protocol and version to be used. |
||
ProxyConfig | Proxy server configurations to be used with the HTTP client endpoint. |
||
Remote | Represents the details of remote address. |
||
RequestLimits | Request validation limits configuration for HTTP service endpoint | ||
RetryConfig | Provides configurations for controlling the retry behaviour in failure scenarios. |
||
RollingWindow | Represents a rolling window in the Circuit Breaker. |
||
SecureEndpointConfiguration | Configuration for secure HTTP service endpoint | ||
SecureSocket | Provides configurations for facilitating secure communication with a remote HTTP endpoint. |
||
ServiceEndpointConfiguration | Configuration for HTTP service endpoint | ||
ServiceOcspStapling | A record for providing configurations for certificate revocation status checks. |
||
ServiceSecureSocket | SecureSocket struct represents SSL/TLS options to be used for HTTP service | ||
TargetService | Represents a single service and its related configurations. |
||
TrustStore | A record for providing trust store related configurations. |
||
ValidateCert | A record for providing configurations for certificate revocation status checks. |
||
Versioning | Configurations for service versioning. |
||
WSServiceConfig | Configuration for a WebSocket service. |
||
WebSocketClientEndpointConfig | Configuration struct for WebSocket client endpoint. |
||
WebSocketConnectorError | Represents the error that occurs during WebSocket message transfers. |
||
WebSocketUpgradeConfig |
Objects Summary
Object | Description | ||
---|---|---|---|
AuthHandlerRegistry | Representation of the Http Auth Handler Registry. |
||
AuthnFilter | Representation of the Authentication filter. |
||
AuthnHandlerChain | Representation of Authentication handler chain | ||
AuthzFilter | Representation of the Authorization filter | ||
CircuitBreakerClient | A Circuit Breaker implementation which can be used to gracefully handle network failures. |
||
Failover | Failover caller actions which provides failover capabilities to an HTTP client endpoint. |
||
Filter | Representation of a HTTP Request Filter. This filter will be applied before the request is dispatched to the relevant resource. Any Filter implementation should be structurally similar to the Filter object. |
||
FilterContext | Representation of filter Context. |
||
HttpAuthnHandler | Representation of Authentication handler for HTTP traffic. Any authention interceptor for basic authentication should be struct-wise similar to HttpAuthnInterceptor | ||
HttpAuthzHandler | Representation of AuthzHandler | ||
HttpBasicAuthnHandler | Representation of Basic Auth handler for HTTP traffic | ||
HttpCache | |||
HttpCachingClient | An HTTP caching client implementation which takes an |
||
HttpFuture |
|
||
HttpJwtAuthnHandler | Representation of JWT Auth handler for HTTP traffic | ||
HttpSecureClient | An HTTP secure client for interacting with an HTTP server with authentication. | ||
Listener | Represents service endpoint where one or more services can be registered. so that ballerina program can offer service through this endpoint. |
||
LoadBalancer | Load Balancer adds an additional layer to the HTTP client to make network interactions more resilient. | ||
NonListener | Mock service endpoint which does not open a listening port. | ||
PushPromise |
|
||
Request | Represents an HTTP request. |
||
RequestCacheControl | Cache control directives configuration for requests |
||
Response | Represents an HTTP response. |
||
ResponseCacheControl | Cache control directives configuration for responses |
||
RetryClient | Represents an HTTP Retry client to be used with the HTTP client to provide retrying over HTTP requests. |
||
SecureListener | Representation of an Secure Listener | ||
Service | |||
WebSocketClient | Represents a WebSocket client endpoint. |
||
WebSocketClientService | Represents the WebSocket client service. |
||
WebSocketConnector | Represents a WebSocket connector in ballerina. This include all connector oriented operations. |
||
WebSocketListener | Represents a WebSocket server endpoint. |
||
WebSocketService | Represents the WebSocket client service. |
Functions Summary
Global Variables
Name | Data Type | Description | |
---|---|---|---|
ACCEPTED_202 | int | The HTTP response status code: 202 Accepted |
|
ACCEPT_ENCODING_ALWAYS | AcceptEncoding | ||
ACCEPT_ENCODING_AUTO | AcceptEncoding | ||
ACCEPT_ENCODING_NEVER | AcceptEncoding | ||
AGE | string | HTTP header key |
|
AUTHORIZATION | string | HTTP header key |
|
BAD_GATEWAY_502 | int | The HTTP response status code: 502 Bad Gateway |
|
BAD_REQUEST_400 | int | The HTTP response status code: 400 Bad Request |
|
CACHE_CONTROL | string | HTTP header key |
|
CACHE_CONTROL_AND_VALIDATORS | CachingPolicy | ||
CB_CLOSED_STATE | CircuitState | Represents the closed state of the circuit. When the Circuit Breaker is in |
|
CB_HALF_OPEN_STATE | CircuitState | Represents the half-open state of the circuit. When the Circuit Breaker is in |
|
CB_OPEN_STATE | CircuitState | Represents the open state of the circuit. When the Circuit Breaker is in |
|
CHUNKING_ALWAYS | Chunking | ||
CHUNKING_AUTO | Chunking | ||
CHUNKING_NEVER | Chunking | ||
COMPRESSION_ALWAYS | Compression | ||
COMPRESSION_AUTO | Compression | ||
COMPRESSION_NEVER | Compression | ||
CONFLICT_409 | int | The HTTP response status code: 409 Conflict |
|
CONTENT_LENGTH | string | HTTP header key |
|
CONTENT_TYPE | string | HTTP header key |
|
CONTINUE_100 | int | The HTTP response status code: 100 Continue |
|
CREATED_201 | int | The HTTP response status code: 201 Created |
|
DATE | string | HTTP header key |
|
ETAG | string | HTTP header key |
|
EXPECT | string | HTTP header key |
|
EXPECTATION_FAILED_417 | int | The HTTP response status code: 417 Expectation Failed |
|
EXPIRES | string | HTTP header key |
|
FORBIDDEN_403 | int | The HTTP response status code: 403 Forbidden |
|
FOUND_302 | int | The HTTP response status code: 302 Found |
|
GATEWAY_TIMEOUT_504 | int | The HTTP response status code: 504 Gateway Timeout |
|
GONE_410 | int | The HTTP response status code: 410 Gone |
|
HTTP_DELETE | HttpOperation | Constant for the HTTP DELETE method |
|
HTTP_FORWARD | HttpOperation | ||
HTTP_GET | HttpOperation | Constant for the HTTP GET method |
|
HTTP_HEAD | HttpOperation | Constant for the HTTP HEAD method |
|
HTTP_NONE | HttpOperation | ||
HTTP_OPTIONS | HttpOperation | Constant for the HTTP OPTIONS method |
|
HTTP_PATCH | HttpOperation | Constant for the HTTP PATCH method |
|
HTTP_POST | HttpOperation | Constant for the HTTP POST method |
|
HTTP_PUT | HttpOperation | Constant for the HTTP PUT method |
|
HTTP_VERSION_NOT_SUPPORTED_505 | int | The HTTP response status code: 505 HTTP Version Not Supported |
|
IF_MATCH | string | HTTP header key |
|
IF_MODIFIED_SINCE | string | HTTP header key |
|
IF_NONE_MATCH | string | HTTP header key |
|
IF_RANGE | string | HTTP header key |
|
IF_UNMODIFIED_SINCE | string | HTTP header key |
|
INTERNAL_SERVER_ERROR_500 | int | The HTTP response status code: 500 Internal Server Error |
|
LAST_MODIFIED | string | HTTP header key |
|
LENGTH_REQUIRED_411 | int | The HTTP response status code: 411 Length Required |
|
LOCATION | string | HTTP header key |
|
MAX_AGE | string | When used in requests, it implies that clients are not willing to accept responses whose age is greater than max-age. When used in responses, the response is to be considered stale after the specified number of seconds. |
|
MAX_STALE | string | Indicates that the client is willing to accept responses which have exceeded their freshness lifetime by no more than the specified number of seconds. |
|
MAX_STALE_ANY_AGE | int | A constant for indicating that the max-stale directive does not specify a limit. |
|
METHOD_NOT_ALLOWED_405 | int | The HTTP response status code: 405 Method Not Allowed |
|
MIN_FRESH | string | Indicates that the client is only accepting responses whose freshness lifetime >= current age + min-fresh |
|
MOVED_PERMANENTLY_301 | int | The HTTP response status code: 301 Moved Permanently |
|
MULTIPLE_CHOICES_300 | int | The HTTP response status code: 300 Multiple Choices |
|
MUST_REVALIDATE | string | Indicates that once the response has become stale, it should not be reused for subsequent requests without validating with the origin server. |
|
NON_AUTHORITATIVE_INFORMATION_203 | int | The HTTP response status code: 203 Non Authoritative Information |
|
NOT_ACCEPTABLE_406 | int | The HTTP response status code: 406 Not Acceptable |
|
NOT_FOUND_404 | int | The HTTP response status code: 404 Not Found |
|
NOT_IMPLEMENTED_501 | int | The HTTP response status code: 501 Not Implemented |
|
NOT_MODIFIED_304 | int | The HTTP response status code: 304 Not Modified |
|
NO_CACHE | string | Forces the cache to validate a cached response with the origin server before serving. |
|
NO_CONTENT_204 | int | The HTTP response status code: 204 No Content |
|
NO_STORE | string | Instructs the cache to not store a response in non-volatile storage. |
|
NO_TRANSFORM | string | Instructs intermediaries not to transform the payload. |
|
OK_200 | int | The HTTP response status code: 200 OK |
|
ONLY_IF_CACHED | string | Indicates that the client is only willing to accept a cached response. A cached response is served subject to other constraints posed by the request. |
|
PARTIAL_CONTENT_206 | int | The HTTP response status code: 206 Partial Content |
|
PAYLOAD_TOO_LARGE_413 | int | The HTTP response status code: 413 Payload Too Large |
|
PAYMENT_REQUIRED_402 | int | The HTTP response status code: 402 Payment Required |
|
PERMANENT_REDIRECT_308 | int | The HTTP response status code: 308 Permanent Redirect |
|
PRAGMA | string | HTTP header key |
|
PRECONDITION_FAILED_412 | int | The HTTP response status code: 412 Precondition Failed |
|
PRIVATE | string | Indicates that the response is intended for a single user and should not be stored by shared caches. |
|
PROXY_AUTHENTICATION_REQUIRED_407 | int | The HTTP response status code: 407 Proxy Authentication Required |
|
PROXY_REVALIDATE | string | Has the same meaning as must-revalidate, except that this does not apply to private caches. |
|
PUBLIC | string | Indicates that any cache may store the response. |
|
RANGE_NOT_SATISFIABLE_416 | int | The HTTP response status code: 416 Range Not Satisfiable |
|
REDIRECT_FOUND_302 | RedirectCode | ||
REDIRECT_MOVED_PERMANENTLY_301 | RedirectCode | ||
REDIRECT_MULTIPLE_CHOICES_300 | RedirectCode | ||
REDIRECT_NOT_MODIFIED_304 | RedirectCode | ||
REDIRECT_PERMANENT_REDIRECT_308 | RedirectCode | ||
REDIRECT_SEE_OTHER_303 | RedirectCode | ||
REDIRECT_TEMPORARY_REDIRECT_307 | RedirectCode | ||
REDIRECT_USE_PROXY_305 | RedirectCode | ||
REQUEST_TIMEOUT_408 | int | The HTTP response status code: 408 Request Timeout |
|
RESET_CONTENT_205 | int | The HTTP response status code: 205 Reset Content |
|
RFC_7234 | CachingPolicy | ||
ROUND_ROBIN | string | Stands for the round robin algorithm for load balancing. | |
SEE_OTHER_303 | int | The HTTP response status code: 303 See Other |
|
SERVICE_UNAVAILABLE_503 | int | The HTTP response status code: 503 Service Unavailable |
|
SWITCHING_PROTOCOLS_101 | int | The HTTP response status code: 101 Switching Protocols |
|
S_MAX_AGE | string | In shared caches, this overrides the max-age or Expires header field |
|
TEMPORARY_REDIRECT_307 | int | The HTTP response status code: 307 Temporary Redirect |
|
TRANSFERENCODE_CHUNKING | TransferEncoding | ||
UNAUTHORIZED_401 | int | The HTTP response status code: 401 Unauthorized |
|
UNSUPPORTED_MEDIA_TYPE | int | The HTTP response status code: 415 Unsupported Media Type |
|
UPGRADE_REQUIRED_426 | int | The HTTP response status code: 426 Upgrade Required |
|
URI_TOO_LONG_414 | int | The HTTP response status code: 414 URI Too Long |
|
USE_PROXY_305 | int | The HTTP response status code: 305 Use Proxy |
|
WARNING | string | HTTP header key |
public type AuthConfig
AuthConfig record can be used to configure the authentication mechanism used by the HTTP endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
scheme | string | Scheme of the configuration (Basic, OAuth, JWT etc.) |
|
username | string | Username for Basic authentication |
|
password | string | Password for Basic authentication |
|
accessToken | string | Access token for OAuth2 authentication |
|
refreshToken | string | Refresh token for OAuth2 authentication |
|
refreshUrl | string | Refresh token URL for OAuth2 authentication |
|
consumerKey | string | Consumer key for OAuth2 authentication |
|
consumerSecret | string | Consumer secret for OAuth2 authentication |
|
tokenUrl | string | Token URL for OAuth2 authentication |
|
clientId | string | Clietnt ID for OAuth2 authentication |
|
clientSecret | string | Client secret for OAuth2 authentication |
public type AuthProvider
Configuration for authentication providers
Field Name | Data Type | Default Value | Description |
---|---|---|---|
scheme | string | Authentication schem | |
id | string | Authention provider instance id | |
authProvider | string | Authentication schem implementation | |
issuer | string | Identifier of the token issuer | |
audience | string | Identifier of the token recipients | |
trustStore | TrustStore | Trustore configurations | |
certificateAlias | string | Token signed key alias | |
clockSkew | int | Time in seconds to mitigate clock skew | |
keyStore | KeyStore | ||
keyAlias | string | ||
keyPassword | string | ||
expTime | int | ||
signingAlg | string | ||
propagateToken | boolean |
public type Authentication
Representation of Authentication Config.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
enabled | boolean | flag to enable/disable authentication |
public type Bucket
Represents a discrete sub-part of the time window (Bucket).
Field Name | Data Type | Default Value | Description |
---|---|---|---|
successCount | int | Number of successful requests during the sub-window time frame |
|
failureCount | int | Number of failed requests during the sub-window time frame. |
public type CacheConfig
Provides a set of configurations for controlling the caching behaviour of the endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
enabled | boolean | true | Specifies whether HTTP caching is enabled. Caching is enabled by default. |
isShared | boolean | false | Specifies whether the HTTP caching layer should behave as a public cache or a private cache |
expiryTimeMillis | int | 86400 | The number of milliseconds to keep an entry in the cache |
capacity | int | 8388608 | The capacity of the cache |
evictionFactor | float | 0.2 | The fraction of entries to be removed when the cache is full. The value should be between 0 (exclusive) and 1 (inclusive). |
policy | CachingPolicy | CACHE_CONTROL_AND_VALIDATORS | Gives the user some control over the caching behaviour. By default, this is set to
|
public type CircuitBreakerConfig
Provides a set of configurations for controlling the behaviour of the Circuit Breaker.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
rollingWindow | RollingWindow | ||
failureThreshold | float | The threshold for request failures. When this threshold exceeds, the circuit trips. The threshold should be a value between 0 and 1. |
|
resetTimeMillis | int | The time period(in milliseconds) to wait before attempting to make another request to the upstream service |
|
statusCodes | int[] | Array of HTTP response status codes which are considered as failures |
public type CircuitBreakerInferredConfig
Field Name | Data Type | Default Value | Description |
---|---|---|---|
failureThreshold | float | ||
resetTimeMillis | int | ||
statusCodes | boolean[] | ||
noOfBuckets | int | ||
rollingWindow | RollingWindow |
public type CircuitHealth
Maintains the health of the Circuit Breaker.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
startTime | Time | Circuit Breaker start time |
|
requestCount | int | Total request count since the starting time |
|
errorCount | int | Total error count since the starting time |
|
lastErrorTime | Time | The time that the last error occurred |
|
totalBuckets | Bucket[] | The discrete time buckets into which the time window is divided |
|
lastUsedBucketId | int | ID of the last bucket used in Circuit Breaker calculations |
public type ClientEndpointConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | URL of the target service |
|
circuitBreaker | CircuitBreakerConfig | Circuit Breaker behaviour configurations |
|
timeoutMillis | int | 60000 | The maximum time to wait (in milliseconds) for a response before closing the connection |
keepAlive | KeepAlive | KEEPALIVE_AUTO | Specifies whether to reuse a connection for multiple requests |
transferEncoding | TransferEncoding | CHUNKING | The types of encoding applied to the request |
chunking | Chunking | AUTO | The chunking behaviour of the request |
httpVersion | string | 1.1 | The HTTP version understood by the client |
forwarded | string | disable | The choice of setting |
followRedirects | FollowRedirects | Redirect related options |
|
retryConfig | RetryConfig | Retry related options |
|
proxy | ProxyConfig | Proxy server related options |
|
connectionThrottling | ConnectionThrottling | Configurations for connection throttling |
|
secureSocket | SecureSocket | SSL/TLS related options |
|
cache | CacheConfig | HTTP caching related configurations |
|
acceptEncoding | AcceptEncoding | ACCEPT_ENCODING_AUTO | Specifies the way of handling |
auth | AuthConfig | HTTP authentication releated configurations |
public type ConnectionThrottling
Provides configurations for throttling connections of the endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
maxActiveConnections | int | -1 | Maximum number of active connections allowed for the endpoint. The default value, -1, indicates that the number of connections are not restricted. |
waitTime | int | 60000 | Maximum waiting time for a request to grab an idle connection from the client |
maxActiveStreamsPerConnection | int | -1 | Maximum number of active streams allowed per an HTTP/2 connection |
public type CorsConfig
Configurations for CORS support.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
allowHeaders | string[] | The array of allowed headers by the service |
|
allowMethods | string[] | The array of allowed methods by the service |
|
allowOrigins | string[] | The array of origins with which the response is shared by the service |
|
exposeHeaders | string[] | The whitelisted headers which clients are allowed to access |
|
allowCredentials | boolean | Specifies whether credentials are required to access the service |
|
maxAge | int | -1 | The maximum duration to cache the preflight from client side |
public type FailoverClientEndpointConfiguration
Provides a set of HTTP related configurations and failover related configurations.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
circuitBreaker | CircuitBreakerConfig | Circuit Breaker behaviour configurations |
|
timeoutMillis | int | 60000 | The maximum time to wait (in milliseconds) for a response before closing the connection |
httpVersion | string | 1.1 | The HTTP version supported by the endpoint |
forwarded | string | disable | The choice of setting |
keepAlive | KeepAlive | KEEPALIVE_AUTO | Specifies whether to reuse a connection for multiple requests |
transferEncoding | TransferEncoding | CHUNKING | The types of encoding applied to the request |
chunking | Chunking | AUTO | The chunking behaviour of the request |
followRedirects | FollowRedirects | Redirect related options |
|
retryConfig | RetryConfig | Retry related options |
|
proxy | ProxyConfig | Proxy related options |
|
connectionThrottling | ConnectionThrottling | The configurations for controlling the number of connections allowed concurrently |
|
targets | TargetService[] | ||
cache | CacheConfig | [] | The configurations for controlling the caching behaviour |
acceptEncoding | AcceptEncoding | ACCEPT_ENCODING_AUTO | Specifies the way of handling |
auth | AuthConfig | HTTP authentication releated configurations |
|
failoverCodes | int[] | [501, 502, 503, 504] | Array of HTTP response status codes for which the failover behaviour should be triggered |
intervalMillis | int | Failover delay interval in milliseconds |
public type FailoverConfig
Provides a set of configurations for controlling the failover behaviour of the endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
failoverCodes | int[] | Array of HTTP response status codes for which the failover mechanism triggers |
|
interval | int | Failover delay interval in milliseconds |
public type FailoverConnectorError
FailoverConnectorError
record represents an error occurred during an attempt to failover.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | An explanation on what went wrong |
|
cause | error | The cause of the |
|
statusCode | int | HTTP status code to be sent to the caller |
|
httpConnectorError | HttpConnectorError[] | Errors which occurred at each endpoint during the failover |
public type FailoverInferredConfig
Field Name | Data Type | Default Value | Description |
---|---|---|---|
failoverClientsArray | CallerActions[] | ||
failoverCodesIndex | boolean[] | ||
failoverInterval | int |
public type FilterResult
Represents a filter result. This should be populated and returned by each request and response filter function.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
canProceed | boolean | Flag to check if the execution of the request should proceed or stop |
|
statusCode | int | Status code which will be returned to the request sender if the canProceed is set to |
|
message | string | Message which will be returned to the request sender if the |
public type FollowRedirects
Provides configurations for controlling the endpoint's behaviour in response to HTTP redirect related responses.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
enabled | boolean | false | Enable/disable redirection |
maxCount | int | 5 | Maximun number of redirects to follow |
public type HttpConnectorError
HttpConnectorError
record represents an error occurred during the HTTP client invocation.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | An explanation on what went wrong |
|
cause | error | The error which caused the |
|
statusCode | int | HTTP status code |
public type HttpResourceConfig
Configuration for an HTTP resource.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
methods | string[] | The array of allowed HTTP methods |
|
path | string | The path of resource |
|
body | string | Inbound request entity body name which declared in signature |
|
consumes | string[] | The media types which are accepted by resource |
|
produces | string[] | The media types which are produced by resource |
|
cors | CorsConfig | The CORS configurations for the resource. If not set, the resource will inherit the CORS behaviour of the enclosing service. |
|
transactionInfectable | boolean | true | |
webSocketUpgrade | WebSocketUpgradeConfig | Annotation to define HTTP to WebSocket upgrade |
|
authConfig | ListenerAuthConfig | AuthConfig instance to secure the resource |
public type HttpServiceConfig
Contains the configurations for an HTTP service.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
endpoints | Listener[] | An array of endpoints the service would be attached to |
|
lifetime | HttpServiceLifeTime | The life time of the service |
|
basePath | string | Service base path |
|
compression | Compression | AUTO | The status of compression |
chunking | Chunking | CHUNKING_AUTO | |
cors | CorsConfig | The CORS configurations for the service |
|
versioning | Versioning | ||
authConfig | ListenerAuthConfig | AuthConfig instance to secure the service |
public type HttpTimeoutError
HttpTimeoutError
record represents a timeout error occurred during service invocation.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | An explanation on what went wrong |
|
cause | error | The error which caused the |
|
statusCode | int | HTTP status code. |
public type KeyStore
A record for providing key store related configurations.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
path | string | Path to the key store file |
|
password | string | Key store password |
public type ListenerAuthConfig
Representation of AuthConfig.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
authentication | Authentication | Authentication instance |
|
authProviders | string[] | Array of authentication providers |
|
scopes | string[] | Array of scopes |
public type LoadBalanceClientEndpointConfiguration
The configurations related to the load balance client endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
circuitBreaker | CircuitBreakerConfig |
|
|
timeoutMillis | int | 60000 |
|
httpVersion | string | 1.1 |
|
forwarded | string | disable |
|
keepAlive | KeepAlive | KEEPALIVE_AUTO |
|
transferEncoding | TransferEncoding | CHUNKING |
|
chunking | Chunking | AUTO |
|
followRedirects | FollowRedirects |
|
|
retryConfig | RetryConfig |
|
|
proxy | ProxyConfig |
|
|
connectionThrottling | ConnectionThrottling |
|
|
targets | TargetService[] | ||
cache | CacheConfig | [] |
|
acceptEncoding | AcceptEncoding | ACCEPT_ENCODING_AUTO |
|
auth | AuthConfig |
|
|
algorithm | string | ROUND_ROBIN |
|
failover | boolean | true |
|
public type LoadBalanceConnectorError
Represents an error occurred in an action of the Load Balance connector.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | An error message explaining about the error. | |
cause | error | The error that caused HttpConnectorError to get thrown. | |
statusCode | int | HTTP status code of the LoadBalanceConnectorError. | |
httpConnectorError | HttpConnectorError[] | Array of HttpConnectorError error occurred at each endpoint. |
public type Local
Represents the details of local address.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
host | string |
|
|
port | int |
|
public type Protocols
A record for configuring SSL/TLS protocol and version to be used.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
name | string | SSL Protocol to be used (eg: TLS1.2) |
|
versions | string[] | SSL/TLS protocols to be enabled (eg: TLSv1,TLSv1.1,TLSv1.2) |
public type ProxyConfig
Proxy server configurations to be used with the HTTP client endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
host | string | Host name of the proxy server |
|
port | int | Proxy server port |
|
userName | string | Proxy server username |
|
password | string | proxy server password |
public type Remote
Represents the details of remote address.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
host | string |
|
|
port | int |
|
public type RequestLimits
Request validation limits configuration for HTTP service endpoint
Field Name | Data Type | Default Value | Description |
---|---|---|---|
maxUriLength | int | -1 | Maximum length allowed in the URL |
maxHeaderSize | int | -1 | Maximum size allowed in the headers |
maxEntityBodySize | int | -1 | Maximum size allowed in the entity body |
public type RetryConfig
Provides configurations for controlling the retry behaviour in failure scenarios.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
count | int | Number of retry attempts before giving up |
|
interval | int | Retry interval in milliseconds |
|
backOffFactor | float | Multiplier of the retry interval to exponentailly increase retry interval |
|
maxWaitInterval | int | Maximum time of the retry interval in milliseconds |
public type RollingWindow
Represents a rolling window in the Circuit Breaker.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
timeWindowMillis | int | 60000 | Time period in milliseconds for which the failure threshold is calculated |
bucketSizeMillis | int | 10000 | The granularity at which the time window slides. This is measured in milliseconds. |
public type SecureEndpointConfiguration
Configuration for secure HTTP service endpoint
Field Name | Data Type | Default Value | Description |
---|---|---|---|
host | string | Host of the service | |
port | int | 9090 | Port number of the service |
keepAlive | KeepAlive | KEEPALIVE_AUTO | The keepAlive behaviour of the connection for a particular port |
transferEncoding | TransferEncoding | TRANSFERENCODE_CHUNKING | The types of encoding applied to the response |
secureSocket | ServiceSecureSocket | The SSL configurations for the service endpoint | |
httpVersion | string | 1.1 | Highest HTTP version supported |
requestLimits | RequestLimits | Request validation limits configuration | |
filters | Filter[] | Filters to be applied to the request before dispatched to the actual resource | |
authProviders | AuthProvider[] | The array of AuthProviders which are used to authenticate the users |
public type SecureSocket
Provides configurations for facilitating secure communication with a remote HTTP endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
trustStore | TrustStore | TrustStore related options |
|
keyStore | KeyStore | KeyStore related options |
|
protocol | Protocols | SSL/TLS protocol related options |
|
certValidation | ValidateCert | Certificate validation against CRL or OCSP related options |
|
ciphers | string[] | List of ciphers to be used eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA |
|
verifyHostname | boolean | true | Enable/disable host name verification |
shareSession | boolean | true | Enable/disable new SSL session creation |
ocspStapling | boolean | Enable/disable OCSP stapling |
public type ServiceEndpointConfiguration
Configuration for HTTP service endpoint
Field Name | Data Type | Default Value | Description |
---|---|---|---|
host | string | Host of the service | |
port | int | Port number of the service | |
keepAlive | KeepAlive | KEEPALIVE_AUTO | The keepAlive behaviour of the connection for a particular port |
transferEncoding | TransferEncoding | TRANSFERENCODE_CHUNKING | The types of encoding applied to the response |
secureSocket | ServiceSecureSocket | The SSL configurations for the service endpoint | |
httpVersion | string | 1.1 | Highest HTTP version supported |
requestLimits | RequestLimits | Request validation limits configuration | |
filters | Filter[] | Filters to be applied to the request before dispatched to the actual resource |
public type ServiceOcspStapling
A record for providing configurations for certificate revocation status checks.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
enable | boolean | The status of OCSP stapling |
|
cacheSize | int | Maximum size of the cache |
|
cacheValidityPeriod | int | The time period for which a cache entry is valid |
public type ServiceSecureSocket
SecureSocket struct represents SSL/TLS options to be used for HTTP service
Field Name | Data Type | Default Value | Description |
---|---|---|---|
trustStore | TrustStore | TrustStore related options | |
keyStore | KeyStore | KeyStore related options | |
protocol | Protocols | ||
certValidation | ValidateCert | Certificate validation against CRL or OCSP related options | |
ciphers | string[] | List of ciphers to be used. eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | |
sslVerifyClient | string | The type of client certificate verification | |
shareSession | boolean | true | Enable/disable new ssl session creation |
ocspStapling | ServiceOcspStapling | Enable/disable ocsp stapling |
public type TargetService
Represents a single service and its related configurations.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | URL of the target service |
|
secureSocket | SecureSocket | Configurations for secure communication with the remote HTTP endpoint |
public type TrustStore
A record for providing trust store related configurations.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
path | string | Path to the trust store file |
|
password | string | Trust store password |
public type ValidateCert
A record for providing configurations for certificate revocation status checks.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
enable | boolean | The status of |
|
cacheSize | int | Maximum size of the cache |
|
cacheValidityPeriod | int | The time period for which a cache entry is valid |
public type Versioning
Configurations for service versioning.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
pattern | string | v{major}.{minor} | Expecting version pattern in the request url |
allowNoVersion | boolean | false | Allow to dispatch requests which does not hold version path segment in url |
matchMajorVersion | boolean | false | Allow to dispatch requests which specify only the major version in url |
public type WSServiceConfig
Configuration for a WebSocket service.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
endpoints | Listener[] | An array of endpoints the service would be attached to |
|
webSocketEndpoints | WebSocketListener[] | An array of endpoints the service would be attached to |
|
path | string | Path of the WebSocket service |
|
subProtocols | string[] | Negotiable sub protocol by the service |
|
idleTimeoutInSeconds | int | Idle timeout for the client connection. This can be triggered by putting onIdleTimeout resource in WS service. |
|
maxFrameSize | int | The maximum payload size of a WebSocket frame in bytes |
public type WebSocketClientEndpointConfig
Configuration struct for WebSocket client endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | The url of the server to connect to |
|
callbackService | typedesc | The callback service for the client. Resources in this service gets called on receipt of messages from the server. |
|
subProtocols | string[] | Negotiable sub protocols for the client |
|
customHeaders | map<string> | Custom headers which should be sent to the server |
|
idleTimeoutInSeconds | int | -1 | Idle timeout of the client. Upon timeout, onIdleTimeout resource in the client service will be triggered (if there is one defined) |
readyOnConnect | boolean | true | true if the client is ready to recieve messages as soon as the connection is established. This is true by default. If changed to false the function ready() of the
|
public type WebSocketConnectorError
Represents the error that occurs during WebSocket message transfers.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | An error message that explains the error |
|
cause | error | The error(s) that caused the |
public type WebSocketUpgradeConfig
Field Name | Data Type | Default Value | Description |
---|---|---|---|
upgradePath | string | ||
upgradeService | typedesc |
public function createHttpCachingClient(string url, ClientEndpointConfig config, CacheConfig cacheConfig) returns (CallerActions)
Creates an HTTP client capable of caching HTTP responses.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | ||
config | ClientEndpointConfig | ||
cacheConfig | CacheConfig |
Return Type | Description | ||
---|---|---|---|
CallerActions |
public function createHttpClient(string uri, ClientEndpointConfig config) returns (CallerActions)
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
uri | string | ||
config | ClientEndpointConfig |
Return Type | Description | ||
---|---|---|---|
CallerActions |
public function createHttpSecureClient(string url, ClientEndpointConfig config) returns (CallerActions)
Creates an HTTP client capable of securing HTTP requests with authentication.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | ||
config | ClientEndpointConfig |
Return Type | Description | ||
---|---|---|---|
CallerActions |
public function createSimpleHttpClient(string uri, ClientEndpointConfig config) returns (CallerActions)
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
uri | string | ||
config | ClientEndpointConfig |
Return Type | Description | ||
---|---|---|---|
CallerActions |
public function decode(string url, string charset) returns (string | error)
Decodes the given URL
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | URL to be decoded | |
charset | string | Charactor set that URL to be decoded |
Return Type | Description | ||
---|---|---|---|
string | error | The decoded URL |
public function encode(string url, string charset) returns (string | error)
Encodes the given URL
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | URL to be encoded | |
charset | string | Charactor set that URL to be encoded |
Return Type | Description | ||
---|---|---|---|
string | error | The encoded URL |
public function extractBasicAuthHeaderValue(Request req) returns (string | null)
Extracts the basic authentication header value from the request
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
req | Request | Request instance |
Return Type | Description | ||
---|---|---|---|
string | null | string: value of the basic authentication header, or null if not found |
public function getcurrentFailureRatio(CircuitHealth circuitHealth) returns (float)
Calculate Failure at a given point.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
circuitHealth | CircuitHealth |
|
Return Type | Description | ||
---|---|---|---|
float |
public function invokeEndpoint(string path, Request outRequest, HttpOperation requestAction, CallerActions httpClient) returns (Response | HttpConnectorError)
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
path | string | ||
outRequest | Request | ||
requestAction | HttpOperation | ||
httpClient | CallerActions |
Return Type | Description | ||
---|---|---|---|
Response | HttpConnectorError |
public function parseHeader(string headerValue) returns ((string,map) | error)
Parses the given header value to extract its value and parameter map.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
headerValue | string | The header value |
Return Type | Description | ||
---|---|---|---|
(string,map) | error | Returns a tuple containing the value and its parameter map |
public function resetBucketStats(CircuitHealth circuitHealth, int bucketId)
Reset the bucket values to default ones.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
circuitHealth | CircuitHealth |
|
|
bucketId | int |
|
public function roundRobin(LoadBalancer lb, CallerActions[] loadBalanceConfigArray) returns (CallerActions)
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
lb | LoadBalancer | ||
loadBalanceConfigArray | CallerActions[] |
Return Type | Description | ||
---|---|---|---|
CallerActions |
public function updateCircuitState(CircuitHealth circuitHealth, CircuitState currentStateValue, CircuitBreakerInferredConfig circuitBreakerInferredConfig) returns (CircuitState)
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
circuitHealth | CircuitHealth | ||
currentStateValue | CircuitState | ||
circuitBreakerInferredConfig | CircuitBreakerInferredConfig |
Return Type | Description | ||
---|---|---|---|
CircuitState |
public type AuthHandlerRegistry object
Representation of the Http Auth Handler Registry.
-
<AuthHandlerRegistry> add(string id, HttpAuthnHandler authnHandler)
Add an HttpAuthnHandler to HttpAuthHandlerRegistry
Parameter Name Data Type Default Value Description id string Auth provider id
authnHandler HttpAuthnHandler HttpAuthnHandler instance
-
<AuthHandlerRegistry> get(string id) returns (HttpAuthnHandler)
Retrieves an HttpAuthnHandler from HttpAuthHandlerRegistry which corresponds to the given id
Parameter Name Data Type Default Value Description id string Auth provider id
Return Type Description HttpAuthnHandler HttpAuthnHandler instance or nil if not found
-
<AuthHandlerRegistry> getAll() returns (map<HttpAuthnHandler>)
Retrieve the HttpAuthnHandler map
Return Type Description map<HttpAuthnHandler> map of HttpAuthnHandler
-
<AuthHandlerRegistry> remove(string id)
Removes a specific authn handler from the HttpAuthnHandler map
Parameter Name Data Type Default Value Description id string -
<AuthHandlerRegistry> clear()
Removes all authn handler from the HttpAuthnHandler map
public type AuthnFilter object
Representation of the Authentication filter.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
authnHandlerChain | AuthnHandlerChain | The Authentication handler chain |
-
<AuthnFilter> filterRequest(Request request, FilterContext context) returns (FilterResult)
Request filter method which attempts to authenticated the request.
Parameter Name Data Type Default Value Description request Request An inboud HTTP request message
context FilterContext A filter context
Return Type Description FilterResult The resulting object after filtering the request
public type AuthnHandlerChain object
Representation of Authentication handler chain
-
<AuthnHandlerChain> handle(Request req) returns (boolean)
Parameter Name Data Type Default Value Description req Request Return Type Description boolean -
<AuthnHandlerChain> handleWithSpecificAuthnHandlers(string[] authProviderIds, Request req) returns (boolean)
Parameter Name Data Type Default Value Description authProviderIds string[] req Request Return Type Description boolean
public type AuthzFilter object
Representation of the Authorization filter
Field Name | Data Type | Default Value | Description |
---|---|---|---|
authzHandler | HttpAuthzHandler |
-
<AuthzFilter> filterRequest(Request request, FilterContext context) returns (FilterResult)
Filter function implementation which tries to authorize the request
Parameter Name Data Type Default Value Description request Request Request instance context FilterContext FilterContext instance Return Type Description FilterResult FilterResult: Authorization result to indicate if the request can proceed or not
public type CircuitBreakerClient object
A Circuit Breaker implementation which can be used to gracefully handle network failures.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
serviceUri | string | The URL of the target service |
|
config | ClientEndpointConfig | The configurations of the client endpoint associated with this |
|
circuitBreakerInferredConfig | CircuitBreakerInferredConfig | Configurations derived from |
|
httpClient | CallerActions | The underlying |
|
circuitHealth | CircuitHealth | The circuit health monitor |
|
currentCircuitState | CircuitState | CB_CLOSED_STATE | The current state the cicuit is in |
-
<CircuitBreakerClient> post(string path) returns (Response | HttpConnectorError)
The POST action implementation of the Circuit Breaker. This wraps the
post()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> head(string path) returns (Response | HttpConnectorError)
The HEAD action implementation of the Circuit Breaker. This wraps the
head()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> put(string path) returns (Response | HttpConnectorError)
The PUT action implementation of the Circuit Breaker. This wraps the
put()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> execute(string httpVerb, string path, Request request) returns (Response | HttpConnectorError)
This wraps the
post()
function of the underlying HTTP actions provider. Theexecute()
function can be used to invoke an HTTP call with the given HTTP verb.Parameter Name Data Type Default Value Description httpVerb string HTTP verb to be used for the request
path string Resource path
request Request A Request struct
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> patch(string path) returns (Response | HttpConnectorError)
The PATCH action implementation of the Circuit Breaker. This wraps the
patch()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> delete(string path) returns (Response | HttpConnectorError)
The DELETE action implementation of the Circuit Breaker. This wraps the
delete()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> get(string path) returns (Response | HttpConnectorError)
The GET action implementation of the Circuit Breaker. This wraps the
get()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> options(string path) returns (Response | HttpConnectorError)
The OPTIONS action implementation of the Circuit Breaker. This wraps the
options()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> forward(string path, Request request) returns (Response | HttpConnectorError)
This wraps the
forward()
function of the underlying HTTP actions provider. The Forward action can be used to forward an incoming request to an upstream service as it is.Parameter Name Data Type Default Value Description path string Resource path
request Request A Request struct
Return Type Description Response | HttpConnectorError The Response struct
-
<CircuitBreakerClient> submit(string httpVerb, string path, Request request) returns (HttpFuture | HttpConnectorError)
Circuit breaking not supported. Defaults to the
submit()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description httpVerb string The HTTP verb
path string The resource path
request Request An HTTP outbound request message
Return Type Description HttpFuture | HttpConnectorError The
Future
for further interactions -
<CircuitBreakerClient> getResponse(HttpFuture httpFuture) returns (Response | HttpConnectorError)
Circuit breaking not supported. Defaults to the
getResponse()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description Response | HttpConnectorError The HTTP response message
-
<CircuitBreakerClient> hasPromise(HttpFuture httpFuture) returns (boolean)
Circuit breaking not supported. Defaults to the
hasPromise()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description boolean Returns true if the
PushPromise
exists -
<CircuitBreakerClient> getNextPromise(HttpFuture httpFuture) returns (PushPromise | HttpConnectorError)
Circuit breaking not supported. Defaults to the
getNextPromise()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description PushPromise | HttpConnectorError The HTTP Push Promise message
-
<CircuitBreakerClient> getPromisedResponse(PushPromise promise) returns (Response | HttpConnectorError)
Circuit breaking not supported. Defaults to the
getPromisedResponse()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description promise PushPromise The related Push Promise message
Return Type Description Response | HttpConnectorError The Push Response message
-
<CircuitBreakerClient> rejectPromise(PushPromise promise)
Circuit breaking not supported. Defaults to the
rejectPromise()
function of the underlying HTTP actions provider.Parameter Name Data Type Default Value Description promise PushPromise The
PushPromise
to be rejected
public type Failover object
Failover caller actions which provides failover capabilities to an HTTP client endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
serviceUri | string | The URL of the remote HTTP endpoint |
|
config | ClientEndpointConfig | The configurations of the client endpoint associated with this |
|
failoverInferredConfig | FailoverInferredConfig | Configurations derived from |
-
<Failover> post(string path) returns (Response | HttpConnectorError)
The POST action implementation of the Failover Connector.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> head(string path) returns (Response | HttpConnectorError)
The HEAD action implementation of the Failover Connector.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> patch(string path) returns (Response | HttpConnectorError)
The PATCH action implementation of the Failover Connector.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> put(string path) returns (Response | HttpConnectorError)
The PUT action implementation of the Failover Connector.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> options(string path) returns (Response | HttpConnectorError)
The OPTIONS action implementation of the Failover Connector.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> forward(string path, Request request) returns (Response | HttpConnectorError)
Invokes an HTTP call using the incoming request's HTTP method.
Parameter Name Data Type Default Value Description path string Resource path
request Request An HTTP request
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> execute(string httpVerb, string path, Request request) returns (Response | HttpConnectorError)
Invokes an HTTP call with the specified HTTP method.
Parameter Name Data Type Default Value Description httpVerb string HTTP method to be used for the request
path string Resource path
request Request An HTTP request
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> delete(string path) returns (Response | HttpConnectorError)
The DELETE action implementation of the Failover Connector.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> get(string path) returns (Response | HttpConnectorError)
The GET action implementation of the Failover Connector.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The response or an
HttpConnectorError
if failed to fulfill the request -
<Failover> submit(string httpVerb, string path, Request request) returns (HttpFuture | HttpConnectorError)
Submits an HTTP request to a service with the specified HTTP verb.
Parameter Name Data Type Default Value Description httpVerb string The HTTP verb value
path string The Resource path
request Request An HTTP request
Return Type Description HttpFuture | HttpConnectorError The Future for further interactions or an
HttpConnectorError
if failed to fulfill the request -
<Failover> getResponse(HttpFuture httpFuture) returns (HttpConnectorError)
Retrieves the response for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description HttpConnectorError HttpConnectorError
if failed to fulfill the request -
<Failover> hasPromise(HttpFuture httpFuture) returns (boolean)
Checks whether server push exists for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description boolean Returns true if the push promise exists
-
<Failover> getNextPromise(HttpFuture httpFuture) returns (PushPromise | HttpConnectorError)
Retrieves the next available push promise for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description PushPromise | HttpConnectorError The HTTP Push Promise message or an
HttpConnectorError
if failed to fulfill the request -
<Failover> getPromisedResponse(PushPromise promise) returns (Response | HttpConnectorError)
Retrieves the promised server push response.
Parameter Name Data Type Default Value Description promise PushPromise The related Push Promise message
Return Type Description Response | HttpConnectorError The HTTP Push Response message or an
HttpConnectorError
if failed to fulfill the request -
<Failover> rejectPromise(PushPromise promise)
Rejects a push promise.
Parameter Name Data Type Default Value Description promise PushPromise The Push Promise to be rejected
public type Filter object
Representation of a HTTP Request Filter. This filter will be applied before the request is dispatched to the relevant resource. Any Filter implementation should be structurally similar to the Filter object.
-
<Filter> filterRequest(Request request, FilterContext context) returns (FilterResult)
Request filter function.
Parameter Name Data Type Default Value Description request Request An inboud HTTP request message
context FilterContext A filter context
Return Type Description FilterResult The resulting object after filtering the request
public type FilterContext object
Representation of filter Context.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
serviceType | typedesc | Type of the service |
|
serviceName | string | Name of the service |
|
resourceName | string | Name of the resource |
public type HttpAuthnHandler object
Representation of Authentication handler for HTTP traffic. Any authention interceptor for basic authentication should be struct-wise similar to HttpAuthnInterceptor
Field Name | Data Type | Default Value | Description |
---|---|---|---|
name | string |
-
<HttpAuthnHandler> canHandle(Request req) returns (boolean)
Parameter Name Data Type Default Value Description req Request Return Type Description boolean -
<HttpAuthnHandler> handle(Request req) returns (boolean)
Parameter Name Data Type Default Value Description req Request Return Type Description boolean
public type HttpAuthzHandler object
Representation of AuthzHandler
Field Name | Data Type | Default Value | Description |
---|---|---|---|
authProvider | AuthProvider | ||
authzCache | Cache | authorization cache instance |
public type HttpBasicAuthnHandler object
Representation of Basic Auth handler for HTTP traffic
Field Name | Data Type | Default Value | Description |
---|---|---|---|
name | string | Authentication handler name | |
authProvider | AuthProvider | AuthProvider instance |
-
<HttpBasicAuthnHandler> canHandle(Request req) returns (boolean)
Parameter Name Data Type Default Value Description req Request Return Type Description boolean -
<HttpBasicAuthnHandler> handle(Request req) returns (boolean)
Parameter Name Data Type Default Value Description req Request Return Type Description boolean
public type HttpCache object
public type HttpCachingClient object
An HTTP caching client implementation which takes an HttpActions
instance and wraps it with an HTTP caching layer.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
serviceUri | string | The URL of the remote HTTP endpoint |
|
config | ClientEndpointConfig | The configurations of the client endpoint associated with this |
|
httpClient | CallerActions | The underlying |
|
cache | HttpCache | The cache storage for the HTTP responses |
|
cacheConfig | CacheConfig | Caching configurations for the HTTP cache |
-
<HttpCachingClient> post(string path) returns (Response | HttpConnectorError)
Responses returned for POST requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for POST requests invalidate the cached responses for the same resource.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> head(string path) returns (Response | HttpConnectorError)
Responses for HEAD requests are cacheable and as such, will be routed through the HTTP cache. Only if a suitable response cannot be found will the request be directed to the origin server.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> put(string path) returns (Response | HttpConnectorError)
Responses returned for PUT requests are not cacheable. Therefore, the requests are simply directed to the origin server. In addition, PUT requests invalidate the currently stored responses for the given path.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> execute(string httpMethod, string path, Request request) returns (Response | HttpConnectorError)
Invokes an HTTP call with the specified HTTP method. This is not a cacheable operation, unless the HTTP method used is GET or HEAD.
Parameter Name Data Type Default Value Description httpMethod string HTTP method to be used for the request
path string Resource path
request Request An HTTP request
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> patch(string path) returns (Response | HttpConnectorError)
Responses returned for PATCH requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for PATCH requests invalidate the cached responses for the same resource.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> delete(string path) returns (Response | HttpConnectorError)
Responses returned for DELETE requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for DELETE requests invalidate the cached responses for the same resource.
Parameter Name Data Type Default Value Description path string Resource path
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> get(string path) returns (Response | HttpConnectorError)
Responses for GET requests are cacheable and as such, will be routed through the HTTP cache. Only if a suitable response cannot be found will the request be directed to the origin server.
Parameter Name Data Type Default Value Description path string Request path
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> options(string path) returns (Response | HttpConnectorError)
Responses returned for OPTIONS requests are not cacheable. Therefore, the requests are simply directed to the origin server. Responses received for OPTIONS requests invalidate the cached responses for the same resource.
Parameter Name Data Type Default Value Description path string Request path
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> forward(string path, Request request) returns (Response | HttpConnectorError)
Forward action can be used to invoke an HTTP call with inbound request's HTTP method. Only inbound requests of GET and HEAD HTTP method types are cacheable.
Parameter Name Data Type Default Value Description path string Request path
request Request The HTTP request to be forwarded
Return Type Description Response | HttpConnectorError The inbound response message
-
<HttpCachingClient> submit(string httpVerb, string path, Request request) returns (HttpFuture | HttpConnectorError)
Submits an HTTP request to a service with the specified HTTP verb.
Parameter Name Data Type Default Value Description httpVerb string The HTTP verb value
path string The resource path
request Request An HTTP request
Return Type Description HttpFuture | HttpConnectorError The Future for further interactions
-
<HttpCachingClient> getResponse(HttpFuture httpFuture) returns (Response | HttpConnectorError)
Retrieves the response for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description Response | HttpConnectorError The HTTP response message
-
<HttpCachingClient> hasPromise(HttpFuture httpFuture) returns (boolean)
Checks whether server push exists for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description boolean Returns true if the push promise exists
-
<HttpCachingClient> getNextPromise(HttpFuture httpFuture) returns (PushPromise | HttpConnectorError)
Retrieves the next available push promise for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation
Return Type Description PushPromise | HttpConnectorError The HTTP Push Promise message
-
<HttpCachingClient> getPromisedResponse(PushPromise promise) returns (Response | HttpConnectorError)
Retrieves the promised server push response.
Parameter Name Data Type Default Value Description promise PushPromise The related Push Promise message
Return Type Description Response | HttpConnectorError HTTP The Push Response message
-
<HttpCachingClient> rejectPromise(PushPromise promise)
Rejects a push promise.
Parameter Name Data Type Default Value Description promise PushPromise The Push Promise to be rejected
public type HttpFuture object
HttpFuture
represents a 'future' that returns as a result of an asynchronous HTTP invocation.
Mainly the submit()
function gives out an HttpFuture
as the result.
This is used to do further interactions such as getResponse()
, getNextPromise()
, getPromisedResponse()
with the endpoint.
public type HttpJwtAuthnHandler object
Representation of JWT Auth handler for HTTP traffic
Field Name | Data Type | Default Value | Description |
---|---|---|---|
name | string | Authentication handler name | |
jwtAuthenticator | JWTAuthProvider | JWTAuthenticator instance |
-
<HttpJwtAuthnHandler> canHandle(Request req) returns (boolean)
Parameter Name Data Type Default Value Description req Request Return Type Description boolean -
<HttpJwtAuthnHandler> handle(Request req) returns (boolean)
Parameter Name Data Type Default Value Description req Request Return Type Description boolean
public type HttpSecureClient object
An HTTP secure client for interacting with an HTTP server with authentication.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
serviceUri | string | ||
config | ClientEndpointConfig | ||
httpClient | CallerActions |
-
<HttpSecureClient> post(string path) returns (Response | HttpConnectorError)
The POST action implementation of the HTTP Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> head(string path) returns (Response | HttpConnectorError)
The HEAD action implementation of the HTTP Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> put(string path) returns (Response | HttpConnectorError)
The PUT action implementation of the HTTP Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> execute(string httpVerb, string path, Request request) returns (Response | HttpConnectorError)
Invokes an HTTP call with the specified HTTP verb.
Parameter Name Data Type Default Value Description httpVerb string HTTP verb value path string Resource path request Request Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> patch(string path) returns (Response | HttpConnectorError)
The PATCH action implementation of the HTTP Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> delete(string path) returns (Response | HttpConnectorError)
The DELETE action implementation of the HTTP connector
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> get(string path) returns (Response | HttpConnectorError)
GET action implementation of the HTTP Connector
Parameter Name Data Type Default Value Description path string Request path Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> options(string path) returns (Response | HttpConnectorError)
OPTIONS action implementation of the HTTP Connector
Parameter Name Data Type Default Value Description path string Request path Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> forward(string path, Request request) returns (Response | HttpConnectorError)
Forward action can be used to invoke an HTTP call with inbound request's HTTP verb
Parameter Name Data Type Default Value Description path string Request path request Request Return Type Description Response | HttpConnectorError The inbound response message -
<HttpSecureClient> submit(string httpVerb, string path, Request request) returns (HttpFuture | HttpConnectorError)
Submits an HTTP request to a service with the specified HTTP verb.
Parameter Name Data Type Default Value Description httpVerb string The HTTP verb value path string The Resource path request Request Return Type Description HttpFuture | HttpConnectorError The Future for further interactions -
<HttpSecureClient> getResponse(HttpFuture httpFuture) returns (Response | HttpConnectorError)
Retrieves response for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation Return Type Description Response | HttpConnectorError The HTTP response message -
<HttpSecureClient> hasPromise(HttpFuture httpFuture) returns (boolean)
Checks whether server push exists for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation Return Type Description boolean Whether push promise exists -
<HttpSecureClient> getNextPromise(HttpFuture httpFuture) returns (PushPromise | HttpConnectorError)
Retrieves the next available push promise for a previously submitted request.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation Return Type Description PushPromise | HttpConnectorError The HTTP Push Promise message -
<HttpSecureClient> getPromisedResponse(PushPromise promise) returns (Response | HttpConnectorError)
Retrieves the promised server push response.
Parameter Name Data Type Default Value Description promise PushPromise The related Push Promise message Return Type Description Response | HttpConnectorError HTTP The Push Response message -
<HttpSecureClient> rejectPromise(PushPromise promise)
Rejects a push promise.
Parameter Name Data Type Default Value Description promise PushPromise The Push Promise need to be rejected
public type Listener object
Represents service endpoint where one or more services can be registered. so that ballerina program can offer service through this endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
remote | Remote |
|
|
local | Local |
|
|
protocol | string |
|
-
<Listener> init(ServiceEndpointConfiguration config)
Parameter Name Data Type Default Value Description config ServiceEndpointConfiguration -
<Listener> initEndpoint() returns (error)
Gets called when the endpoint is being initialize during package init time
Return Type Description error Error occured during initialization -
<Listener> register(typedesc serviceType)
Gets called every time a service attaches itself to this endpoint. Also happens at package initialization.
Parameter Name Data Type Default Value Description serviceType typedesc The type of the service to be registered -
<Listener> start()
Starts the registered service
-
<Listener> getCallerActions() returns (Connection)
Returns the connector that client code uses
Return Type Description Connection The connector that client code uses -
<Listener> stop()
Stops the registered service
public type LoadBalancer object
Load Balancer adds an additional layer to the HTTP client to make network interactions more resilient.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
serviceUri | string | ||
config | ClientEndpointConfig | ||
loadBalanceClientsArray | CallerActions[] | ||
algorithm | string | ||
nextIndex | int | ||
failover | boolean |
-
<LoadBalancer> post(string path) returns (Response | HttpConnectorError)
The POST action implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> head(string path) returns (Response | HttpConnectorError)
The HEAD action implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> patch(string path) returns (Response | HttpConnectorError)
The PATCH action implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> put(string path) returns (Response | HttpConnectorError)
The PUT action implementation of the Load Balance Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> options(string path) returns (Response | HttpConnectorError)
The OPTIONS action implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> forward(string path, Request request) returns (Response | HttpConnectorError)
The FORWARD action implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description path string Resource path request Request A Request struct Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> execute(string httpVerb, string path, Request request) returns (Response | HttpConnectorError)
The EXECUTE action implementation of the LoadBalancer Connector. The Execute action can be used to invoke an HTTP call with the given HTTP verb.
Parameter Name Data Type Default Value Description httpVerb string HTTP verb to be used for the request path string Resource path request Request A Request struct Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> delete(string path) returns (Response | HttpConnectorError)
The DELETE action implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> get(string path) returns (Response | HttpConnectorError)
The GET action implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description path string Resource path Return Type Description Response | HttpConnectorError The Response struct -
<LoadBalancer> submit(string httpVerb, string path, Request request) returns (HttpFuture | HttpConnectorError)
The submit implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description httpVerb string The HTTP verb value path string The Resource path request Request Return Type Description HttpFuture | HttpConnectorError The Future for further interactions -
<LoadBalancer> getResponse(HttpFuture httpFuture) returns (Response | HttpConnectorError)
The getResponse implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation Return Type Description Response | HttpConnectorError The HTTP response message -
<LoadBalancer> hasPromise(HttpFuture httpFuture) returns (boolean)
The hasPromise implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation Return Type Description boolean Whether push promise exists -
<LoadBalancer> getNextPromise(HttpFuture httpFuture) returns (PushPromise | HttpConnectorError)
The getNextPromise implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation Return Type Description PushPromise | HttpConnectorError The HTTP Push Promise message -
<LoadBalancer> getPromisedResponse(PushPromise promise) returns (Response | HttpConnectorError)
The getPromisedResponse implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description promise PushPromise The related Push Promise message Return Type Description Response | HttpConnectorError HTTP The Push Response message -
<LoadBalancer> rejectPromise(PushPromise promise)
The rejectPromise implementation of the LoadBalancer Connector.
Parameter Name Data Type Default Value Description promise PushPromise The Push Promise need to be rejected
public type NonListener object
Mock service endpoint which does not open a listening port.
-
<NonListener> init(ServiceEndpointConfiguration config)
Parameter Name Data Type Default Value Description config ServiceEndpointConfiguration -
<NonListener> initEndpoint() returns (error)
Return Type Description error -
<NonListener> register(typedesc serviceType)
Parameter Name Data Type Default Value Description serviceType typedesc -
<NonListener> start()
-
<NonListener> getCallerActions() returns (Connection)
Return Type Description Connection -
<NonListener> stop()
public type PushPromise object
PushPromise
represents an HTTP/2 PUSH_PROMISE frame.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
path | string | The resource path |
|
method | string | The HTTP method |
-
<PushPromise> hasHeader(string headerName) returns (boolean)
Checks whether the requested header exists.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description boolean A
boolean
representing the existence of a given header -
<PushPromise> getHeader(string headerName) returns (string)
Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string The header value, or null if there is no such header
-
<PushPromise> getHeaders(string headerName) returns (string[])
Gets transport headers from the
PushPromise
.Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string[] The array of header values
-
<PushPromise> addHeader(string headerName, string headerValue)
Adds the specified key/value pair as an HTTP header to the
PushPromise
.Parameter Name Data Type Default Value Description headerName string The header name
headerValue string The header value
-
<PushPromise> setHeader(string headerName, string headerValue)
Sets the value of a transport header in
PushPromise
.Parameter Name Data Type Default Value Description headerName string The header name
headerValue string The header value
-
<PushPromise> removeHeader(string headerName)
Removes a transport header from the
PushPromise
.Parameter Name Data Type Default Value Description headerName string The header name
-
<PushPromise> removeAllHeaders()
Removes all transport headers from the
PushPromise
. -
<PushPromise> getHeaderNames() returns (string[])
Gets all transport header names from the
PushPromise
.Return Type Description string[] An array of all transport header names
public type Request object
Represents an HTTP request.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
rawPath | string | Resource path of the request URL |
|
method | string | The HTTP request method |
|
httpVersion | string | The HTTP version supported by the client |
|
userAgent | string | The user-agent. This value is used when setting the |
|
extraPathInfo | string | Additional information associated with the URL provided by the client |
|
cacheControl | RequestCacheControl | The cache-control directives for the request. This needs to be explicitly initialized if intending on utilizing HTTP caching. |
-
<Request> setEntity(Entity entity)
Sets the provided
Entity
to the request.Parameter Name Data Type Default Value Description entity Entity The
Entity
to be set to the request -
<Request> getQueryParams() returns (map<string>)
Gets the query parameters of the request, as a map.
Return Type Description map<string> String map of query params
-
<Request> getMatrixParams(string path) returns (map)
Gets the matrix parameters of the request.
Parameter Name Data Type Default Value Description path string Path to the location of matrix parameters
Return Type Description map A map of matrix paramters which can be found for the given path
-
<Request> getEntity() returns (mimeEntity | error)
Gets the
Entity
associated with the request.Return Type Description mimeEntity | error The
Entity
of the request.EntityError
will be returned if entity construction fails -
<Request> hasHeader(string headerName) returns (boolean)
Checks whether the requested header key exists in the header map.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description boolean Returns true if the specified header key exists
-
<Request> getHeader(string headerName) returns (string)
Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string The first header value for the specified header name. Returns an empty string if the header does not exist
-
<Request> getHeaders(string headerName) returns (string[])
Gets all the header values to which the specified header key maps to.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string[] The header values the specified header key maps to
-
<Request> setHeader(string headerName, string headerValue)
Sets the specified header to the request. If a mapping already exists for the specified header key, the existing header value is replaced with the specfied header value.
Parameter Name Data Type Default Value Description headerName string The header name
headerValue string The header value
-
<Request> addHeader(string headerName, string headerValue)
Adds the specified header to the request. Existing header values are not replaced.
Parameter Name Data Type Default Value Description headerName string The header name
headerValue string The header value
-
<Request> removeHeader(string key)
Removes the specified header from the request.
Parameter Name Data Type Default Value Description key string The header name
-
<Request> removeAllHeaders()
Removes all the headers from the request.
-
<Request> getHeaderNames() returns (string[])
Gets all the names of the headers of the request.
Return Type Description string[] An array of all the header names
-
<Request> expects100Continue() returns (boolean)
Checks whether the client expects a
100-continue
response.Return Type Description boolean Returns true if the client expects a
100-continue
response -
<Request> setContentType(string contentType)
Sets the
content-type
header to the request.Parameter Name Data Type Default Value Description contentType string Content type value to be set as the
content-type
header -
<Request> getContentType() returns (string)
Gets the type of the payload of the request (i.e: the
content-type
header value).Return Type Description string Returns the
content-type
header value as a string -
<Request> getJsonPayload() returns (json | error)
Gets the request payload as a
json
.Return Type Description json | error The JSON representation of the message payload or
error
in case of errors -
<Request> getTextPayload() returns (string | error)
Gets the text payload from the request.
Return Type Description string | error The String representation of the message payload or
error
in case of errors -
<Request> getPayloadAsString() returns (string | error)
Gets the request payload as a
string
.Return Type Description string | error The string representation of the message payload or
error
in case of errors -
<Request> getXmlPayload() returns (xml | error)
Gets the request payload as an
xml
.Return Type Description xml | error The XML representation of the message payload or
error
in case of errors -
<Request> getByteChannel() returns (ioByteChannel | error)
Gets the request payload as a
ByteChannel
except in the case of multiparts. To retrieve multiparts, usegetBodyParts()
.Return Type Description ioByteChannel | error A byte channel from which the message payload can be read or
error
in case of errors -
<Request> getBinaryPayload() returns (blob | error)
Gets the request payload as a
blob
.Return Type Description blob | error The blob representation of the message payload or
error
in case of errors -
<Request> getFormParams() returns (map<string> | error)
Gets the form parameters from the HTTP request as a
map
.Return Type Description map<string> | error The map of form params or
error
in case of errors -
<Request> getBodyParts() returns (Entity[] | error)
Get multiparts from request.
Return Type Description Entity[] | error Returns the body parts as an array of entities or an
EntityError
if there were any errors in constructing the body parts from the request -
<Request> setJsonPayload(json payload)
Sets a
json
as the payload.Parameter Name Data Type Default Value Description payload json The
json
payload -
<Request> setXmlPayload(xml payload)
Sets an
xml
as the payload.Parameter Name Data Type Default Value Description payload xml The
xml
payload -
<Request> setTextPayload(string payload)
Sets a
string
as the payload.Parameter Name Data Type Default Value Description payload string The
string
payload -
<Request> setBinaryPayload(blob payload)
Sets a
blob
as the payload.Parameter Name Data Type Default Value Description payload blob The
blob
payload -
<Request> setBodyParts(Entity[] bodyParts)
Set multiparts as the payload.
Parameter Name Data Type Default Value Description bodyParts Entity[] The entities which make up the message body
-
<Request> setFileAsPayload(string filePath)
Sets the content of the specified file as the entity body of the request.
Parameter Name Data Type Default Value Description filePath string Path to the file to be set as the payload
-
<Request> setByteChannel(ByteChannel payload)
Sets a
ByteChannel
as the payload.Parameter Name Data Type Default Value Description payload ByteChannel A
ByteChannel
through which the message payload can be read -
<Request> setPayload(string | xml | json | blob | ioByteChannel | Entity[] payload)
Sets the request payload.
Parameter Name Data Type Default Value Description payload string | xml | json | blob | ioByteChannel | Entity[] Payload can be of type
string
,xml
,json
,blob
,ByteChannel
orEntity[]
(i.e: a set of body parts)
public type RequestCacheControl object
Cache control directives configuration for requests
Field Name | Data Type | Default Value | Description |
---|---|---|---|
noCache | boolean | false | Represents the no-cache directive |
noStore | boolean | false | Represents the no-store directive |
noTransform | boolean | true | Represents the no-transform directive |
onlyIfCached | boolean | false | Represents the only-if-cached directive |
maxAge | int | -1 | Represents the max-age directive |
maxStale | int | -1 | Represents the max-stale directive |
minFresh | int | -1 | Represents the min - fresh directive |
-
<RequestCacheControl> buildCacheControlDirectives() returns (string)
Build the cache control directives string from the current request cache control configurations
Return Type Description string
public type Response object
Represents an HTTP response.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
statusCode | int | 200 | The response status code |
reasonPhrase | string | The status code reason phrase |
|
server | string | The server header |
|
cacheControl | ResponseCacheControl | The cache-control directives for the response. This needs to be explicitly initialized if intending on utilizing HTTP caching. For incoming responses, this will already be populated if the response was sent with cache-control directives |
-
<Response> getEntity() returns (mimeEntity | error)
Gets the
Entity
associated with the response.Return Type Description mimeEntity | error The
Entity
of the response.EntityError
will be returned if entity construction fails -
<Response> getEntityWithoutBody() returns (Entity)
Gets the
Entity
from the response without the entity body.Return Type Description Entity The
Entity
of the response -
<Response> setEntity(Entity entity)
Sets the provided
Entity
to the response.Parameter Name Data Type Default Value Description entity Entity The
Entity
to be set to the response -
<Response> hasHeader(string headerName) returns (boolean)
Checks whether the requested header key exists in the header map.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description boolean Returns true if the specified header key exists
-
<Response> getHeader(string headerName) returns (string)
Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string The first header value for the specified header name. Returns an empty string if the header does not exist
-
<Response> addHeader(string headerName, string headerValue)
Adds the specified header to the response. Existing header values are not replaced.
Parameter Name Data Type Default Value Description headerName string The header name
headerValue string The header value
-
<Response> getHeaders(string headerName) returns (string[])
Gets all the header values to which the specified header key maps to.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string[] The header values the specified header key maps to
-
<Response> setHeader(string headerName, string headerValue)
Sets the specified header to the response. If a mapping already exists for the specified header key, the existing header value is replaced with the specfied header value.
Parameter Name Data Type Default Value Description headerName string The header name
headerValue string The header value
-
<Response> removeHeader(string key)
Removes the specified header from the response.
Parameter Name Data Type Default Value Description key string The header name
-
<Response> removeAllHeaders()
Removes all the headers from the response.
-
<Response> getHeaderNames() returns (string[])
Gets all the names of the headers of the response.
Return Type Description string[] An array of all the header names
-
<Response> setContentType(string contentType)
Sets the
content-type
header to the response.Parameter Name Data Type Default Value Description contentType string Content type value to be set as the
content-type
header -
<Response> getContentType() returns (string)
Gets the type of the payload of the response (i.e: the
content-type
header value).Return Type Description string Returns the
content-type
header value as a string -
<Response> getJsonPayload() returns (json | error)
Gets the response payload as a
json
.Return Type Description json | error The JSON representation of the message payload or
error
in case of errors -
<Response> getXmlPayload() returns (xml | error)
Gets the response payload as an
xml
.Return Type Description xml | error The XML representation of the message payload or
error
in case of errors -
<Response> getTextPayload() returns (string | error)
Get the text payload from the response.
Return Type Description string | error The string representation of the message payload or
error
in case of errors -
<Response> getPayloadAsString() returns (string | error)
Gets the response payload as a
string
.Return Type Description string | error The string representation of the message payload or
error
in case of errors -
<Response> getBinaryPayload() returns (blob | error)
Gets the response payload as a
blob
.Return Type Description blob | error The blob representation of the message payload or
error
in case of errors -
<Response> getByteChannel() returns (ioByteChannel | error)
Gets the response payload as a
ByteChannel
except in the case of multiparts. To retrieve multiparts, usegetBodyParts()
.Return Type Description ioByteChannel | error A byte channel from which the message payload can be read or
error
in case of errors -
<Response> getBodyParts() returns (Entity[] | error)
Get multiparts from response.
Return Type Description Entity[] | error Returns the body parts as an array of entities or an
EntityError
if there were any errors in constructing the body parts from the response -
<Response> setETag(json | xml | string | blob payload)
Sets the
etag
header for the given payload. The ETag is generated using a CRC32 hash function.Parameter Name Data Type Default Value Description payload json | xml | string | blob The payload for which the ETag should be set
-
<Response> setLastModified()
Sets the current time as the
last-modified
header. -
<Response> setJsonPayload(json payload)
Sets a
json
as the payload.Parameter Name Data Type Default Value Description payload json The
json
payload -
<Response> setXmlPayload(xml payload)
Sets an
xml
as the payloadParameter Name Data Type Default Value Description payload xml The
xml
payload -
<Response> setTextPayload(string payload)
Sets a
string
as the payload.Parameter Name Data Type Default Value Description payload string The
string
payload -
<Response> setBinaryPayload(blob payload)
Sets a
blob
as the payload.Parameter Name Data Type Default Value Description payload blob The
blob
payload -
<Response> setBodyParts(Entity[] bodyParts)
Set multiparts as the payload.
Parameter Name Data Type Default Value Description bodyParts Entity[] The entities which make up the message body
-
<Response> setFileAsPayload(string filePath)
Sets the content of the specified file as the entity body of the response.
Parameter Name Data Type Default Value Description filePath string Path to the file to be set as the payload
-
<Response> setByteChannel(ByteChannel payload)
Sets a
ByteChannel
as the payload.Parameter Name Data Type Default Value Description payload ByteChannel A
ByteChannel
through which the message payload can be read -
<Response> setPayload(string | xml | json | blob | ioByteChannel | Entity[] payload)
Sets the response payload.
Parameter Name Data Type Default Value Description payload string | xml | json | blob | ioByteChannel | Entity[] Payload can be of type
string
,xml
,json
,blob
,ByteChannel
orEntity[]
(i.e: a set of body parts)
public type ResponseCacheControl object
Cache control directives configuration for responses
Field Name | Data Type | Default Value | Description |
---|---|---|---|
mustRevalidate | boolean | false | Represents the must-revalidate directive |
noCache | boolean | false | Represents the no-cache directive |
noStore | boolean | false | Represents the no-store directive |
noTransform | boolean | true | Represents the no-transform directive |
isPrivate | boolean | false | Represents the private and public directives |
proxyRevalidate | boolean | false | Represents the proxy-revalidate directive |
maxAge | int | -1 | Represents the max-age directive |
sMaxAge | int | -1 | Represents the s-maxage directive |
noCacheFields | string[] | [] | Optional fields for no-cache directive. If sending any of the listed fields in a response, they must validated with the origin server. |
privateFields | string[] | [] | Optional fields for private directive. A cache can omit the fields specified and store the rest ofthe response. |
-
<ResponseCacheControl> buildCacheControlDirectives() returns (string)
Build the cache control directives string from the current response cache control configurations
Return Type Description string
public type RetryClient object
Represents an HTTP Retry client to be used with the HTTP client to provide retrying over HTTP requests.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
serviceUri | string |
|
|
config | ClientEndpointConfig |
|
|
retryConfig | RetryConfig |
|
|
httpClient | CallerActions |
|
-
<RetryClient> post(string path) returns (Response | HttpConnectorError)
The POST function implementation of the HTTP retry client. Protects the invocation of the POST function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
Return Type Description Response | HttpConnectorError -
<RetryClient> head(string path) returns (Response | HttpConnectorError)
The HEAD function implementation of the HTTP retry client. Protects the invocation of the HEAD function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
Return Type Description Response | HttpConnectorError -
<RetryClient> put(string path) returns (Response | HttpConnectorError)
The PUT function implementation of the HTTP retry client. Protects the invocation of the PUT function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
Return Type Description Response | HttpConnectorError -
<RetryClient> forward(string path, Request request) returns (Response | HttpConnectorError)
The FORWARD function implementation of the HTTP retry client. Protects the invocation of the FORWARD function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
request Request A request message.
Return Type Description Response | HttpConnectorError -
<RetryClient> execute(string httpVerb, string path, Request request) returns (Response | HttpConnectorError)
The EXECUTE function implementation of the HTTP retry client. Protects the invocation of the EXECUTE function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description httpVerb string HTTP verb to be used for the request.
path string Target service url.
request Request A request message.
Return Type Description Response | HttpConnectorError -
<RetryClient> patch(string path) returns (Response | HttpConnectorError)
The PATCH function implementation of the HTTP retry client. Protects the invocation of the PATCH function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
Return Type Description Response | HttpConnectorError -
<RetryClient> delete(string path) returns (Response | HttpConnectorError)
The DELETE function implementation of the HTTP retry client. Protects the invocation of the DELETE function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
Return Type Description Response | HttpConnectorError -
<RetryClient> get(string path) returns (Response | HttpConnectorError)
The GET function implementation of the HTTP retry client. Protects the invocation of the GET function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
Return Type Description Response | HttpConnectorError -
<RetryClient> options(string path) returns (Response | HttpConnectorError)
The OPTIONS function implementation of the HTTP retry client. Protects the invocation of the OPTIONS function attached to the underlying HTTP client.
Parameter Name Data Type Default Value Description path string Target service url.
Return Type Description Response | HttpConnectorError -
<RetryClient> submit(string httpVerb, string path, Request request) returns (HttpFuture | HttpConnectorError)
The SUBMIT function implementation of the HTTP retry client.
Parameter Name Data Type Default Value Description httpVerb string HTTP verb to be used for the request.
path string Target service url.
request Request A request message.
Return Type Description HttpFuture | HttpConnectorError -
<RetryClient> getResponse(HttpFuture httpFuture) returns (Response | HttpConnectorError)
The getResponse function implementation of the HTTP retry client.
Parameter Name Data Type Default Value Description httpFuture HttpFuture -The Future which relates to previous async invocation.
Return Type Description Response | HttpConnectorError -
<RetryClient> hasPromise(HttpFuture httpFuture) returns (boolean)
The hasPromise function implementation of the HTTP retry client.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation.
Return Type Description boolean -
<RetryClient> getNextPromise(HttpFuture httpFuture) returns (PushPromise | HttpConnectorError)
The getNextPromise function implementation of the HTTP retry client.
Parameter Name Data Type Default Value Description httpFuture HttpFuture The Future which relates to previous async invocation.
Return Type Description PushPromise | HttpConnectorError -
<RetryClient> getPromisedResponse(PushPromise promise) returns (Response | HttpConnectorError)
The getPromisedResponse function implementation of the HTTP retry client.
Parameter Name Data Type Default Value Description promise PushPromise The related Push Promise message.
Return Type Description Response | HttpConnectorError -
<RetryClient> rejectPromise(PushPromise promise)
The rejectPromise function implementation of the HTTP retry client.
Parameter Name Data Type Default Value Description promise PushPromise The Push Promise need to be rejected.
public type SecureListener object
Representation of an Secure Listener
Field Name | Data Type | Default Value | Description |
---|---|---|---|
config | SecureEndpointConfiguration | SecureEndpointConfiguration instance | |
httpListener | Listener | HTTP Listener instance |
-
<SecureListener> init(SecureEndpointConfiguration config)
Parameter Name Data Type Default Value Description config SecureEndpointConfiguration -
<SecureListener> initEndpoint() returns (error)
Gets called when the endpoint is being initialize during package init time
Return Type Description error Error occured during initialization -
<SecureListener> register(typedesc serviceType)
Gets called every time a service attaches itself to this endpoint. Also happens at package initialization.
Parameter Name Data Type Default Value Description serviceType typedesc The type of the service to be registered -
<SecureListener> start()
Starts the registered service
-
<SecureListener> getCallerActions() returns (Connection)
Returns the connector that client code uses
Return Type Description Connection The connector that client code uses -
<SecureListener> stop()
Stops the registered service
public type Service object
-
<Service> getEndpoint() returns (Listener)
Return Type Description Listener
public type WebSocketClient object
Represents a WebSocket client endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
id | string | The connection id |
|
negotiatedSubProtocol | string | The subprotocols negoriated with the server |
|
isSecure | boolean |
|
|
isOpen | boolean |
|
|
attributes | map | A map to store connection related attributes |
-
<WebSocketClient> init(WebSocketClientEndpointConfig config)
Gets called when the endpoint is being initialize during package init time.
Parameter Name Data Type Default Value Description config WebSocketClientEndpointConfig The
WebSocketClientEndpointConfig
of the endpoint -
<WebSocketClient> initEndpoint()
Native function that initializes the endpoint.
-
<WebSocketClient> register(typedesc serviceType)
Gets called every time a service attaches itself to this endpoint - also happens at package init time.
Parameter Name Data Type Default Value Description serviceType typedesc The service type
-
<WebSocketClient> getCallerActions() returns (WebSocketConnector)
Allows access to connector that the client endpoint uses.
Return Type Description WebSocketConnector The connector that client endpoint uses
-
<WebSocketClient> start()
Starts the registered service.
-
<WebSocketClient> stop()
Stops the registered service.
public type WebSocketClientService object
Represents the WebSocket client service.
-
<WebSocketClientService> getEndpoint() returns (WebSocketClient)
Return Type Description WebSocketClient
public type WebSocketConnector object
Represents a WebSocket connector in ballerina. This include all connector oriented operations.
-
<WebSocketConnector> pushText(string text) returns (WebSocketConnectorError | null)
Push text to the connection.
Parameter Name Data Type Default Value Description text string Text to be sent
Return Type Description WebSocketConnectorError | null WebSocketConnectorError
if an error occurs when sending -
<WebSocketConnector> pushBinary(blob data) returns (WebSocketConnectorError | null)
Push binary data to the connection.
Parameter Name Data Type Default Value Description data blob Binary data to be sent
Return Type Description WebSocketConnectorError | null WebSocketConnectorError
if an error occurs when sending -
<WebSocketConnector> ping(blob data) returns (WebSocketConnectorError | null)
Ping the connection.
Parameter Name Data Type Default Value Description data blob Binary data to be sent.
Return Type Description WebSocketConnectorError | null WebSocketConnectorError
if an error occurs when sending -
<WebSocketConnector> pong(blob data) returns (WebSocketConnectorError | null)
Send pong message to the connection.
Parameter Name Data Type Default Value Description data blob Binary data to be sent
Return Type Description WebSocketConnectorError | null WebSocketConnectorError
if an error occurs when sending -
<WebSocketConnector> close(int statusCode, string reason) returns (WebSocketConnectorError | null)
Close the connection.
Parameter Name Data Type Default Value Description statusCode int Status code for closing the connection
reason string Reason for closing the connection
Return Type Description WebSocketConnectorError | null WebSocketConnectorError
if an error occurs when sending -
<WebSocketConnector> ready() returns (WebSocketConnectorError | null)
Called when the endpoint is ready to receive messages. Can be called only once per endpoint. For the WebSocketListener can be called only in upgrade or onOpen resources.
Return Type Description WebSocketConnectorError | null WebSocketConnectorError
if an error occurs when sending
public type WebSocketListener object
Represents a WebSocket server endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
id | string | The connection id |
|
negotiatedSubProtocol | string | The subprotocols negoriated with the client |
|
isSecure | boolean |
|
|
isOpen | boolean |
|
|
attributes | map | A |
-
<WebSocketListener> init(ServiceEndpointConfiguration config)
Gets called when the endpoint is being initialize during package init time.
Parameter Name Data Type Default Value Description config ServiceEndpointConfiguration The
ServiceEndpointConfiguration
of the endpoint -
<WebSocketListener> register(typedesc serviceType)
Gets called every time a service attaches itself to this endpoint - also happens at package init time.
Parameter Name Data Type Default Value Description serviceType typedesc The service type
-
<WebSocketListener> start()
Starts the registered service.
-
<WebSocketListener> getCallerActions() returns (WebSocketConnector)
Allows access to connector that the listener endpoint uses.
Return Type Description WebSocketConnector The connector that listener endpoint uses
-
<WebSocketListener> stop()
Stops the registered service.
public type WebSocketService object
Represents the WebSocket client service.
-
<WebSocketService> getEndpoint() returns (WebSocketListener)
Return Type Description WebSocketListener