Sync architecture specs with Phase 2 research findings
- Add definitions.md: normative terminology disambiguation (Interface, Service, Transport, Token, Identity, Domain, Scope, CredentialProvider, etc.) - Add credentials.md: CredentialProvider trait and CredentialSet enum for outbound auth, mirroring IdentityProvider pattern for inbound auth - Rewrite interface.md: StreamInterface/MessageInterface split (ADR-035), InterfaceRequest/InterfaceResponse, HttpInterface/DnsInterface stubs, ListenerConfig with Stream/Http/Dns variants, credential presentation table - Update auth.md: API keys in DynamicConfig (ADR-037), credential presentation per (Transport, Interface) pair, ApiKeyEntry struct in AuthPolicy - Update configuration.md: API keys, ListenerConfig with Http/Dns variants, expanded TOML config examples - Update call-protocol.md: resolve OQ-IF-01 (InterfaceEvent carries EventEnvelope + Identity), add MessageInterface awareness to protocol adapter layer - Update overview.md: three-layer model now includes StreamInterface/ MessageInterface, CredentialProvider/CredentialSet exports, definitions.md reference, ADRs 035-037 - Update open-questions.md: resolve OQ-IF-01, OQ-IF-02, add OQ-P2-01 through OQ-P2-04, add OQ-CP-01 through OQ-CP-04, add OQ-DEF-01, OQ-DEF-03, OQ-DEF-08 - Update README.md: add definitions.md, credentials.md, ADRs 035-037, phase2 research docs, current state description Key architectural decisions: - ADR-035: StreamInterface/MessageInterface split (two Layer 2 traits) - ADR-036: CredentialProvider as core type (outbound auth, alknet_core::credentials) - ADR-037: API keys as DynamicConfig auth (hash-verified bearer tokens)
This commit is contained in:
@@ -311,8 +311,18 @@ periodically.
|
||||
|
||||
### Protocol Adapter Layer
|
||||
|
||||
The call protocol is transport-agnostic by design. It maps to any transport
|
||||
that carries `EventEnvelope` frames:
|
||||
The call protocol is transport-agnostic and interface-agnostic by design. It
|
||||
receives input from two interface categories (ADR-035):
|
||||
|
||||
**StreamInterface** produces `InterfaceEvent` frames from a continuous byte
|
||||
stream (SSH channel, raw framing). The call protocol handler calls `recv()`
|
||||
on the session to get events.
|
||||
|
||||
**MessageInterface** handles individual `InterfaceRequest` → `InterfaceResponse`
|
||||
pairs (HTTP, DNS). The call protocol handler constructs an `OperationContext`
|
||||
from the request and invokes the registry directly.
|
||||
|
||||
Both paths resolve to the same `OperationRegistry` and `OperationEnv`:
|
||||
|
||||
| Transport | Channel mechanism | Direction |
|
||||
|-----------|-------------------|-----------|
|
||||
@@ -494,9 +504,16 @@ agent service itself is built on top, not into the core.
|
||||
in gRPC terms)?~~ Resolved — deferred. Current model covers all identified use
|
||||
cases. See [open-questions.md](open-questions.md).
|
||||
|
||||
- **OQ-IF-01**: How does the `Interface` session type relate to the call
|
||||
protocol's `EventEnvelope` stream? This needs design during Phase 1.8
|
||||
implementation. See [open-questions.md](open-questions.md).
|
||||
- **~~OQ-IF-01~~**: ~~How does the `Interface` session type relate to the call
|
||||
protocol's `EventEnvelope` stream?~~ Resolved — `InterfaceSession::recv()`
|
||||
returns `Option<InterfaceEvent>` where `InterfaceEvent` carries
|
||||
`EventEnvelope` + `Identity`. `InterfaceSession::send()` accepts `EventEnvelope`.
|
||||
The `SshSession` bridge implements this over the `alknet-control:0` channel.
|
||||
For `MessageInterface`, `InterfaceRequest`/`InterfaceResponse` normalize
|
||||
request/response pairs. See [interface.md](interface.md) and ADR-035.
|
||||
|
||||
- **OQ-P2-01**: Should `MessageInterface` and `StreamInterface` share a common
|
||||
trait? See [interface.md](interface.md) and [open-questions.md](open-questions.md).
|
||||
|
||||
## Design Decisions
|
||||
|
||||
@@ -507,6 +524,7 @@ agent service itself is built on top, not into the core.
|
||||
| [025](decisions/025-handler-spec-separation.md) | Handler/spec separation | Downstream registers operations without modifying core |
|
||||
| [028](decisions/028-auth-irpc-service.md) | Auth as irpc service | irpc is one dispatch backend for OperationEnv |
|
||||
| [033](decisions/033-operationenv-irpc-call-protocol.md) | OperationEnv | Universal composition with three dispatch paths |
|
||||
| [035](decisions/035-streaminterface-messageinterface-split.md) | StreamInterface/MessageInterface | Call protocol accepts events from both interface categories |
|
||||
|
||||
## References
|
||||
|
||||
|
||||
Reference in New Issue
Block a user