DominScript — tcpserver

63 functionsnamespace tcpserversource plugins/tcp_server/TcpServerPlugin.c

Introduction

The tcpserver plugin is a complete callback-based TCP package: an `Open` call opens a loopback TCP server (incoming connections are dispatched to a callback), and the SAME plugin can also act as a client — it can send a request to its own (or another) listener via `RequestText`/`RequestBlob` (synchronous) or `BeginTextRequest`/`BeginBlobRequest` (asynchronous) calls. The plugin supports the full asyncmeta vocabulary (Capabilities = 4095 = ProfileRouteService), and every job-level query has two names: the native `Request*` and the asyncmeta-compatible `Job*` synonym.

Server + client in one

This plugin is both a TCP server AND a TCP client. `Open(callback, timeoutMs)` opens a loopback TCP port and dispatches the RAW bytes of every incoming connection to the callback on a background thread. The callback signature is `callback i32 NAME(ref blob $Request)` (see the extended forms below for the peer's address and certificate); the callback may modify the request blob in place, and the modified bytes become the TCP response. Meanwhile, `RequestText(listenerId, text, timeoutMs)` synchronously and `BeginTextRequest(listenerId, text, timeoutMs)` asynchronously open a TCP connection to the listener's port, send the text/blob, and return the response (or an asynchronous requestId).

Peer metadata: the extended callback forms

The handler may declare extra parameters, and the host fills them in with the peer's identity. Three forms are accepted; pick the shortest one that covers what you need:

callback i32 NAME(ref blob $Request) — payload only.
callback i32 NAME(ref blob $Request, string $PeerHost, i32 $PeerPort) — plus the client's address and port.
callback i32 NAME(ref blob $Request, string $PeerHost, i32 $PeerPort, string $PeerCertSubject) — plus the client certificate's subject when the connection is mTLS-verified. It is an empty string when there is no TLS, or when an optional-mode client presented no certificate.

The same forms work on the TCP, HTTP and UDP callback families, so a handler moves between transports unchanged.

What is the client side for?

The `RequestText` / `Begin*Request` families exist primarily for TESTING: you call your own server with them to confirm the callback handles requests correctly. The loopback TCP channel has minimal overhead and works like a locally simulated incoming connection. They can also reach other loopback servers (e.g. another tcp_server listener, or another local TCP service).

Relationship to asyncmeta

The plugin is fully built on the asyncmeta constants. `Capabilities()` returns exactly the `asyncmeta.ProfileRouteService()` bitmask (=4095) — the entire vocabulary supported. `RouteState` returns `asyncmeta.RouteStateOpen` (=1) / `RouteStateClosed` (=0); `RouteMeta(listenerId, key)` knows the `asyncmeta.RouteMeta*` keys; `JobMeta(requestId, key)` knows the `asyncmeta.JobMeta*` keys.

Request* / Job* synonym pairs

Job-level (i.e., asynchronous request) query functions all exist under two names. `Request*` is the native, descriptive name (paints a “request”, HTTP-like image); `Job*` is the asyncmeta-vocabulary name. The two names map to the EXACT same handler — pick stylistically. Examples: `RequestPhase` ↔︎ `Phase`, `RequestStatus` ↔︎ `Status`, `RequestError` ↔︎ `ErrorText`, `RequestStatusText` ↔︎ `StatusText`, `RequestInfo` ↔︎ `JobInfo`, `RequestRoute` ↔︎ `JobRoute`, `RequestTimeout` ↔︎ `JobTimeout`, `RequestKnown` ↔︎ `JobKnown`, `RequestMeta` ↔︎ `JobMeta`, `RequestHasBlobResult` ↔︎ `JobHasBlobResult`, `RequestBlobResultSize` ↔︎ `JobBlobResultSize`.

Optional TLS layer

`EnableTls(listenerId, certFile, keyFile)` activates TLS on the listener: every subsequent incoming connection is wrapped in TLS by the tls plugin's provider. The listener itself does NOT link OpenSSL — that is resolved at runtime via the tls plugin. On a platform that doesn't support TLS (e.g. Windows pre-bundle), EnableTls returns a clean error and the listener keeps serving plaintext. TLS activation is IDEMPOTENT: calling it again with the same files just returns 0.

Sync vs async request

`RequestText(listenerId, text, timeoutMs)` and `RequestBlob(listenerId, blob, timeoutMs)` are SYNCHRONOUS: the call BLOCKS until the TCP connection is established, the request is sent, and the response arrives. `BeginTextRequest`/`BeginBlobRequest` are ASYNCHRONOUS: they return immediately with a requestId, and a background thread handles the connect/send/wait. Async jobs are managed with `WaitComplete(requestId, timeoutMs)`, `TakeTextResponse(requestId)`, and `TakeBlob(requestId)`.

Loading the plugin

plugin "builtin:print";
plugin "../plugins/async_meta/AsyncMetaPlugin";
plugin
"../plugins/tcp_server/TcpServerPlugin";

A typical flow — synchronous echo on loopback

callback i32 Echo(ref blob $Request)
{
    // the callback may modify the request bytes in place;
    // these become the TCP response bytes
    return(1);
}
i32 main()
{
    i64 $lid;
    string $resp[64];
    $lid = tcpserver.Open("Echo", 5000);
    $resp = tcpserver.RequestText($lid, "PING", 5000);
    // ... process the response ...
    tcpserver.Close($lid);
    return(0);
}

A typical flow — asynchronous request with WaitComplete + TakeTextResponse

i64 $lid;
i64 $jobId;
string $resp[64];
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
// ... the script does other things ...
tcpserver.WaitComplete($jobId, 5000);
if (tcpserver.Status($jobId) == 0)
{
    $resp = tcpserver.TakeTextResponse($jobId);
    // ... processing ...
}
tcpserver.Close($lid);

What to know about every function (the basics)

Capabilities is always ProfileRouteService = 4095 (every asyncmeta bit).
Open binds to loopback (127.0.0.1) on an OS-picked port (query with Port).
The `Request*` and `Job*` families are SYNONYMS — exactly the same handler. Stylistic choice for code style.
RequestText/RequestBlob are synchronous; BeginTextRequest/BeginBlobRequest are asynchronous.
WaitComplete takes a requestId (NOT listenerId), and does NOT destroy the request.
TakeTextResponse and TakeBlob destroy the request; the requestId is invalid afterward.
EnableTls is idempotent — calling it again with the same files just returns 0.
RouteClose and Close map to the same handler: close the listener, return the canceled queued requests count.
RouteCloseAccepted is a LATCH — once it's 1 it never resets.
An error (stopping the script) is caused by a wrong argument count or type, an out-of-range timeoutMs, an invalid listenerId/requestId, a closed plugin, TCP connect failure, and embedded NUL byte in a text response.

How to read the signatures

callbackName is the script-level callback name (`callback i32 NAME(ref blob $X)`). timeoutMs is the callback run-time (Open) or request I/O (Request*, Begin*) max in ms; -1 = infinite. listenerId is the positive id given by Open. requestId is the positive id given by Begin*. metaKey is one of the asyncmeta.RouteMeta* or JobMeta* values. The type after the -> arrow is the return type.

Lifecycle and TLS

Opening the listener on a loopback TCP port, optional TLS activation, and plugin shutdown.

tcpserver.Capabilities

tcpserver.Capabilities() -> int

Returns the plugin's capability bitmask matching the asyncmeta constants.

Parameters

This function takes no arguments.

Return value

asyncmeta.ProfileRouteService (=4095): every asyncmeta bit (the entire vocabulary supported).

Example

printf("%d\n", tcpserver.Capabilities());
printf("%d\n", (tcpserver.Capabilities() ==
asyncmeta.ProfileRouteService()));

Output after running

4095
1

When to use

For backend capability checking with the Supports* helpers. tcp_server supports the FULL vocabulary (like bus) — the Supports* helpers return 1 for everything.

tcpserver.Open

tcpserver.Open(callbackName, timeoutMs) -> int

Opens a TCP listener on loopback IP and dispatches every incoming connection to the callback via a background thread.

Parameters

Parameter	Type	Description
callbackName	string	The script-level callback name to call. Signature: `callback i32 NAME(ref blob $X)`.
timeoutMs	int	The callback run-time limit in ms. -1 = infinite; otherwise 0..2147483647.

Return value

The listenerId (positive i64). A bad argument, bind failure, or thread startup failure raises a runtime error.

Example

callback i32 Echo(ref blob $X) { return(1); }
i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", ($lid > 0));

Output after running

When to use

For starting a local TCP service (debug server, local RPC, tested protocol). The port is OS-picked; query it with Port($lid). The callback receives RAW TCP bytes — any text or binary protocol is freely implementable.

tcpserver.SetClientCa

tcpserver.SetClientCa(listenerId, caFile, mode) -> 0

Turns on mTLS for this listener: requires (mode 2) or accepts (mode 1) a client certificate that chains to caFile on every TLS connection it accepts. The listener's mTLS shape is therefore Open + SetClientCa + EnableTls. With mTLS on, the 4-parameter callback form receives the verified client certificate's subject.

Parameters

Parameter	Type	Description
listenerId	int	The listener id returned by Open.
caFile	string	Path to the CA bundle (PEM) that client certificates are verified against.
mode	int	1 = optional (accept a certificate if offered), 2 = required (the handshake fails without a valid one).

Return value

Returns 0 on success; raises a runtime error on a bad argument, an unknown listener, a missing mTLS-capable TLS provider, or when TLS is already enabled.

Order matters

Call it BEFORE EnableTls / OpenTls. Calling it afterwards is a runtime error by design — otherwise connections accepted in between would run unverified, leaving an unchecked window.

tcpserver.EnableTls

tcpserver.EnableTls(listenerId, certFile, keyFile) -> int

Activates TLS on the listener: every subsequent connection is wrapped in TLS by the tls plugin's provider.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.
certFile	string	The server certificate path (PEM).
keyFile	string	The private key path (PEM).

Return value

0 (success). Idempotent: calling it again with the same files just returns 0. If TLS is not supported on the platform, a clean runtime error.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
// tcpserver.EnableTls($lid, "server.crt", "server.key");
print.Line($"ok");

Output after running

ok

When to use

For a secure local service with a TLS layer. The listener itself does not link OpenSSL — it relies on the tls plugin's provider at runtime. The probe didn't activate TLS (we only document the verb's presence).

tcpserver.OpenCount

tcpserver.OpenCount() -> int

Returns the count of currently open listeners (plugin-wide, global view).

Parameters

This function takes no arguments.

Return value

The number of open listeners (0 if none).

Example

printf("%d\n", tcpserver.OpenCount());
i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.OpenCount());

Output after running

0
1

When to use

For resource control and diagnostics. If it does not return to 0 after Close calls, that signals a resource leak.

tcpserver.Close

tcpserver.Close(listenerId) -> int

Closes the given listener: stops the accept thread, shuts down the socket, releases resources.

Parameters

Parameter	Type	Description
listenerId	int	The listener id from Open.

Return value

The count of queued requests canceled by the close. Typically 0 (clean close with nothing pending).

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.Close($lid));

