stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
40362de56880f054c29ce23e6ba980834a7f831f
git.stella-ops.org/docs/modules/router/messaging-valkey-transport.md
StellaOps Bot 7503c19b8f 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.
2025-12-24 02:17:34 +02:00

3.9 KiB
Raw Blame History

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