Worker Socket Protocol

App workers talk to the Lombok platform over a single authenticated Socket.IO connection. Every platform capability a worker needs — emitting events, minting user tokens, signing storage URLs, running Docker jobs, managing tasks and triggers — is expressed as a typed request/response message over that socket.

This page is the reference for that message contract. It is derived directly from the schemas in @lombokapp/types (packages/types/src/app-socket-message-schemas.ts) and the worker SDK (packages/app-worker-sdk/src/app-worker-sdk.ts).

Most app developers do not send these messages by hand — the App Worker SDK exposes a typed method for each one. This reference documents the wire contract those methods implement.

Transport and framing

Aspect	Value
Protocol	Socket.IO (request/response via acknowledgement)
Direction	Worker → platform
Socket event	`APP_API`
Call style	`socket.timeout(ms).emitWithAck('APP_API', { name, data })`
Default timeout	`30000` ms, overridable per call via `{ timeoutMs }`

Every call sends a single request envelope and resolves with a single response envelope.

Request envelope

Every request is the same envelope, discriminated by name:

{
  name: AppSocketMessageName,
  data: unknown
}

data is validated against the schema registered for name.

Response envelope

Every response is a discriminated union of a success result or an error:

{ result: <result for this message> }
// or
{ error: AppSocketResponseError }

Error shape

AppSocketResponseError has this structure:

| Field | Type | Notes | | ---------- | -------- | --------------------------- | --------------------------- | | code | number | string | Machine-readable error code | | message | string | Human-readable message | | details? | object | Optional structured context |

Message catalog

There are 24 message names. They are grouped below by domain.

Events and logging

Message	SDK method
`EMIT_EVENT`	`emitEvent`
`SAVE_LOG_ENTRY`	`saveLogEntry`

EMIT_EVENT — emits an app-defined event into the platform event bus. The eventIdentifier uses the bare app-event format (^[a-z_]+$), not a core:-prefixed platform event name.

// request
{
  eventIdentifier: EventIdentifier,
  data: JsonObject,
  targetUserId?: uuid,
  targetLocation?: { folderId: string, objectKey?: string }
}
// result
{ success: boolean }

SAVE_LOG_ENTRY

// request
{
  message: string,
  level: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR',
  targetLocation?: { folderId: string, objectKey?: string },
  data?: JsonObject
}
// result
null

Content and storage

Message	SDK method
`GET_CONTENT_SIGNED_URLS`	`getContentSignedUrls`
`GET_METADATA_SIGNED_URLS`	`getMetadataSignedUrls`
`UPDATE_CONTENT_METADATA`	`updateContentMetadata`
`GET_APP_STORAGE_SIGNED_URLS`	`getAppStorageSignedUrls`

GET_CONTENT_SIGNED_URLS

// request: array of
{ folderId: string, objectKey: string, method: SignedURLsRequestMethod }
// result: array of
{ url: string, folderId: string, objectKey: string }

GET_METADATA_SIGNED_URLS

// request: array of
{
  folderId: string,
  objectKey: string,
  contentHash: string,
  metadataHash: string,
  method: SignedURLsRequestMethod
}
// result: array of
{ url: string, folderId: string, objectKey: string }

UPDATE_CONTENT_METADATA

// request: array of
{
  folderId: string,
  objectKey: string,
  hash: string,
  metadata: Record<string, MetadataEntry>
}
// result
null

GET_APP_STORAGE_SIGNED_URLS

// request: array of
{ objectKey: string, method: SignedURLsRequestMethod }
// result
string[]

Identity

Message	SDK method
`MINT_APP_USER_TOKEN`	`mintAppUserToken`

// request
{
  userId: uuid,
  platformAccess?: boolean,
  extra?: JsonObject
}
// result
{ accessToken: string, refreshToken: string }

Database

Message	SDK method
`GET_LATEST_DB_CREDENTIALS`	`getLatestDbCredentials`

// request
undefined
// result
{
  host: string,
  port: number,
  user: string,
  password: string,
  database: string,
  ssl: boolean
}

Query execution itself is not part of this socket contract. Workers use these credentials to connect directly to Postgres.

App settings

Message	SDK method
`GET_APP_CUSTOM_SETTINGS`	`getAppCustomSettings`
`PATCH_APP_CUSTOM_SETTINGS`	`patchAppCustomSettings`

// GET_APP_CUSTOM_SETTINGS
{ userId: string } -> { values: Record<string, unknown> }

// PATCH_APP_CUSTOM_SETTINGS
{ userId: string, values: Record<string, unknown> } -> { success: boolean }

Tasks

Message	SDK method
`GET_APP_TASK`	`getAppTask`
`TRIGGER_APP_TASK`	`triggerAppTask`
`REPORT_TASK_PROGRESS`	`reportTaskProgress`

GET_APP_TASK

{ taskId: uuid, targetUserId?: uuid } -> TaskDTO

TRIGGER_APP_TASK

{
  taskIdentifier: string,
  inputData: JsonObject,
  correlationKey?: string,
  outputLocation?: { folderId: string, prefix: string | null },
  dontStartBefore?: { timestamp: ISODateTime } | { delayMs: number },
  targetLocation?: { folderId: string, objectKey?: string },
  targetUserId?: uuid,
  onComplete?: TaskOnCompleteConfig[],
  onProgress?: TaskOnProgressConfig[],
  storageAccessPolicy?: StorageAccessPolicy
} -> { taskId: string }

