117 lines
4.9 KiB
Markdown
117 lines
4.9 KiB
Markdown
# Adapter Internals
|
|
|
|
## Purpose
|
|
|
|
Adapters translate external inputs into public engine requests and translate
|
|
public results or errors back to their interface. They own IO and presentation
|
|
mechanics; use-case decisions remain behind the root `scriptorium` facade.
|
|
|
|
External contracts are canonical in the [CLI reference](../cli.md), [HTTP API
|
|
reference](../api.md), and [Go package contract](../consumers/pkg-scriptorium.md).
|
|
|
|
## Components And Collaborators
|
|
|
|
- `cmd/scriptorium` passes process arguments and streams to
|
|
`internal/adapter/cli`.
|
|
- `internal/adapter/cli` parses commands, resolves application settings through
|
|
`internal/config`, constructs the public engine, and owns process output
|
|
handling.
|
|
- `internal/adapter/http` decodes DTOs, maps them to public run requests,
|
|
calls its local public `Runner` interface, and maps public errors and results
|
|
to HTTP DTOs.
|
|
- The root `scriptorium` package maps its public types and options to internal
|
|
collaborators and maps selected internal errors to public sentinels.
|
|
- `internal/format` formats public prepared runs for the CLI.
|
|
|
|
## Wiring Flows
|
|
|
|
### CLI
|
|
|
|
The CLI resolves configuration before constructing the public engine. `run`
|
|
calls `Engine.Run` with a public request and `render` calls `Engine.Prepare`
|
|
with the same request mapping. `serve` constructs the HTTP-owned restricted
|
|
artifact reader, injects it with `WithArtifactReader`, passes the resulting
|
|
engine directly to the HTTP handler, and starts the server.
|
|
|
|
Parser state records whether numeric runtime values were explicitly supplied.
|
|
That presence is carried into `scriptorium.ExecutionTargetOverride`, allowing
|
|
the engine to distinguish omitted values from explicit zero overrides.
|
|
|
|
### HTTP
|
|
|
|
The handler first enforces transport limits, strict JSON decoding, and the
|
|
minimal request shape. It maps DTO values to public types without deciding
|
|
prompt selection, source behavior, or validation semantics. On success it maps
|
|
the public result to the response DTO; on failure it uses `errors.Is` over
|
|
public framework errors and HTTP-local artifact-policy errors to choose the
|
|
public error mapping.
|
|
|
|
The [HTTP API reference](../api.md) owns the route, DTO schema, status codes,
|
|
and externally observable limit behavior.
|
|
|
|
### Public Go Facade
|
|
|
|
`NewEngine` applies public options, selects filesystem, `fs.FS`, single-file,
|
|
or in-memory dependencies, and constructs a runner. The conversion functions
|
|
copy maps and slices across the boundary so callers do not receive internal
|
|
domain values. The facade maps selected internal errors to the public sentinel
|
|
set and keeps direct request API keys out of public results.
|
|
|
|
## Package-Local Guarantees
|
|
|
|
- Adapters do not embed framework orchestration or source-loading decisions.
|
|
- Configuration is resolved before adapter dependency composition.
|
|
- CLI and HTTP consume the public engine without a repairer; a repairer remains
|
|
available only through explicit internal runner construction.
|
|
- DTO conversion preserves explicit numeric-override presence.
|
|
- Error mapping matches error identities, not error text.
|
|
- No adapter creates durable run state; caller-selected output files are not
|
|
application state.
|
|
|
|
## Failure And Verification Boundaries
|
|
|
|
Keep external error payloads concise, preserve strict external decoding, and do
|
|
not serialize resolved secret values. Validation content failures remain result
|
|
state; runtime failures remain errors for the relevant adapter to map.
|
|
|
|
Inspect focused tests when changing this area:
|
|
|
|
- `internal/adapter/cli/run_test.go`
|
|
- `internal/adapter/http/handler_test.go`
|
|
- `engine_test.go`
|
|
- `internal/format/prepared_run_test.go`
|
|
|
|
Run the affected adapter package tests and recheck the relevant canonical
|
|
contract. The [testing policy](../policy/testing.md) owns global test
|
|
sufficiency guidance.
|
|
|
|
## Change Recipes
|
|
|
|
### Application Configuration Fields
|
|
|
|
1. Add the field to the relevant `internal/config` shape and default handling.
|
|
2. Parse and validate it, then preserve configuration and CLI-override
|
|
precedence while wiring it through its consuming adapter.
|
|
3. Add focused configuration and adapter tests for parsing, mapping, and
|
|
effective behavior.
|
|
4. Update the [configuration contract](../config.md) and any affected external
|
|
contract.
|
|
|
|
### CLI Flags
|
|
|
|
1. Add the flag to the relevant parser in `internal/adapter/cli/run.go`.
|
|
2. Keep command scope and application-configuration precedence intentional.
|
|
3. Add or update parser and command tests in
|
|
`internal/adapter/cli/run_test.go`.
|
|
4. Update the [CLI contract](../cli.md) and affected maintained examples.
|
|
|
|
### Adapter Capabilities
|
|
|
|
1. Define or reuse an adapter-local consumer interface with public facade
|
|
types when a test seam is needed.
|
|
2. Implement translation and IO behavior without moving framework decisions out
|
|
of the public engine.
|
|
3. Add focused mapping, parsing, and error-behavior tests.
|
|
4. Update this document and the affected public or integration contract. Update
|
|
[source internals](sources.md) when source-loading behavior changes.
|