Output after running

When to use

For clean listener shutdown. Close waits for in-progress callbacks to finish. If you called RouteClose first, Close returns 0 (listener no longer active).

Listener-level state

Current state of the listener: bound port, “open/closed” state, callback name, timeout, full diagnostic text. Route* names are equivalent to the State*/Info names.

tcpserver.Port

tcpserver.Port(listenerId) -> int

Returns the listener's actual, bound TCP port.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The port (1..65535).

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", (tcpserver.Port($lid) > 0));

Output after running

When to use

For querying the OS-picked port. RequestText/Blob and BeginTextRequest/BeginBlobRequest use this port automatically via the listenerId.

tcpserver.State

tcpserver.State(listenerId) -> int

Returns the listener's state using the asyncmeta route-state constants.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

asyncmeta.RouteStateOpen (=1) or RouteStateClosed (=0).

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.State($lid));

Output after running

When to use

For programmatic state checking. Shared vocabulary with the callback_* family.

tcpserver.RouteState

tcpserver.RouteState(listenerId) -> int

Synonym of State — under the asyncmeta vocabulary.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

asyncmeta.RouteStateOpen (=1) or RouteStateClosed (=0).

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteState($lid));

Output after running

When to use

For asyncmeta-compatible code.

tcpserver.StateText

