88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# Internal: Adapters
|
|
|
|
## Purpose
|
|
|
|
Explain the adapter interfaces and production composition used by application
|
|
and stage orchestration. Externally observable protocols and formats belong in
|
|
the [integration contracts](../integrations/).
|
|
|
|
## Adapter Boundaries
|
|
|
|
Narratio stage logic depends on adapter interfaces, not transport-specific details.
|
|
|
|
Primary adapters:
|
|
|
|
- `whisperx.Client`
|
|
- `seriatim.Runner`
|
|
- `audita.Runner`
|
|
- `scriptorium.Runner`
|
|
- `notarius.Runner`
|
|
- `storage.ObjectStore`
|
|
- `notify.Sender`
|
|
|
|
## Ownership
|
|
|
|
Adapters own:
|
|
|
|
- HTTP/subprocess/SDK argument and transport details.
|
|
- Backend-specific request/response mapping.
|
|
|
|
Adapters do not own:
|
|
|
|
- stage ordering/skip/force logic;
|
|
- manifest transitions;
|
|
- canonical path policy.
|
|
|
|
## Default Wiring
|
|
|
|
`internal/app/runner.go` initializes default adapters when not injected:
|
|
|
|
- WhisperX HTTP client from pipeline config.
|
|
- Seriatim subprocess runner.
|
|
- Audita subprocess runner.
|
|
- Scriptorium subprocess runner.
|
|
- Notarius subprocess runner when extraction is enabled.
|
|
- Noop notifier (`notify.NoopSender`).
|
|
- Object store only when required by selected stages/config.
|
|
|
|
Notarius is composed only when extraction is enabled; the extract stage owns
|
|
receipt, bundle, and configured-lane policy rather than the adapter.
|
|
|
|
Object-store construction goes through `newCommandObjectStore`, which loads
|
|
configured filesystem secrets before adapter initialization.
|
|
|
|
## Failure Semantics
|
|
|
|
- Constructor errors fail stage execution setup early.
|
|
- Runtime adapter errors propagate to stage code and then manifest failure handling.
|
|
- Subprocess adapters persist stage logs/generated configs through stage-managed paths.
|
|
- Shared subprocess execution starts an owned process group on Linux/macOS or a
|
|
kill-on-close job object on Windows. Cancellation and deadlines request
|
|
termination, use a bounded forceful fallback, and wait for the leader before
|
|
returning. Child environments contain only the execution baseline and
|
|
adapter-specified values; configured credentials are explicit sensitive
|
|
values. Stdout and stderr are redacted while streaming into separate 8 MiB
|
|
diagnostic captures; a bounded wait closes a stream retained by a departed
|
|
leader's descendant. Reaching either limit terminates the owned tree.
|
|
Unsupported platforms reject owned command execution.
|
|
|
|
## Implementation And Tests
|
|
|
|
- Composition: `internal/app/runner.go`, `internal/app/object_store.go`
|
|
- Shared subprocess mechanics: `internal/adapters/subprocess`
|
|
- Focused adapters: `internal/adapters/{whisperx,seriatim,audita,scriptorium,notarius,storage,notify}`
|
|
- `internal/adapters/whisperx/http_test.go`
|
|
- `internal/adapters/seriatim/subprocess_test.go`
|
|
- `internal/adapters/audita/subprocess_test.go`
|
|
- `internal/adapters/scriptorium/subprocess_test.go`
|
|
- `internal/adapters/notarius/subprocess_test.go`
|
|
- `internal/adapters/storage/*_test.go`
|
|
- `internal/app/runner_test.go`
|
|
|
|
See the [WhisperX](../integrations/whisperx.md),
|
|
[Seriatim](../integrations/seriatim.md), [Audita](../integrations/audita.md),
|
|
[Scriptorium](../integrations/scriptorium.md), and
|
|
[Notarius](../integrations/notarius.md) contracts before changing an
|
|
externally visible boundary. Operator-selected values belong in
|
|
[Configuration](../config.md).
|