Home /Examples/lib/examples/connector/LEARNING-NOTES.md

LEARNING-NOTES.md

lib/examples/connector/LEARNING-NOTES.md · 58 line(s) · markdown

Connector examples — what to learn here

A connector is the component that manages a relationship with an external service: configure it, open it, exchange data, close it. These examples teach how to make that relationship correct and resilient — without ever touching a real network. Every program is deterministic and has no side effects.

Read them in order.

The three cases

LevelFileThe one new idea
BasicBASIC-connector-lifecycle.sleelaThe lifecycle as an ordered checklist: configure → validate → open → exchange → close.
ModerateMODERATE-state-machine.sleelaThe lifecycle as a guarded state machine: transitions only fire from a legal state, and illegal calls fail closed.
AdvancedADVANCED-retry-backoff.sleelaResilience: retry transient failures with exponential backoff and a hard cap.

The original CLASSIC-connector-lifecycle.sleela is the shortest starter.

What we want you to take away

  1. A lifecycle is a contract. Step order matters. The basic example names the steps; the moderate example enforces them. If you try to open before configuring, or reopen after closing, the connector moves to FAILED instead of pretending everything is fine.
  2. Model state explicitly. Integer state constants plus small transition methods that each check their precondition is a pattern you will reuse for any lifecycle (sockets, files, sessions, hardware). The method names say what they do, and each returns the new state so callers can react.
  3. Transient failure is normal; hammering is a bug. The advanced example retries, but each retry waits twice as long as the last (100 → 200 → 400 ms), clamped to a ceiling. This protects the remote service and your own process. Here the delays are only simulated and summed so the run is reproducible.

Practical notes for SLeeLa 1.7

Run them

sleela check lib/examples/connector/MODERATE-state-machine.sleela
sleela run   lib/examples/connector/ADVANCED-retry-backoff.sleela

Output is deterministic: the state machine ends in FAILED after an illegal re-open, and the retry example connects on attempt 4 after 700 ms of simulated backoff.