tcpserver.StateText(listenerId) -> string

The state as text.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

“open” or “closed”.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
print.Line(tcpserver.StateText($lid));

Output after running

open

When to use

For logging or UI display.

tcpserver.RouteStateText

tcpserver.RouteStateText(listenerId) -> string

Synonym of StateText.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

“open” or “closed”.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
print.Line(tcpserver.RouteStateText($lid));

Output after running

open

When to use

For logging, under the asyncmeta vocabulary.

tcpserver.RouteCallback

tcpserver.RouteCallback(listenerId) -> string

Returns the callback name passed at Open.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The callback name as text.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
print.Line(tcpserver.RouteCallback($lid));

Output after running

Echo

When to use

For reflective queries and diagnostics.

tcpserver.RouteTimeout

tcpserver.RouteTimeout(listenerId) -> int

Returns the timeout value passed at Open, in ms.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The timeoutMs value; -1 for infinite.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteTimeout($lid));

Output after running

When to use

Reflective query of listener configuration.

tcpserver.RouteKnown

tcpserver.RouteKnown(listenerId) -> int

Tells whether the listenerId is known to the plugin.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

1 if known (open); 0 if not.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteKnown($lid));

Output after running

When to use

Defensive check.

tcpserver.RouteMeta

tcpserver.RouteMeta(listenerId, metaKey) -> int

