Envelope Types

These are the TypeScript interfaces for the message envelopes that make up Strata's wire protocol. For conceptual background on the protocol, see The Protocol.

All envelope types are exported from the main package:

import type {
    MessageEnvelope,
    RequestEnvelope,
    PostEnvelope,
    ResponseEnvelope,
    ResponseMessage,
} from '@strata-js/strata';

MessageEnvelope

The base interface shared by all envelope types.

interface MessageEnvelope<PayloadType = Record<string, unknown>>
{
    id : string;
    messageType : 'request' | 'response' | 'post';
    context : string;
    operation : string;
    timestamp : string;
    payload : PayloadType;
}

Field	Type	Description
id	string	Unique message identifier (nanoid, 20 chars).
messageType	string	Discriminator: 'request', 'response', or 'post'.
context	string	Target context name.
operation	string	Target operation name.
timestamp	string	ISO 8601 datetime.
payload	object	Application-specific data. Opaque to the framework.

RequestEnvelope

Sent by a client when it expects a response. Extends MessageEnvelope with messageType: 'request'.

interface RequestEnvelope<
    PayloadType = Record<string, unknown>,
    MetadataType = Record<string, unknown>,
> extends MessageEnvelope<PayloadType>
{
    messageType : 'request';
    responseQueue ?: string;
    timeout ?: number;
    metadata : MetadataType;
    auth ?: string;
    priorRequest ?: string;
    client ?: string;
    requestChain ?: string[];
}

Field	Type	Required	Description
responseQueue	string	no	Queue where the service should send the response. Set by the backend.
timeout	number	no	Milliseconds the client will wait. 0 or omitted uses service default.
metadata	object	yes	Additional metadata. Opaque to the framework.
auth	string	no	Authentication data (typically a JWT). Passed through, never inspected.
priorRequest	string	no	ID of the request that triggered this one (for tracing).
client	string	no	Human-readable client identifier.
requestChain	string[]	no	Chain of request IDs for distributed tracing.

PostEnvelope

Sent by a client when no response is needed. Extends MessageEnvelope with messageType: 'post'.

interface PostEnvelope<
    PayloadType = Record<string, unknown>,
    MetadataType = Record<string, unknown>,
> extends MessageEnvelope<PayloadType>
{
    messageType : 'post';
    metadata : MetadataType;
    auth ?: string;
    priorRequest ?: string;
    client ?: string;
    requestChain ?: string[];
}

Same fields as RequestEnvelope, minus responseQueue and timeout.

RequestOrPostEnvelope

Union type used internally when handling either type of incoming message.

type RequestOrPostEnvelope<
    P = Record<string, unknown>,
    M = Record<string, unknown>
> = RequestEnvelope<P, M> | PostEnvelope<P, M>;

ResponseEnvelope

Sent by a service back to the client after processing a request. Extends MessageEnvelope with messageType: 'response'.

interface ResponseEnvelope<PayloadType = Record<string, unknown>>
    extends MessageEnvelope<PayloadType>
{
    id : string;
    messageType : 'response';
    context : string;
    operation : string;
    timestamp : string;
    payload : PayloadType;
    status : 'succeeded' | 'failed' | 'pending';
    messages : ResponseMessage[];
    service : string;
}

Field	Type	Description
status	string	'succeeded', 'failed', or 'pending'.
messages	ResponseMessage[]	Array of structured messages generated during processing.
service	string	Human-readable service identifier (e.g. 'UserService v1.0').

ResponseMessage

Structured messages generated during request processing. Useful for returning warnings, informational messages, or detailed error information alongside the response payload.

interface ResponseMessage<DetailsType = Record<string, unknown>>
{
    severity : ResponseMessageSeverity;
    message : string;
    code ?: string;
    type ?: string;
    details ?: DetailsType;
    stack ?: string;
}

Field	Type	Required	Description
severity	string	yes	'error', 'warning', 'info', or 'debug'.
message	string	yes	Human-readable message text.
code	string	no	Machine-readable message code.
type	string	no	Message type name (typically the error class name).
details	object	no	Additional structured data.
stack	string	no	Stack trace, if applicable. Never expose to end users.

ResponseMessageSeverity

const ResponseMessageSeverity = [ 'error', 'warning', 'info', 'debug' ] as const;
type ResponseMessageSeverity = typeof ResponseMessageSeverity[number];

Command Types

Commands are a separate messaging mechanism from requests. They control service behavior at runtime.

ServiceCommand

interface ServiceCommand<Payload = Record<string, unknown>>
{
    id : string;
    command : ValidCommandName;
    payload ?: Payload;
}

ValidCommandName

type ValidCommandName = 'info' | 'concurrency' | 'shutdown' | 'toobusy';

ServiceCommandResponse

interface ServiceCommandResponse<Payload = Record<string, unknown>>
{
    id : string;
    payload ?: Payload;
}

Specific Command Types

// Info command -- the only command with a response
interface StrataInfoCommand extends ServiceCommand<undefined>
{
    command : 'info';
    responseChannel : string;
}

// Concurrency command
interface StrataConcurrencyCommand extends ServiceCommand<StrataConcurrencyCommandPayload>
{
    command : 'concurrency';
    payload : { concurrency : number };
}

// Shutdown command
interface StrataShutdownCommand extends ServiceCommand<StrataShutdownCommandPayload>
{
    command : 'shutdown';
    payload ?: { graceful ?: boolean; exitCode ?: number };
}

// TooBusy command
interface StrataToobusyCommand extends ServiceCommand<StrataTooBusyCommandPayload>
{
    command : 'toobusy';
    payload : TooBusyConfig;
}