Note: There is a newer version (1.0.1) of this package available. Click here to view docs for the latest version.

wso2/icp.runtime.bridge

0.3.0

Package Overview

The icp.runtime.bridge library is one of the external library packages, it provides internal support for exposing Ballerina runtime artifacts to the integration control plane.

Report Issues

To report bugs, request new features, start new discussions, view project boards, etc., go to the WSO2 Integrator repository

Useful Links

Chat live with us via our Discord server.
Post all technical questions on Stack Overflow with the #ballerina tag.

Functions

loadConfig

function loadConfig() returns IcpConfig|error

registerWorkflowIntegration

Isolated Function

function registerWorkflowIntegration(WorkflowMetadataProvider metadataProvider, TunneledCommandExecutor commandExecutor, WorkflowTaskQueueProvider? taskQueueProvider) returns boolean

Registers the integration's workflow runtime with this bridge. Called at module init by the compiler-plugin-generated glue; may also be called directly by advanced integrations that assemble their own metadata.

Parameters

metadataProvider WorkflowMetadataProvider - Supplies the metadata document for full heartbeats

commandExecutor TunneledCommandExecutor - Executes WORKFLOW_MGMT commands, typically an adapter over workflow.management:executeCommand

taskQueueProvider WorkflowTaskQueueProvider? (default ()) - Supplies the worker's Temporal task queue, reported beside capabilities; optional so older glue keeps binding

Return Type

boolean - true, so the generated glue can bind the call at module level

Classes

icp.runtime.bridge: HeartbeatJob

execute

function execute()

Executes the heartbeat job: one heartbeat round, plus bounded follow-up rounds while the server is actively tunneling work. A follow-up happens immediately after executing a tunneled command (its result may already have unblocked the next queued command) or after the server's nextHeartbeatInSeconds boost hint (sent while a user is actively working with workflow views). Follow-ups stop once the tick's real elapsed time — rounds and sleeps alike — would exceed one regular interval, so a tick never runs much past the next scheduled one, which then continues the boost. A tick that IS still running when the scheduler fires again (a slow command, a slow server) makes the new tick a no-op instead of a second concurrent round: the job's heartbeat bookkeeping fields are not synchronized, and overlapping rounds would race on them.

Clients

icp.runtime.bridge: IcpClient

ICP Client This client is responsible for communicating with the ICP server to send heartbeats and receive control commands

sendDeltaHeartbeat

Isolated FunctionRemote Function

function sendDeltaHeartbeat(DeltaHeartbeat deltaHeartbeat) returns HeartbeatResponse|error

Parameters

deltaHeartbeat DeltaHeartbeat -

sendCommandResult

Isolated FunctionRemote Function

function sendCommandResult(TunneledCommandResult result) returns error?

Parameters

result TunneledCommandResult -

sendHeartbeat

Isolated FunctionRemote Function

function sendHeartbeat(Heartbeat heartbeat) returns HeartbeatResponse|error

Parameters

heartbeat Heartbeat -

Enums

icp.runtime.bridge: ArtifactState

Members

ENABLED

DISABLED

icp.runtime.bridge: ArtifactType

Members

SERVICE

LISTENER

icp.runtime.bridge: ControlAction

Members

START

STOP

SET_LOGGER_LEVEL

WORKFLOW_MGMT

icp.runtime.bridge: ControlCommandStatus

Members

PENDING

SENT

ACKNOWLEDGED

FAILED

COMPLETED

icp.runtime.bridge: RuntimeStatus

Members

RUNNING

OFFLINE

icp.runtime.bridge: RuntimeType

Members

Configurables

icp.runtime.bridge: runtimeIdFile

string(default ".icp_runtime_id")

icp.runtime.bridge: serverUrl

string(default "https://localhost:9445")

icp.runtime.bridge: heartbeatInterval

int(default 10)

icp.runtime.bridge: cert

string(default "")

icp.runtime.bridge: enableSSL

boolean(default false)

icp.runtime.bridge: jwtIssuer

string(default "icp-runtime-jwt-issuer")

icp.runtime.bridge: jwtAudience

string|string[](default "icp-server")

icp.runtime.bridge: jwtExpiryTimeSeconds

decimal(default 3600)

icp.runtime.bridge: runtime

string?(default ())

icp.runtime.bridge: environment

string(default "Dev")