Returns a specific meta field of the listener by asyncmeta.RouteMeta* keys.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.
metaKey	int	An asyncmeta.RouteMeta* value (State, Timeout, Pending, Queued, Running, Drained, Known, CloseAccepted, ClosedQueued).

Return value

The value for the field.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteMeta($lid,
asyncmeta.RouteMetaState()));
printf("%d\n", tcpserver.RouteMeta($lid,
asyncmeta.RouteMetaDrained()));

Output after running

1
1

When to use

Uniform asyncmeta query — for portable multi-backend code.

tcpserver.Info

tcpserver.Info(listenerId) -> string

Returns the listener's aggregated key=value diagnostic state as a string.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

A space-separated key=value list.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", (str.Len(tcpserver.Info($lid)) > 0));

Output after running

When to use

Detailed diagnostics in a single call.

tcpserver.RouteInfo

tcpserver.RouteInfo(listenerId) -> string

Synonym of Info — key=value diagnostic state.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

A space-separated key=value list.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", (str.Len(tcpserver.RouteInfo($lid)) > 0));

Output after running

When to use

For logging, under the asyncmeta vocabulary.

Listener-level traffic

Listener traffic metrics: active, pending, queued, running connections; drain state and blocking wait. Route* names are synonyms here too.

tcpserver.Pending

tcpserver.Pending(listenerId) -> int

Returns the number of pending (not yet started) requests.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The number of pending requests.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.Pending($lid));

Output after running

When to use

Early signal of congestion.

tcpserver.RoutePending

tcpserver.RoutePending(listenerId) -> int

Synonym of Pending.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The number of pending requests.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RoutePending($lid));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.Queued

tcpserver.Queued(listenerId) -> int

Returns the number of queued requests.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The number of queued requests.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.Queued($lid));

Output after running

When to use

For monitoring the internal queue length.

tcpserver.RouteQueued

tcpserver.RouteQueued(listenerId) -> int

Synonym of Queued.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The number of queued requests.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteQueued($lid));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.Running

tcpserver.Running(listenerId) -> int

Returns the number of currently running requests.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The number of running requests.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.Running($lid));

Output after running

When to use

For monitoring parallelism.

tcpserver.RouteRunning

tcpserver.RouteRunning(listenerId) -> int

Synonym of Running.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The number of running requests.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteRunning($lid));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.Active

tcpserver.Active(listenerId) -> int

Returns the number of currently active connections.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The number of active connections.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.Active($lid));

Output after running

When to use

For monitoring current server load.

tcpserver.Drained

tcpserver.Drained(listenerId) -> int

Tells whether the listener is drained (pending = queued = running = active = 0).

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

1 if drained; 0 if something is in progress.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.Drained($lid));

Output after running

When to use

Before clean shutdown: ensure Drained=1 before calling Close.

tcpserver.RouteDrained

tcpserver.RouteDrained(listenerId) -> int

Synonym of Drained.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

1 if drained; 0 if not.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteDrained($lid));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.WaitDrained

tcpserver.WaitDrained(listenerId, timeoutMs) -> int

Blocks until the listener is drained, or timeoutMs expires.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.
timeoutMs	int	Max wait in ms; -1 = infinite.

Return value

1 if drain occurred before timeoutMs expired; 0 if it expired.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.WaitDrained($lid, 50));

Output after running

When to use

In the two-step shutdown pattern: AFTER RouteClose, wait for drain.

tcpserver.WaitRouteDrained

