artifact; pure; gasoline;
lib/advantage/connect — the connectivity medium
The in-between component structure that connects Advantage™ SLeeLa programs to the outside world: databases, national clocks, networks, and money sources. It is a medium — a thin, uniform layer that sits between a pure Advantage model and the messy, stateful systems it must talk to — so the model code stays clean and every external call is validated, status-coded, and fault-recorded the same way.
artifact; pure; gasoline;— an Advantage™ subject. These classes model lifecycle and the native boundary; they do not dial a live database, clock, socket, or bank from inside the SLeeLa VM, and this is not financial advice.
The medium at a glance
| Class | Connects to | Native entry points (documented, host-adapter supplied) |
|---|---|---|
SLConnectStatus | — (shared) | the universal integer status vocabulary (OK … NATIVE_ADAPTER_REQUIRED … INTERNAL) |
SLConnectFault | — (shared) | the structured fault record every connector raises |
SLSqlConnector | MySQL / databases | slsql_open / ping / execute / query / close (mirrors lib/connector/mysql) |
SLClockConnector | national clocks / NTP | slntp_open / sync / now / close |
SLNetConnector | network connectivity | slnet_connect / probe / write / close |
SLMoneyConnector | money sources (banks, cards, wallets) | slbank_open / authorize / capture / refund / void / close |
A runnable connect-demo.sleela drives all four through their lifecycle, their
native-adapter boundary, and a fault path, and ends in ALL CHECKS PASSED.
Exception handling for all classes of perform
SLeeLa the language has try/catch/throw, but the standard library signals
failure with integer status codes plus a structured fault record — a single,
uniform convention across every connector. That is the "exception handling for
all these classes of perform":
SLConnectStatus— one vocabulary of outcome codes shared by all four connectors:OK(0),INVALID_ARGUMENT(1),INVALID_STATE(2),NOT_CONFIGURED(3),UNAUTHORIZED(4),TIMEOUT(5),UNREACHABLE(6),PROTOCOL(7),DECLINED(8),NATIVE_ADAPTER_REQUIRED(9),INTERNAL(10). It also classifies a code as transient (safe to retry) or permanent.SLConnectFault— the exception stand-in:code,subsystem,operation,message,retryable, andattempts. Each connector exposeslastFault(); a caller inspects it instead of catching. Domain rules override retryability — e.g. a moneyDECLINEDis marked non-retryable so no caller loops on a refusal.
Every method returns a status code; a non-OK code leaves a fully populated fault behind. No connector throws.
The native boundary (where the real connection plugs in)
Each connector models its lifecycle and accounting in the VM (so a program
can be written, type-checked, and validated offline) and defers the operation
that actually touches the outside world to a host adapter, returning
NATIVE_ADAPTER_REQUIRED(9). The native entry points are named in each class's
header doc comment (and in the table above); a host runtime registers adapters
that implement them. This mirrors the existing precedent in
lib/advantage/output/SLAdvantageSink.sleela (slnet_*) and the native ABI in
lib/connector/mysql.
Host-adapter callbacks let a real result flow back in without breaking the
status model: SLClockConnector.acceptSync(offset, stratum),
SLNetConnector.acceptProbe(rtt), and SLMoneyConnector.acceptAuthorization /
declineAuthorization.
Safety notes baked into the classes
- No secrets in SLeeLa. The SQL connector keeps only a redacted coordinate
(
mysql://host:port/db) and a flag that a credential is pinned; the money connector keeps only a keystore alias — never a PAN, CVV, or password. The real secret is resolved by the native adapter from the keystore (seelib/advantage/transport). - Money is integer cents to avoid floating-point error; capture cannot exceed the authorization, and refund cannot exceed the captured net.
- Clocks declare their schedule.
SLClockConnectorcites NTPv4 (RFC 5905) and treats UTC (BIPM / national metrology institutes) as the reference scale; it records which authority was configured without endorsing any.
Run it
./working-binaries/sleela run lib/advantage/connect/connect-demo.sleela