Module service_commons
commons/service_commons
commons/service_commons
Shared plumbing for the commons services. It declares no listeners, so importing it never starts a server.
| Module | Provides |
|---|---|
service_commons | newId() (ULID), epoch-millis time helpers, ErrorBody responses, ErrorInterceptor |
service_commons.auth | Authenticator (JWT via JWKS or cert, API key, trusted headers), AuthInterceptor, callerOf(ctx), scope checks, TicketStore for SSE |
service_commons.db | connect for H2, MySQL and PostgreSQL, migrate (versioned, per-dialect), atomic (transactions), ident/raw for prefixed table names, isDuplicateKey |
service_commons.sse | Hub: in-process fan-out by target key (user:tara, role:Finance), backlog replay, heartbeats |
service_commons.webhook | Webhooks: subscriptions per participant, a transactional outbox (enqueue joins the caller's transaction), HMAC-signed delivery with backoff, a claim step so nodes don't send twice, a retry job, delivery history; verify for receivers |
Auth settings mirror the workflow module's management.rest configurables.
Transactions go through atomic
Ballerina starts its transaction coordinator, an HTTP listener, once for each package that contains a
transaction block. Every start uses the same coordinatorPort, so the second start fails ("Address already in
use") and the program exits. The services therefore never write transaction themselves. They call
service_commons.db:atomic(work), so the only transaction block is in this package.
An application that embeds these services and also uses transaction blocks of its own will hit the same failure.
Route its transactions through atomic too.
work is an isolated closure. It may use self and final readonly values, so clone records with
cloneReadOnly() into final locals first. It commits when it returns a value and rolls back when it returns an
error.
Functions
alreadyExists
Builds a 409 Conflict with an error body.
Parameters
- message string - What conflicted
Return Type
- Conflict - The response
badRequest
function badRequest(string message) returns BadRequestBuilds a 400 Bad Request with an error body.
Parameters
- message string - What was wrong with the request
Return Type
- BadRequest - The response
forbidden
Builds a 403 Forbidden with an error body.
Parameters
- message string - Why the caller may not do this
Return Type
- Forbidden - The response
fromIso
Parses an RFC 3339 timestamp into epoch milliseconds.
Parameters
- timestamp string - The timestamp
newId
function newId() returns stringReturns a new ULID: 26 Crockford base32 characters that sort by creation time.
Return Type
- string - The new ID
notFound
Builds a 404 Not Found with an error body.
Parameters
- message string - What was not found
Return Type
- NotFound - The response
nowMillis
function nowMillis() returns intReturns the current time as epoch milliseconds, the timestamp format of every commons table.
Return Type
- int - Milliseconds since the Unix epoch
toIso
Formats epoch milliseconds as an RFC 3339 UTC timestamp.
Parameters
- millis int - Milliseconds since the Unix epoch
Return Type
- string - The timestamp, e.g.
2026-09-25T10:15:30.120Z
Classes
service_commons: ErrorInterceptor
Maps errors returned by resources and request binding to ErrorBody responses.
interceptResponseError
function interceptResponseError(error err) returns BadRequest|NotFound|InternalServerErrorParameters
- err error -
Records
service_commons: ErrorBody
Error body returned by every commons service.
Fields
- code string - Stable, machine-readable error code
- message string - Human-readable description
Import
import commons/service_commons;Other versions
0.1.0