icp.runtime.bridge: integration

string(default "default_integration")

icp.runtime.bridge: project

string(default "default_project")

icp.runtime.bridge: secret

string(default ?)

icp.runtime.bridge: enableWorkflowManagement

boolean(default false)

Allow the ICP to tunnel workflow management commands to this runtime over the heartbeat channel. The commands are executed in-process by the workflow runtime — the integration exposes no management port and needs no API key.

icp.runtime.bridge: runtimeHostUrl

string(default "http://localhost")

icp.runtime.bridge: tunneledCommandConcurrency

int(default 4)

Records

icp.runtime.bridge: Artifact

Fields

name string -

icp.runtime.bridge: Artifacts

Fields

listeners? ListenerDetail[] -

services? ServiceDetail[] -

main? MainDetail -

icp.runtime.bridge: CommandIdentity

Closed record

The caller identity a tunneled command executes on behalf of. Same semantics as the management API's x-user-id / x-user-roles headers.

Fields

userId string?(default ()) - The user ID, or () when unknown

roles string[](default []) - The caller's roles; empty means "no roles"

icp.runtime.bridge: ControlCommand

Fields

commandId string -

runtimeId string -

targetArtifact Artifact -

action ControlAction -

issuedAt Utc -

status ControlCommandStatus -

payload? string -

icp.runtime.bridge: DeltaHeartbeat

Closed record

Fields

runtimeId string -

heartbeatVersion string(default HEARTBEAT_VERSION) -

runtimeHash string -

timestamp Utc -

icp.runtime.bridge: Heartbeat

Closed record

Fields

runtimeId string -

runtime? string -

runtimeType RuntimeType -

heartbeatVersion string(default HEARTBEAT_VERSION) -

status RuntimeStatus -

environment string(default environment) -

project string -

component string -

version? string -

nodeInfo Node -

artifacts Artifacts -

runtimeHash string -

timestamp Utc -

logLevels? map<Level> -

tryItHost? string -

openApiDefinitions? map<json> -

workflowMetadata? map<json> -

capabilities? string[] -

workflowTaskQueue? string -

icp.runtime.bridge: HeartbeatForHash

Closed record

Fields

runtimeId string -

runtime? string -

runtimeType RuntimeType -

heartbeatVersion string(default HEARTBEAT_VERSION) -

status RuntimeStatus -

environment string -

project string -

component string -

version? string -

nodeInfo Node -

artifacts Artifacts -

logLevels? map<Level> -

tryItHost? string -

icp.runtime.bridge: HeartbeatResponse

Fields

acknowledged boolean -

fullHeartbeatRequired? boolean -

commands ControlCommand[](default []) -

supportedHeartbeatFields? string[] -

nextHeartbeatInSeconds? int -

icp.runtime.bridge: IcpConfig

Closed record

Fields

serverUrl string -

cert string -

enableSSL boolean -

heartbeatInterval int -

icp.runtime.bridge: ListenerDetail

Fields

Fields Included from *Artifact

name string
anydata...

protocol? string -

package string -

state ArtifactState(default "enabled") -

icp.runtime.bridge: LoggerLevelPayload

Closed record

Fields

componentName string -

componentPackage? string -

logLevel Level -

icp.runtime.bridge: MainDetail

Fields

packageOrg string -

packageName string -

packageVersion string -

icp.runtime.bridge: Node

Fields

platformName string(default "ballerina") -

platformVersion? string -

platformHome? string -

ballerinaHome? string -

osName? string -

osVersion? string -

icp.runtime.bridge: RequestLimit

Fields

maxUriLength int -

maxHeaderSize int -

maxEntityBodySize int -

icp.runtime.bridge: Resource

Fields

methods string[] -

url string -

icp.runtime.bridge: ServiceDetail

Fields

Fields Included from *Artifact

name string
anydata...

basePath string? -

package string -

listeners Artifact[] -

resources Resource[] -

state ArtifactState(default "enabled") -

icp.runtime.bridge: TunneledCommandPayload

Closed record

The JSON carried in a tunneled control command's payload.

Fields

commandId string - Correlation ID; the result is posted back under this ID

operation string - Dot-qualified operation name (e.g. humanTasks.complete)

params map<json>(default {}) - Operation parameters, keyed like the management API's query/path/body

identity CommandIdentity(default {}) - The end user the ICP executes this on behalf of