REPORT_TASK_PROGRESS

{
  taskId: uuid,
  progressReport: {
    code?: string,
    details?: TaskProgressDetails,
    message?: TaskProgressMessage,
    timestamp?: string,
    executorMetadata?: ExecutorMetadata
  }
} -> { success: boolean }

Triggers

Message	SDK method
`REGISTER_APP_TRIGGER`	`registerAppTrigger`
`UNREGISTER_APP_TRIGGER`	`unregisterAppTrigger`
`LIST_APP_TRIGGERS`	`listAppTriggers`

// REGISTER_APP_TRIGGER
{ trigger: RegisterableTriggerConfig } -> { triggerId: string }

// UNREGISTER_APP_TRIGGER
{ triggerId: uuid } -> { success: boolean }

// LIST_APP_TRIGGERS
{ kind?: 'event' | 'schedule' } -> {
  triggers: {
    id: string,
    kind: 'event' | 'schedule',
    definition: RegisterableTriggerConfig
  }[]
}

Docker jobs

Message	SDK method
`EXECUTE_APP_DOCKER_JOB`	`executeAppDockerJob`
`EXECUTE_APP_DOCKER_JOB_ASYNC`	`executeAppDockerJobAsync`

Shared request shape:

{
  profileIdentifier: string,
  jobIdentifier: string,
  jobData: JsonObject,
  storageAccessPolicy?: StorageAccessPolicy,
  containerId?: string,
  targetUserId?: string
}

EXECUTE_APP_DOCKER_JOB waits for execution and returns one of the defined submit/execute outcomes. EXECUTE_APP_DOCKER_JOB_ASYNC returns once submission completes.

Docker containers

Message	SDK method
`DESTROY_APP_DOCKER_CONTAINERS`	`destroyAppDockerContainers`
`RESOLVE_APP_DOCKER_CONTAINER`	`resolveAppDockerContainer`
`INSPECT_APP_DOCKER_CONTAINER`	`inspectAppDockerContainer`
`START_APP_DOCKER_CONTAINER`	`startAppDockerContainer`

These cover destroy, resolve, inspect, and start operations for app-managed containers.

Bridge tunnels

Message	SDK method
`CREATE_BRIDGE_TUNNEL`	`createBridgeTunnel`
`DELETE_BRIDGE_TUNNEL`	`deleteBridgeTunnel`

CREATE_BRIDGE_TUNNEL opens a tunnel and returns session credentials and URLs. DELETE_BRIDGE_TUNNEL closes it.

Message ↔ SDK method index

Message name	SDK method	Domain
`EMIT_EVENT`	`emitEvent`	Events / logging
`SAVE_LOG_ENTRY`	`saveLogEntry`	Events / logging
`GET_CONTENT_SIGNED_URLS`	`getContentSignedUrls`	Content / storage
`GET_METADATA_SIGNED_URLS`	`getMetadataSignedUrls`	Content / storage
`UPDATE_CONTENT_METADATA`	`updateContentMetadata`	Content / storage
`GET_APP_STORAGE_SIGNED_URLS`	`getAppStorageSignedUrls`	Content / storage
`MINT_APP_USER_TOKEN`	`mintAppUserToken`	Identity
`GET_LATEST_DB_CREDENTIALS`	`getLatestDbCredentials`	Database
`GET_APP_CUSTOM_SETTINGS`	`getAppCustomSettings`	App settings
`PATCH_APP_CUSTOM_SETTINGS`	`patchAppCustomSettings`	App settings
`GET_APP_TASK`	`getAppTask`	Tasks
`TRIGGER_APP_TASK`	`triggerAppTask`	Tasks
`REPORT_TASK_PROGRESS`	`reportTaskProgress`	Tasks
`REGISTER_APP_TRIGGER`	`registerAppTrigger`	Triggers
`UNREGISTER_APP_TRIGGER`	`unregisterAppTrigger`	Triggers
`LIST_APP_TRIGGERS`	`listAppTriggers`	Triggers
`EXECUTE_APP_DOCKER_JOB`	`executeAppDockerJob`	Docker jobs
`EXECUTE_APP_DOCKER_JOB_ASYNC`	`executeAppDockerJobAsync`	Docker jobs
`DESTROY_APP_DOCKER_CONTAINERS`	`destroyAppDockerContainers`	Docker containers
`RESOLVE_APP_DOCKER_CONTAINER`	`resolveAppDockerContainer`	Docker containers
`INSPECT_APP_DOCKER_CONTAINER`	`inspectAppDockerContainer`	Docker containers
`START_APP_DOCKER_CONTAINER`	`startAppDockerContainer`	Docker containers
`CREATE_BRIDGE_TUNNEL`	`createBridgeTunnel`	Bridge tunnels
`DELETE_BRIDGE_TUNNEL`	`deleteBridgeTunnel`	Bridge tunnels

Notes

Referenced types such as TaskDTO, StorageAccessPolicy, RegisterableTriggerConfig, and progress/detail objects are defined elsewhere in @lombokapp/types and are intentionally summarized here.
The message set is fixed by the AppSocketMessage enum. Workers cannot invent new message names.