tcpserver.WaitRouteDrained(listenerId, timeoutMs) -> int

Synonym of WaitDrained.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.
timeoutMs	int	Max wait in ms.

Return value

1 if drain occurred; 0 if expired.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.WaitRouteDrained($lid, 50));

Output after running

When to use

Under the asyncmeta vocabulary.

Request sending (client side)

Sending a TCP request to a listener's port (typically to test your own listener). Request* is synchronous, Begin* is asynchronous.

tcpserver.RequestText

tcpserver.RequestText(listenerId, text, timeoutMs) -> string

Sends a synchronous TCP request to the listener's port and returns the response text.

Parameters

Parameter	Type	Description
listenerId	int	The target listener id.
text	string	The text to send (UTF-8 or ASCII; the response MUST NOT contain NUL bytes).
timeoutMs	int	Max time for the entire connection (connect + send + receive) in ms.

Return value

The response text. If the response contains a NUL byte, a runtime error.

Example

i64 $lid;
string $resp[64];
$lid = tcpserver.Open("Echo", 5000);
$resp = tcpserver.RequestText($lid, "PING", 5000);
printf("%d\n", str.Len($resp));

Output after running

When to use

For testing your own callback: send a specific request and check the response. A simple, synchronous pattern — if you need async, use BeginTextRequest.

tcpserver.RequestBlob

tcpserver.RequestBlob(listenerId, request, timeoutMs) ->
blob

Sends a synchronous TCP request with a blob to the listener's port and returns the response blob.

Parameters

Parameter	Type	Description
listenerId	int	The target listener id.
request	blob	The binary data to send.
timeoutMs	int	Max time for the entire connection in ms.

Return value

The response blob (the callback-modified bytes). May be empty if the callback didn't write anything.

Example

i64 $lid;
blob $req[3];
blob $resp[16];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$lid = tcpserver.Open("Echo", 5000);
$resp = tcpserver.RequestBlob($lid, $req, 5000);
printf("%d\n", $resp.Length);

Output after running

When to use

For binary protocols. NUL bytes are allowed (only RequestText restricts them).

tcpserver.BeginTextRequest

tcpserver.BeginTextRequest(listenerId, text, timeoutMs) ->
int

Starts an asynchronous TCP request: the background thread connects, sends, and waits — the call returns immediately with a requestId.

Parameters

Parameter	Type	Description
listenerId	int	The target listener id.
text	string	The text to send.
timeoutMs	int	Max I/O time in ms.

Return value

The requestId (positive i64).

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", ($jobId > 0));

Output after running

When to use

For an async testing pattern: start a request, do other things, then WaitComplete + TakeTextResponse.

tcpserver.BeginBlobRequest

tcpserver.BeginBlobRequest(listenerId, request, timeoutMs) ->
int

Starts an asynchronous TCP request with a blob payload.

Parameters

Parameter	Type	Description
listenerId	int	The target listener id.
request	blob	The binary data to send.
timeoutMs	int	Max I/O time in ms.

Return value

The requestId (positive i64).

Example

i64 $lid;
i64 $jobId;
blob $req[3];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginBlobRequest($lid, $req, 5000);
printf("%d\n", ($jobId > 0));

Output after running

When to use

For async binary requests. Take the response with TakeBlob after WaitComplete.

Wait and response take

Waiting for an async request to complete and taking the response (text or blob).

tcpserver.WaitComplete

tcpserver.WaitComplete(requestId, timeoutMs) -> int

Blocks until the request completes, but does NOT destroy it — status and result are queryable afterward.

Parameters

Parameter	Type	Description
requestId	int	The requestId from Begin*.
timeoutMs	int	Max wait in ms; -1 = infinite.

Return value

1 if the request completed; 0 if the timeout expired.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", tcpserver.WaitComplete($jobId, 5000));

Output after running

When to use

First step of the async two-step pattern: wait for completion, verify success via Status / RequestStatus, then TakeTextResponse / TakeBlob the response.

tcpserver.TakeTextResponse

tcpserver.TakeTextResponse(requestId) -> string

Returns the text response of a completed request, and destroys the request.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The response text. If the request has not completed, a runtime error. If it contains a NUL byte, a runtime error.

Example

i64 $lid;
i64 $jobId;
string $resp[64];
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
$resp = tcpserver.TakeTextResponse($jobId);
printf("%d\n", str.Len($resp));

