Add determinism tests for verdict artifact generation and update SHA256 sums script

- Implemented comprehensive tests for verdict artifact generation to ensure deterministic outputs across various scenarios, including identical inputs, parallel execution, and change ordering.
- Created helper methods for generating sample verdict inputs and computing canonical hashes.
- Added tests to validate the stability of canonical hashes, proof spine ordering, and summary statistics.
- Introduced a new PowerShell script to update SHA256 sums for files, ensuring accurate hash generation and file integrity checks.
This commit is contained in:
StellaOps Bot
2025-12-24 02:17:34 +02:00
parent e59921374e
commit 7503c19b8f
390 changed files with 37389 additions and 5380 deletions

View File

@@ -0,0 +1,75 @@
# Router · Messaging Transport over Valkey (Draft v0.1)
## Status
- Draft; intended for implementation via a dedicated sprint.
- Last updated: 2025-12-23 (UTC).
## Purpose
Enable Gateway ↔ microservice Router traffic over an offline-friendly, Redis-compatible transport (Valkey) by using the existing **Messaging** transport layer:
- Router transport: `StellaOps.Router.Transport.Messaging`
- Messaging backend: `StellaOps.Messaging.Transport.Valkey`
This supports environments where direct TCP/TLS microservice connections are undesirable, and where an internal message bus is the preferred control plane.
## What Exists Today (Repository Reality)
- Messaging transport server/client:
- `src/__Libraries/StellaOps.Router.Transport.Messaging/MessagingTransportServer.cs`
- `src/__Libraries/StellaOps.Router.Transport.Messaging/MessagingTransportClient.cs`
- Valkey-backed message queue factory:
- `src/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyMessageQueueFactory.cs`
- Gateway WebService currently starts only TCP/TLS transport servers:
- `src/Gateway/StellaOps.Gateway.WebService/Program.cs`
- `src/Gateway/StellaOps.Gateway.WebService/Services/GatewayHostedService.cs`
## High-Level Flow
1) Microservice connects via messaging transport:
- publishes a HELLO message to the gateway request queue
2) Gateway processes HELLO:
- registers instance + endpoints into routing state
3) Gateway routes an HTTP request to a microservice:
- publishes a REQUEST message to the service request queue
4) Microservice handles request:
- executes handler (or ASP.NET bridge) and publishes a RESPONSE message
5) Gateway returns response to the client.
## Queue Topology (Conceptual)
The Messaging transport uses a small set of queues (names are configurable):
- **Gateway request queue**: receives HELLO / HEARTBEAT / REQUEST frames from services
- **Gateway response queue**: receives RESPONSE frames from services
- **Per-service request queues**: gateway publishes REQUEST frames targeted to a service
- **Dead letter queues** (optional): for messages that exceed retries/leases
## Configuration (Draft)
### Gateway
- Register Valkey messaging services (`StellaOps.Messaging.Transport.Valkey`)
- Add messaging transport server (`AddMessagingTransportServer`)
- Add Gateway config section for messaging transport options:
- Valkey connection info (host/port/auth)
- queue naming prefix
- consumer group / lease duration / dead-letter suffix
### Microservice
- Register Valkey messaging services (`StellaOps.Messaging.Transport.Valkey`)
- Add messaging transport client (`AddMessagingTransportClient`)
- Ensure Microservice Router SDK connects via `IMicroserviceTransport`
## Operational Semantics (Draft)
- **At-least-once** delivery: message queues and leases imply retries are possible; handlers should be idempotent where feasible.
- **Lease timeouts**: must be tuned to max handler execution time; long-running tasks should respond with 202 + job id rather than blocking.
- **Determinism**: message ordering may vary; Router must not depend on arrival order for correctness (only for freshness/telemetry).
## Security Notes
- Messaging transport is internal. External identity must still be enforced at the Gateway.
- The Gateway must not trust client-supplied identity headers; it must overwrite reserved headers before dispatch.
- See `docs/modules/gateway/identity-header-policy.md`.
## Gaps / Implementation Work
1) Wire Messaging transport into Gateway:
- start/stop `MessagingTransportServer`
- subscribe to HELLO/HEARTBEAT/RESPONSE events and reuse existing HELLO validation + routing state updates
2) Extend Gateway transport client to support `TransportType.Messaging` for dispatch.
3) Add config mapping and deployment examples (compose/helm) for Valkey transport.
4) Add integration tests covering:
- microservice HELLO registration via messaging
- request dispatch + response return