stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
8355e2ff7575b8fa5a1bc137850b018701c51373
git.stella-ops.org/docs/modules/orchestrator/event-envelope.md
master 8355e2ff75
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat: Add initial implementation of Vulnerability Resolver Jobs 
- Created project for StellaOps.Scanner.Analyzers.Native.Tests with necessary dependencies.
- Documented roles and guidelines in AGENTS.md for Scheduler module.
- Implemented IResolverJobService interface and InMemoryResolverJobService for handling resolver jobs.
- Added ResolverBacklogNotifier and ResolverBacklogService for monitoring job metrics.
- Developed API endpoints for managing resolver jobs and retrieving metrics.
- Defined models for resolver job requests and responses.
- Integrated dependency injection for resolver job services.
- Implemented ImpactIndexSnapshot for persisting impact index data.
- Introduced SignalsScoringOptions for configurable scoring weights in reachability scoring.
- Added unit tests for ReachabilityScoringService and RuntimeFactsIngestionService.
- Created dotnet-filter.sh script to handle command-line arguments for dotnet.
- Established nuget-prime project for managing package downloads.
2025-11-18 07:52:15 +02:00

2.6 KiB
Raw Blame History

Orchestrator Event Envelope (draft)

Status: draft for ORCH-SVC-38-101 (pending ORCH-SVC-37-101 approval)

Goals

  • Single, provenance-rich envelope for policy/export/job lifecycle events.
  • Idempotent across retries and transports (Notifier bus, webhooks, SSE/WS streams).
  • Tenant/project isolation and offline-friendly replays.

Envelope

{
  "schemaVersion": "orch.event.v1",
  "eventId": "urn:orch:event:...",            // UUIDv7 or ULID
  "eventType": "job.failed|job.completed|pack_run.log|pack_run.artifact|policy.updated|export.completed",
  "occurredAt": "2025-11-19T12:34:56Z",
  "idempotencyKey": "orch-{eventType}-{jobId}-{attempt}",
  "correlationId": "corr-...",                 // propagated from producer
  "tenantId": "...",
  "projectId": "...",                          // optional but preferred
  "actor": {
    "subject": "service/worker-sdk-go",        // who emitted the event
    "scopes": ["orch:quota", "orch:backfill"]
  },
  "job": {
    "id": "job_018f...",
    "type": "pack-run|ingest|export|policy-simulate",
    "runId": "run_018f...",                    // for pack runs / sims
    "attempt": 3,
    "leaseId": "lease_018f...",
    "taskRunnerId": "tr_018f...",
    "status": "completed|failed|running|canceled",
    "reason": "user_cancelled|retry_backoff|quota_paused",
    "payloadDigest": "sha256:...",
    "artifacts": [
      {"uri": "s3://...", "digest": "sha256:...", "mime": "application/json"}
    ]
  },
  "metrics": {
    "durationSeconds": 12.345,
    "logStreamLagSeconds": 0.8,
    "backoffSeconds": 30
  },
  "notifier": {
    "channel": "orch.jobs",
    "delivery": "dsse",
    "replay": {"ordinal": 5, "total": 12}
  }
}

Idempotency rules

  • eventId globally unique; idempotencyKey dedupe per channel.
  • Emit once per state transition; retries reuse the same eventId/idempotencyKey.

Provenance

  • Always include tenantId and projectId (if available).
  • Carry correlationId from upstream producers and taskRunnerId from leasing bridge.
  • Include actor.scopes when events are triggered via elevated tokens (orch:quota, orch:backfill).

Transport bindings

  • Notifier bus: DSSE-wrapped envelope; subject orch.event and eventType.
  • Webhooks: HMAC with X-Orchestrator-Signature (sha256), replay-safe via idempotencyKey.
  • SSE/WS: stream per tenantId filtered by projectId; client dedupe via eventId.

Backlog & follow-ups

  • Align field names with ORCH-SVC-37-101 once finalized.
  • Add examples for policy/export events and pack-run log/manifest payloads.
  • Document retry/backoff semantics in Notify/Console subscribers.