Output after running

When to use

For a text response. If the callback didn't write anything, the response is an empty string. For binary, use TakeBlob.

tcpserver.TakeBlob

tcpserver.TakeBlob(requestId) -> blob

Returns the blob response of a completed request, and destroys the request.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The response blob.

Example

i64 $lid;
i64 $jobId;
blob $req[3];
blob $resp[16];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginBlobRequest($lid, $req, 5000);
tcpserver.WaitComplete($jobId, 5000);
$resp = tcpserver.TakeBlob($jobId);
printf("%d\n", $resp.Length);

Output after running

When to use

For a binary response (may contain NUL bytes). The callback may modify the request bytes in place — these become the response.

Request-level state and metadata

Current state (phase, status, error) and metadata of an async request. Request* and Job* names are SYNONYMS — exactly the same handler, just stylistically interchangeable.

tcpserver.RequestPhase

tcpserver.RequestPhase(requestId) -> int

Returns the request phase from the asyncmeta.Phase* constants.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

asyncmeta.PhaseQueued (=0), PhaseRunning (=1), or PhaseCompleted (=2).

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.RequestPhase($jobId));

Output after running

When to use

For programmatic phase checks. Synonym of Phase.

tcpserver.Phase

tcpserver.Phase(requestId) -> int

Synonym of RequestPhase — under the asyncmeta vocabulary.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

asyncmeta.PhaseQueued / PhaseRunning / PhaseCompleted.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.Phase($jobId));

Output after running

When to use

For asyncmeta-compatible code.

tcpserver.RequestPhaseText

tcpserver.RequestPhaseText(requestId) -> string

The phase as text.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

“queued”, “running”, or “completed”.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
print.Line(tcpserver.RequestPhaseText($jobId));

Output after running

completed

When to use

For logging or UI display.

tcpserver.PhaseText

tcpserver.PhaseText(requestId) -> string

Synonym of RequestPhaseText.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

“queued”, “running”, or “completed”.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
print.Line(tcpserver.PhaseText($jobId));

Output after running

completed

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestStatus

tcpserver.RequestStatus(requestId) -> int

Returns the request status: 0 = success, non-zero = error.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

0 if successful; non-zero is the error code.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.RequestStatus($jobId));

Output after running

When to use

Worth checking first after WaitComplete.

tcpserver.Status

tcpserver.Status(requestId) -> int

Synonym of RequestStatus.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

0 or error code.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.Status($jobId));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestError

tcpserver.RequestError(requestId) -> string

Returns the request error message (empty on success).

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The error message; empty string on success.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", str.Len(tcpserver.RequestError($jobId)));

Output after running

When to use

If Status is non-0, check this for the cause.

tcpserver.ErrorText

tcpserver.ErrorText(requestId) -> string

Synonym of RequestError.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The error message.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", str.Len(tcpserver.ErrorText($jobId)));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestStatusText

tcpserver.RequestStatusText(requestId) -> string

The textual counterpart of the status.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

“success” on a successful request, other text depending on the error type.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
print.Line(tcpserver.RequestStatusText($jobId));

Output after running

success

When to use

For logging or user feedback.

tcpserver.StatusText

tcpserver.StatusText(requestId) -> string

Synonym of RequestStatusText.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

“success” or error text.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
print.Line(tcpserver.StatusText($jobId));

Output after running

success

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestInfo

tcpserver.RequestInfo(requestId) -> string

Returns the request state as a key=value diagnostic string.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

A space-separated key=value list.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", (str.Len(tcpserver.RequestInfo($jobId)) >
0));

Output after running

When to use

Detailed request diagnostics in a single call.

tcpserver.JobInfo

tcpserver.JobInfo(requestId) -> string

Synonym of RequestInfo.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

A key=value diagnostic string.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", (str.Len(tcpserver.JobInfo($jobId)) > 0));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestRoute

tcpserver.RequestRoute(requestId) -> int

Returns the id of the listener the request belongs to.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The listenerId.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", (tcpserver.RequestRoute($jobId) == $lid));

Output after running

When to use

Reflective query of the request-owner relation.

tcpserver.JobRoute

tcpserver.JobRoute(requestId) -> int

Synonym of RequestRoute.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The listenerId.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", (tcpserver.JobRoute($jobId) == $lid));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestTimeout

tcpserver.RequestTimeout(requestId) -> int

Returns the request's configured timeout in ms (from Begin*).

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The timeoutMs value.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", tcpserver.RequestTimeout($jobId));

Output after running

When to use

For logging or configuration checks.

tcpserver.JobTimeout

tcpserver.JobTimeout(requestId) -> int

Synonym of RequestTimeout.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The timeoutMs value.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", tcpserver.JobTimeout($jobId));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestKnown

tcpserver.RequestKnown(requestId) -> int

Tells whether the requestId is known to the plugin.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

1 if known; 0 if not (e.g. already destroyed by Take).

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", tcpserver.RequestKnown($jobId));

Output after running

When to use

Defensive check.

tcpserver.JobKnown

tcpserver.JobKnown(requestId) -> int

Synonym of RequestKnown.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

1 if known; 0 if not.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
printf("%d\n", tcpserver.JobKnown($jobId));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestMeta

tcpserver.RequestMeta(requestId, metaKey) -> int

Returns a meta field of the request by asyncmeta.JobMeta* keys.

Parameters

Parameter	Type	Description
requestId	int	The requestId.
metaKey	int	An asyncmeta.JobMeta* value (Phase, Status, Route, Timeout, Known, HasBlobResult, BlobResultSize).

Return value

The value for the field.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.RequestMeta($jobId,
asyncmeta.JobMetaPhase()));

Output after running

When to use

Uniform asyncmeta query on the request state.

tcpserver.JobMeta

tcpserver.JobMeta(requestId, metaKey) -> int

Synonym of RequestMeta.

Parameters

Parameter	Type	Description
requestId	int	The requestId.
metaKey	int	An asyncmeta.JobMeta* value.

Return value

The value for the field.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.JobMeta($jobId,
asyncmeta.JobMetaPhase()));

Output after running

When to use

Under the asyncmeta vocabulary — for portable multi-backend code.

tcpserver.RequestHasBlobResult

tcpserver.RequestHasBlobResult(requestId) -> int

Tells whether the request has a blob result.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

1 if yes; 0 if no.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.RequestHasBlobResult($jobId));

Output after running

When to use

Take precondition: if 0, TakeBlob raises a runtime error.

tcpserver.JobHasBlobResult

tcpserver.JobHasBlobResult(requestId) -> int

Synonym of RequestHasBlobResult.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

1 if yes; 0 if no.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.JobHasBlobResult($jobId));

Output after running

When to use

Under the asyncmeta vocabulary.

tcpserver.RequestBlobResultSize

tcpserver.RequestBlobResultSize(requestId) -> int

Returns the response blob size in bytes.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The blob size in bytes.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.RequestBlobResultSize($jobId));

Output after running

When to use

For memory pre-allocation: you know how big a blob to allocate for TakeBlob.

tcpserver.JobBlobResultSize

tcpserver.JobBlobResultSize(requestId) -> int

Synonym of RequestBlobResultSize.

Parameters

Parameter	Type	Description
requestId	int	The requestId.

Return value

The blob size in bytes.

Example

i64 $lid;
i64 $jobId;
$lid = tcpserver.Open("Echo", 5000);
$jobId = tcpserver.BeginTextRequest($lid, "HELLO", 5000);
tcpserver.WaitComplete($jobId, 5000);
printf("%d\n", tcpserver.JobBlobResultSize($jobId));

Output after running

When to use

Under the asyncmeta vocabulary.

Listener shutdown

Diagnostics of the listener (route) shutdown process and explicit shutdown. RouteClose and Close do the same thing under different names.

tcpserver.RouteCloseAccepted

tcpserver.RouteCloseAccepted(listenerId) -> int

Tells whether a close request has been accepted on the listener.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

1 if yes; 0 if no RouteClose / Close has happened yet.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
tcpserver.RouteClose($lid);
printf("%d\n", tcpserver.RouteCloseAccepted($lid));

Output after running

When to use

LATCH: once 1, it never resets. Useful for diagnostics.

tcpserver.RouteClosedQueued

tcpserver.RouteClosedQueued(listenerId) -> int

Returns the count of queued requests canceled by the most recent RouteClose / Close.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The count of canceled queued requests.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
tcpserver.RouteClose($lid);
printf("%d\n", tcpserver.RouteClosedQueued($lid));

Output after running

When to use

For diagnostics: how many requests were lost during shutdown.