deadline? string - ISO-8601 instant after which the command is dropped unexecuted

icp.runtime.bridge: TunneledCommandResult

Closed record

The outcome of a tunneled command, posted to POST /icp/commandResult.

Fields

runtimeId string - This runtime's ID

commandId string - The command's correlation ID

status string - COMPLETED when the operation executed (regardless of its HTTP-level outcome), FAILED when it could not be executed at all

httpStatus int - The status code the corresponding management API would have returned

body json - The response body, byte-identical to the management API's

Union types

icp.runtime.bridge: ArtifactDetail

ServiceDetail|ListenerDetail|MainDetail

ArtifactDetail

Function types

icp.runtime.bridge: WorkflowMetadataProvider

function() returns (map<json>|error)

WorkflowMetadataProvider

Supplies the workflow metadata document to publish in full heartbeats. Typically an adapter over workflow.management:getWorkflowMetadata.

icp.runtime.bridge: WorkflowTaskQueueProvider

function() returns (string?)

WorkflowTaskQueueProvider

Supplies the Temporal task queue the integration's workflow worker serves, or nil before the worker has registered. Typically an adapter over workflow.management:getWorkflowTaskQueue. Read each heartbeat round: a queue known only after startup promotes the next round to a full heartbeat, which publishes it.

icp.runtime.bridge: TunneledCommandExecutor

function(map<json>) returns (map<json>|error)

TunneledCommandExecutor

Executes one tunneled command's operation. Takes the operation request ({operation, params, identity}) and returns {httpStatus, body} exactly as the corresponding management API would have responded.

Import

import wso2/icp.runtime.bridge;

Other versions

1.0.1 1.0.0

0.3.0

0.2.0 0.1.9

Metadata

Released date: 11 days ago

Version: 0.3.0

License: Apache-2.0

Compatibility

Platform: java21

Ballerina version: 2201.13.2

GraalVM compatible: Yes

Pull count

Total: 1260

Current verison: 6

Weekly downloads

Source repository

Dependencies

ballerina/uuid/1.10.0 ballerina/file/1.12.0 ballerina/jwt/2.15.1

Cookie policy

Delete policy

functions

classes

clients

enums

records

unionTypes

functionTypes

wso2/icp.runtime.bridge

Package Overview

Report Issues

Useful Links

Functions

loadConfig

registerWorkflowIntegration

Parameters

Return Type

Classes

icp.runtime.bridge: HeartbeatJob

execute

Clients

icp.runtime.bridge: IcpClient

sendDeltaHeartbeat

Parameters

sendCommandResult

Parameters

sendHeartbeat

Parameters

Enums

icp.runtime.bridge: ArtifactState

Members

icp.runtime.bridge: ArtifactType

Members

icp.runtime.bridge: ControlAction

Members

icp.runtime.bridge: ControlCommandStatus

Members

icp.runtime.bridge: RuntimeStatus

Members

icp.runtime.bridge: RuntimeType

Members

Configurables

icp.runtime.bridge: runtimeIdFile

icp.runtime.bridge: serverUrl

icp.runtime.bridge: heartbeatInterval

icp.runtime.bridge: cert

icp.runtime.bridge: enableSSL

icp.runtime.bridge: jwtIssuer

icp.runtime.bridge: jwtAudience

icp.runtime.bridge: jwtExpiryTimeSeconds

icp.runtime.bridge: runtime

icp.runtime.bridge: environment

icp.runtime.bridge: integration

icp.runtime.bridge: project

icp.runtime.bridge: secret

icp.runtime.bridge: enableWorkflowManagement

icp.runtime.bridge: runtimeHostUrl

icp.runtime.bridge: tunneledCommandConcurrency

Records

icp.runtime.bridge: Artifact

Fields

icp.runtime.bridge: Artifacts

Fields

icp.runtime.bridge: CommandIdentity

Fields

icp.runtime.bridge: ControlCommand

Fields

icp.runtime.bridge: DeltaHeartbeat

Fields

icp.runtime.bridge: Heartbeat

Fields

icp.runtime.bridge: HeartbeatForHash

Fields

icp.runtime.bridge: HeartbeatResponse

Fields

icp.runtime.bridge: IcpConfig

Fields

icp.runtime.bridge: ListenerDetail

Fields

icp.runtime.bridge: LoggerLevelPayload

Fields