README
¶
weaveplatform-sdk
The library layer of the Weave platform agent: what modules (and core) build on. Depends only
on weaveplatform-api and infrastructure (grpc, x/sys). CGO_ENABLED=0 throughout — this is
a Zone A library.
flowchart LR
api[weaveplatform-api] --> sdk[<b>weaveplatform-sdk</b><br/>this repo]
sdk --> agent[weaveplatform-agent]
sdk --> modules[weaveplatform-agent-modules]
style sdk fill:#1f6feb,color:#fff
Packages
| Package | What |
|---|---|
modulesdk |
The module runtime: implement Module, call modulesdk.Serve(m) — handshake, lifecycle dispatch, health serving and the Host client are handled for you |
modulesdk/testkit |
Fake Host, in-memory store/policy/bus, and the protocol-compat harness every module's CI runs |
platform |
The thin OS seam: host info, well-known paths, session helpers. No bindings re-exports — modules link go-bindings-* directly at protocol-pinned versions |
werror |
Error conventions: sentinels + wrapping |
wlog |
slog construction; module logs stream to core after Init |
config |
Handshake-delivered config document > env > defaults; no files, no viper |
retry |
Exponential backoff with full jitter; policy calculator, not a loop runner |
Writing a module
Start with docs/writing-a-module.md — the Module interface,
the Host surface, health semantics, the manifest, and testing with testkit.StubCore. Then
copy sysinfo,
which exists to be copied.
Rules
- Host is closed by default (spec §5). This SDK grows by design review, not accretion.
- Modules never import each other, never open their own sockets, never draw UI.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config resolves a module's typed configuration.
|
Package config resolves a module's typed configuration. |
|
Package handshake is the shared vocabulary of the core↔module handshake: the environment core sets, the one stdout line the module answers with, and the exit code that means "protocol out of window".
|
Package handshake is the shared vocabulary of the core↔module handshake: the environment core sets, the one stdout line the module answers with, and the exit code that means "protocol out of window". |
|
Package ipc owns local transport: Unix domain sockets on macOS and Linux, named pipes on Windows, behind one Listen/Dial seam so neither core nor the SDK runtime carries per-OS socket code at call sites.
|
Package ipc owns local transport: Unix domain sockets on macOS and Linux, named pipes on Windows, behind one Listen/Dial seam so neither core nor the SDK runtime carries per-OS socket code at call sites. |
|
Package modulesdk is the module runtime.
|
Package modulesdk is the module runtime. |
|
testkit
Package testkit is the test harness for modules and for the module runtime itself.
|
Package testkit is the test harness for modules and for the module runtime itself. |
|
Package platform is the deliberately thin OS seam.
|
Package platform is the deliberately thin OS seam. |
|
Package retry provides exponential backoff with jitter.
|
Package retry provides exponential backoff with jitter. |
|
Package werror carries the platform's error conventions: sentinel errors for conditions callers branch on, and wrapping helpers that keep module and operation context attached.
|
Package werror carries the platform's error conventions: sentinel errors for conditions callers branch on, and wrapping helpers that keep module and operation context attached. |
|
Package wlog constructs the platform's loggers.
|
Package wlog constructs the platform's loggers. |
Click to show internal directories.
Click to hide internal directories.