WebUI Wire IPC Bridge
| (require webui-wire-ipc) |
This module provides a small IPC abstraction around the external webui-wire executable. It is responsible for:
starting the webui-wire process (via ww-get-webui-wire-command);
reading and decoding its stdout and stderr streams;
dispatching incoming events to a callback;
serialising access to the process so it can be shared by multiple threads.
The public API consists of a single function, webui-ipc, which starts the helper process and returns a function for sending commands and receiving replies.
The helper process itself implements a simple text-based protocol; this module hides those details and presents a synchronous “send a string, get a string back” interface.
1 IPC entry point
procedure
(webui-ipc event-queuer log-processor) → (-> string? string?)
event-queuer : (-> string? any) log-processor : (-> symbol? string? any)
The arguments:
event-queuerA callback that receives event payloads produced by the helper process.
Whenever the process emits an EVENT line on stderr, the textual payload after the "EVENT:" tag is passed to this callback as:
(event-queuer line)
The callback is executed in the context of a dedicated reader thread and should return quickly (for example by placing the event on a queue to be handled elsewhere).
log-processorA callback used for all non-event messages and error conditions.
It is called as:
(log-processor kind msg)
where kind is a symbol describing the source or category of the message (for example 'stderr-reader or a tag from the incoming line) and msg is a human-readable string.
The return value is a command function with the contract (-> string? string?):
When you call it with a command string, it sends that command to the webui-wire process and blocks until one reply is received.
The reply payload (decoded as UTF-8) is returned as a plain string.
If anything goes wrong with the IPC protocol (invalid prefix, unexpected EOF, etc.), an exception is raised.
A typical usage pattern:
(define (enqueue-event line) (printf "EVENT: ~a\n" line)) (define (log-message kind msg) (printf "[~a] ~a\n" kind msg)) (define send-cmd (webui-ipc enqueue-event log-message)) (define reply (send-cmd "HELLO 42")) (printf "Reply was: ~a\n" reply)
Notes:
The command function writes a line to the process stdin using displayln; callers do not need to append a newline themselves.
Calls to the command function are executed one at a time, even when invoked from multiple threads (see Concurrency and serialisation).
2 Protocol overview (informative)
The webui-wire process uses a simple length-prefixed text protocol on both stdout and stderr. This section describes the format for reference; the details are handled internally by this module.
2.1 Message framing
Each message from the helper has the following structure:
An 8-character decimal length prefix (ASCII digits),
followed by a single colon character ":",
followed by exactly that many bytes of payload,
followed by a single newline character.
The payload is treated as UTF-8 text by this module.
2.2 Stdout replies
On stdout:
Each command sent via the returned command function results in exactly one reply on stdout with the framing described above.
The payload is decoded as UTF-8 and returned to the caller as a plain string.
If the helper sends malformed output (for example, a non-numeric prefix, incorrect length, or missing colon), the IPC code raises an error indicating “unexpected input from webui-wire executable”.
2.3 Stderr events and logs
On stderr:
Each payload is interpreted as a single logical line;
The line is expected to start with a symbolic tag followed by a colon, e.g. "EVENT:..." or "INFO:...".
The module distinguishes:
EVENT lines: the text after the "EVENT:" prefix is delivered to the event-queuer callback.
All other tags (and untagged lines): turned into (kind msg) calls to log-processor, where kind is a symbol derived from the tag or from the stderr reader, and msg is the remaining text.
If the stderr reader encounters EOF, it reports this via log-processor (using an appropriate kind symbol) and then terminates its reader thread.
3 Internal behaviour (informative)
This section summarises how webui-ipc is implemented. The details are not part of the public API, but they can help to interpret log messages and errors.
3.1 Process startup
When you call webui-ipc, the following steps are performed:
Obtain the command string for webui-wire by calling ww-get-webui-wire-command from webui-wire-download.
Launch the helper process using process from racket/system.
Keep handles to the process stdin, stdout, and stderr ports.
Spawn a background thread dedicated to reading and decoding stderr events and log lines.
If the process cannot be started, an exception is raised immediately from webui-ipc.
3.2 Concurrency and serialisation
The command function returned by webui-ipc may be called from multiple threads.
Internally, a semaphore is used to ensure that only one caller at a time:
writes a command line to the process stdin,
waits for a single, complete reply on stdout,
returns that reply to the caller.
This guarantees that requests and replies do not interleave: the reply string you receive always corresponds to the command you sent in that call.
The stderr reader runs independently in its own thread and does not block command calls.
3.3 Error handling and shutdown
Several error conditions can occur:
EOF or broken pipe on stdin/stdout/stderr;
malformed length prefix or framing errors;
helper process exiting unexpectedly.
In these cases, the module:
raises an exception from the command function on the next call that attempts to send a command or read a reply;
reports context via log-processor (for example, that the stderr reader hit EOF or that the executable exited).
It is the responsibility of the caller to decide how to react: typically by catching such exceptions at a higher level, informing the user, and possibly restarting the application or IPC bridge.
Once the webui-wire process has exited, the previously returned command function is no longer usable; further calls are expected to fail with an error.