shc / arch / plugs-and-sockets ← lab docs

Wire the app to its providers

An app declares what it needs as a plug file and a provider declares what it offers as a socket file. The filename stem is the type. Nothing below is connected, and the sockets are not in the plugs' order; drag each wire to the socket carrying its own name. Wiring one does not copy env vars: the provider runs jobs and creates the real database, bucket or OIDC client.

state nothing wired wired 0/4
Four unwired plug files on the left, four provider sockets on the right, out of order The consumer stack nextcloud declares four plug files, top to bottom: postgres.plug.yaml, s3.plug.yaml, smtp.plug.yaml, oidc.plug.yaml. Four provider stacks sit opposite in a different order: mail stack mx offering smtp.socket.yaml, keycloak stack kc offering oidc.socket.yaml, postgres stack db offering postgres.socket.yaml, external-s3 front obj backed by an S3 connection offering s3.socket.yaml. No wire is connected. Each plug carries a connector head cut to its type and each socket a cavity of the same shape. Drag from a plug to pull a wire, and drop it on the socket whose filename stem matches. Or focus a plug and press Enter to try each socket in turn; Escape unwires it.
drag a plug to its socket · enter tries · esc unwires
●shc integration plugs · live shc cli
simulated sources & caveats

No live cluster. The stage mirrors internal/modules/app/integration_render.go (ParseIntegrateFlags, resolveIntegrations, findSocketForPlug, buildIntegrationsContext), socket_jobs.go, plug_jobs.go and plug_required.go. Every file path, field name, SQL statement and app name shown is copied from the real catalog under apps/.
How the type check actually works: findSocketForPlug looks for exactly <plug>.socket.yaml in the provider's app dir. One honest caveat: when the provider ships exactly one socket and the stem does not match, it falls back to that sole socket. So a wrong wire onto db, obj or mx is refused here as a type error, but the real findSocketForPlug would bind it to that provider's only socket anyway. Only keycloak refuses absolutely: it ships four (oidc.socket.yaml, saml.socket.yaml, ldap.socket.yaml, keycloakAdmin.socket.yaml), so the fallback cannot fire and the name really is the type.
What "no match" costs you: nothing loud, unless the plug is required. An unmatched edge resolves to an empty integrations.s3 and the consumer falls back to its own vars.s3.*. The hard gate is required: in the plug file: nextcloud's postgres.plug.yaml and s3.plug.yaml carry required: "{{ not vars.postgres.hostname }}" and required: "{{ not vars.s3.endpoint }}", both empty by default, so an install naming neither fails with X400994PLGREQ before anything deploys. smtp and oidc declare no required:; they are optional.
Secrets: the @secret marker in a socket schema is the only part of that schema the Go daemon reads; it drives cross-tenant redaction, blanking those socket fields in the copy a foreign tenant's compose renders. The rest of the schema block is documentation. A consumer never carries a plaintext password in its app definition either: vars.postgres.password is ref+vault://postgres_password?autogen, minted and resolved from the vault at render time.
Teardown is not symmetric yet: sockets and plugs may declare unintegration and cleanup job phases, but no runner consumes them; disconnect deletes the edge row only. A provisioned database or OIDC client survives an uninstall. Docs: docs.