tcpserver.RouteClose

tcpserver.RouteClose(listenerId) -> int

Synonym of Close — exact same handler.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

The count of canceled queued requests (0 = clean close).

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", tcpserver.RouteClose($lid));

Output after running

When to use

Under the asyncmeta vocabulary. Equivalent to Close — stylistic choice.

tcpserver.RouteCloseInfo

tcpserver.RouteCloseInfo(listenerId) -> string

Returns the listener shutdown process as a key=value diagnostic string.

Parameters

Parameter	Type	Description
listenerId	int	The listener id.

Return value

A space-separated key=value list.

Example

i64 $lid;
$lid = tcpserver.Open("Echo", 5000);
printf("%d\n", (str.Len(tcpserver.RouteCloseInfo($lid)) >
0));

Output after running

When to use

Detailed shutdown diagnostics in a single call.

Practical notes

What the tcpserver plugin is good for

Starting a local TCP service on a loopback port (debug server, local RPC, tested protocol).
Event-driven processing: every incoming TCP connection is a callback invocation; the callback gets RAW bytes and can implement any protocol.
Built-in client side for testing your own server: `RequestText`/`RequestBlob` are synchronous, `BeginTextRequest`/`BeginBlobRequest` are asynchronous — both open a loopback TCP connection.
Optional TLS layer with EnableTls: incoming connections are TLS-wrapped, the callback receives the decoded bytes unchanged.
asyncmeta compatibility with the full vocabulary: Phase, Status, JobMeta, RouteMeta, WaitDrained, RouteClose — every bit supported (Capabilities = 4095).

Server + client in one — the testing pattern

A key feature of the plugin is that a complete TCP exchange is reachable from one script: Open opens a server, and RequestText immediately calls the server itself. This is ideal for testing a callback implementation: you can invoke your own logic through a real TCP channel, ensuring the endpoints communicate properly. A minimal test: open a listener → send RequestText → check the response → close.

Request* vs Job* — synonym pairs

Every job-level (= queryable per async request) function has two names: the native `Request*` (paints the HTTP/RPC request image) and the asyncmeta-vocabulary `Job*`. The two forms are EXACTLY the same handler — pick stylistically. If your code works with other asyncmeta-compatible backends, `Job*` is more consistent; if only tcpserver, `Request*` is more expressive.

Sync vs async request

`RequestText`/`RequestBlob` are SYNCHRONOUS: the call blocks until the TCP connection + send + receive finishes. Simple, but the script does nothing else meanwhile. `BeginTextRequest`/`BeginBlobRequest` are ASYNCHRONOUS: they return immediately with a requestId, the background thread handles I/O. Then WaitComplete + TakeTextResponse / TakeBlob finish and collect. For high-throughput or parallel testing, the async form is recommended.

TLS activation

`EnableTls(listenerId, certFile, keyFile)` is IDEMPOTENT: calling it again with the same files just returns 0. The TLS layer runs through the tls plugin's provider — resolved at runtime, so the tcpserver plugin itself does not link OpenSSL. If the platform doesn't support TLS (e.g. a Windows pre-bundle build), EnableTls returns a clean error and the listener keeps serving plaintext.

Callback signature

The callback signature is `callback i32 NAME(ref blob $Request)`. The incoming `$Request` blob contains the RAW bytes received over the TCP connection — the plugin does not interpret HTTP, does not look for protocol framing. The callback may modify the blob bytes in place, and the modified content becomes the TCP response. If the callback writes nothing, the response is empty (as in the probe — the Echo callback returns 1 without modifying the blob).

Listener shutdown

`RouteClose(listenerId)` and `Close(listenerId)` are the SAME handler — two names, identical behavior. The return value is NOT a 1/0 success flag, but the COUNT of queued requests canceled by the close. Typically 0 (clean close with no pending requests). The two-step shutdown pattern: RouteClose → WaitDrained → forced cleanup (if needed). A single Close performs all steps.

Error handling

An invalid listenerId, requestId, wrong argument count or type, out-of-range timeoutMs, touching an already-closed listener or plugin are reported by the runtime as a runtime error, and the script stops. A TCP connect failure (e.g. connecting to a closed listener's port) gives an error code in the Status field; `RequestError` returns the error text. `TakeTextResponse` raises a runtime error if the response contains an embedded NUL byte — use TakeBlob instead.