coulomb/hub-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: transport authoritative workload projections
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49
This commit is contained in:
tegwick 2026-08-23 10:54:40 +02:00
parent a090903cfc
commit ab936a1e98
27 changed files with 1671 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

11
hub_core/contracts/__init__.py
View file

@ -7,6 +7,8 @@ CONTRACT_ID = "helixforge.hub-extension"
CONTRACT_VERSION = "0.1.0"
REPOSITORY_NAVIGATION_CONTRACT_ID = "helixforge.repository-navigation"
REPOSITORY_NAVIGATION_CONTRACT_VERSION = "1.0.0"
WORKLOAD_PROJECTION_CONTRACT_ID = "helixforge.workload-projection"
WORKLOAD_PROJECTION_CONTRACT_VERSION = "1.0.0"
def extension_contract_root() -> Traversable:
@ -21,11 +23,20 @@ def repository_navigation_contract_root() -> Traversable:
return files("hub_core.contracts.repository_navigation.v1_0_0")
def workload_projection_contract_root() -> Traversable:
"""Return the packaged root for the workload-projection contract."""
return files("hub_core.contracts.workload_projection.v1_0_0")
__all__ = [
"CONTRACT_ID",
"CONTRACT_VERSION",
"REPOSITORY_NAVIGATION_CONTRACT_ID",
"REPOSITORY_NAVIGATION_CONTRACT_VERSION",
"WORKLOAD_PROJECTION_CONTRACT_ID",
"WORKLOAD_PROJECTION_CONTRACT_VERSION",
"extension_contract_root",
"repository_navigation_contract_root",
"workload_projection_contract_root",
]

1
hub_core/contracts/workload_projection/__init__.py Normal file
View file

@ -0,0 +1 @@
"""Versioned authoritative workload projection contracts."""

13
hub_core/contracts/workload_projection/v1_0_0/README.md Normal file
View file

@ -0,0 +1,13 @@
# helixforge.workload-projection 1.0.0
This package freezes hub-core's transport boundary for Repo Manager's
`helixforge.workload-reference/v1` index. It includes strict input/output JSON
schemas, a nine-declaration fixture, the read-only query OpenAPI fragment, and
the compatibility/authority matrix.
The exact identity key is `rapp_id` plus `workload_identity.name`; optional
deployable resolution checks declared membership. Hub-core transports and
queries normalized records with source repository, declaration path, source
Git revision, and canonical UTC observation metadata. It never infers identity
from repository names, owners, paths, or aliases and never imports Repo Manager
private persistence.

1
hub_core/contracts/workload_projection/v1_0_0/__init__.py Normal file
View file

@ -0,0 +1 @@
"""Packaged workload projection contract 1.0.0."""

25
hub_core/contracts/workload_projection/v1_0_0/compatibility-matrix.json Normal file
View file

@ -0,0 +1,25 @@
{
"contract_id": "helixforge.workload-projection",
"current_version": "1.0.0",
"accepted_inputs": [
{
"contract_id": "helixforge.workload-projection-source",
"version": "1.0.0",
"source_contract": "helixforge.workload-reference/v1",
"status": "current",
"coercion": false
}
],
"authority": {
"declarations": "rapp-*/declarations/rapp.yaml",
"semantic_schema": "railiance-master/schemas/rapp.schema.json",
"index_and_resolution": "repo-manager",
"transport_and_cross_repository_query": "hub-core"
},
"forbidden_fallbacks": ["repository_name", "owner_repo", "path_segment", "alias"],
"change_policy": {
"patch": "Clarifications and compatible constraint corrections only.",
"minor": "Additive optional transport metadata and diagnostics.",
"major": "Changed identity, authority, resolution, rebuild, cursor, or deletion semantics; removed or renamed fields; or narrowed constraints."
}
}

139
hub_core/contracts/workload_projection/v1_0_0/fixtures/repo-manager-nine-workloads.json Normal file
View file

@ -0,0 +1,139 @@
{
"contract_id": "helixforge.workload-projection-source",
"contract_version": "1.0.0",
"source": {
"system": "repo-manager",
"workload_contract": "helixforge.workload-reference/v1",
"workload_contract_id": "RMGR-CONTRACT-WORKLOAD-REFERENCE-0001",
"producer_revision": "b36b68bc5747aaeea412079c737f9f7e9d4b7dfb"
},
"snapshot": {
"snapshot_id": "9999999999999999999999999999999999999999999999999999999999999999",
"generated_at": "2026-08-22T12:00:00Z",
"source_revision": "b36b68bc5747aaeea412079c737f9f7e9d4b7dfb",
"page_cursor": null,
"next_cursor": null,
"final_page": true,
"total_workload_count": 9
},
"workloads": [
{
"rapp_id": "rapp-issue-core",
"name": "issue-core",
"declaration_repo": "rapp-issue-core",
"declaration_path": "rapp-issue-core/declarations/rapp.yaml",
"source_git_revision": "a78f38cfd8afb29ed23d150a4ea3e3dcd1f35381",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "issue-core",
"readiness_state": "verified",
"data_classification": "confidential",
"criticality": "high",
"deployables": ["issue-core"]
},
{
"rapp_id": "rapp-openbao",
"name": "openbao",
"declaration_repo": "rapp-openbao",
"declaration_path": "rapp-openbao/declarations/rapp.yaml",
"source_git_revision": "6c3012f6bd12d12c88df03de69b07895e8325347",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "railiance-platform",
"readiness_state": "verified",
"data_classification": "restricted",
"criticality": "critical",
"deployables": ["openbao", "openbao-ui-gateway"]
},
{
"rapp_id": "rapp-policy-nexus",
"name": "policy-nexus",
"declaration_repo": "rapp-policy-nexus",
"declaration_path": "rapp-policy-nexus/declarations/rapp.yaml",
"source_git_revision": "41c42e8d1a653af666da2e5e7e008a27464d9b87",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "policy-nexus",
"readiness_state": "verified",
"data_classification": "public",
"criticality": "high",
"deployables": ["policy-nexus-static"]
},
{
"rapp_id": "rapp-postgres",
"name": "postgres",
"declaration_repo": "rapp-postgres",
"declaration_path": "rapp-postgres/declarations/rapp.yaml",
"source_git_revision": "cfc252630c53e87d01eb38b91e1d5b692e72a4b2",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "railiance-platform",
"readiness_state": "verified",
"data_classification": "restricted",
"criticality": "critical",
"deployables": ["platform-pg"]
},
{
"rapp_id": "rapp-qonto",
"name": "qonto",
"declaration_repo": "rapp-qonto",
"declaration_path": "rapp-qonto/declarations/rapp.yaml",
"source_git_revision": "f57e60ad2a41c18f55dd9ee4ec24a56a4e0d9ff2",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "qonto-assistant",
"readiness_state": "verified",
"data_classification": "restricted",
"criticality": "critical",
"deployables": ["rapp-qonto"]
},
{
"rapp_id": "rapp-sbom-nexus",
"name": "sbom-nexus",
"declaration_repo": "rapp-sbom-nexus",
"declaration_path": "rapp-sbom-nexus/declarations/rapp.yaml",
"source_git_revision": "1566bcf69fc0757db5efc67f78b14af10d944c1b",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "sbom-nexus",
"readiness_state": "draft",
"data_classification": "confidential",
"criticality": "high",
"deployables": ["sbom-nexus"]
},
{
"rapp_id": "rapp-secrets-engine",
"name": "secrets-engine",
"declaration_repo": "rapp-secrets-engine",
"declaration_path": "rapp-secrets-engine/declarations/rapp.yaml",
"source_git_revision": "f71131e76b70aad02d32ab46f2d0983f030304a9",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "secrets-engine",
"readiness_state": "retired",
"data_classification": "restricted",
"criticality": "high",
"deployables": ["secrets-engine-cli"]
},
{
"rapp_id": "rapp-tenant-engine",
"name": "tenant-engine",
"declaration_repo": "rapp-tenant-engine",
"declaration_path": "rapp-tenant-engine/declarations/rapp.yaml",
"source_git_revision": "82bbbf78c4159aa5267af683efca75cce7a57c00",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "tenant-engine",
"readiness_state": "draft",
"data_classification": "confidential",
"criticality": "high",
"deployables": ["tenant-engine"]
},
{
"rapp_id": "rapp-user-engine",
"name": "user-engine",
"declaration_repo": "rapp-user-engine",
"declaration_path": "rapp-user-engine/declarations/rapp.yaml",
"source_git_revision": "e599b4f345cdd4725a6d0ee16efd475cf98ea616",
"observed_at": "2026-08-22T12:00:00Z",
"ownership_repo": "user-engine",
"readiness_state": "verified",
"data_classification": "confidential",
"criticality": "high",
"deployables": ["user-engine", "user-engine-pg"]
}
],
"diagnostics": []
}

43
hub_core/contracts/workload_projection/v1_0_0/openapi/workload-projection.openapi.json Normal file
View file

@ -0,0 +1,43 @@
{
"openapi": "3.1.0",
"info": {"title": "HelixForge workload projection", "version": "1.0.0"},
"paths": {
"/ports/projections/workloads": {
"get": {
"operationId": "queryWorkloads",
"x-port-id": "port.projection.query",
"x-direction": "out",
"parameters": [
{"name": "rapp_id", "in": "query", "schema": {"type": "string"}},
{"name": "name", "in": "query", "schema": {"type": "string"}},
{"name": "deployable", "in": "query", "schema": {"type": "string"}},
{"name": "cursor", "in": "query", "schema": {"type": "string"}},
{"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}}
],
"responses": {
"200": {"description": "Stable page of normalized workload records", "content": {"application/json": {"schema": {"$ref": "../schemas/workload-projection.schema.json"}}}},
"400": {"description": "Invalid explicit filter"},
"409": {"description": "Cursor belongs to another generation or filter"},
"503": {"description": "No accepted workload projection is available"}
}
}
},
"/ports/projections/workloads/resolve": {
"get": {
"operationId": "resolveWorkloadReference",
"x-port-id": "port.projection.query",
"x-direction": "out",
"parameters": [
{"name": "rapp_id", "in": "query", "required": true, "schema": {"type": "string"}},
{"name": "name", "in": "query", "required": true, "schema": {"type": "string"}},
{"name": "deployable", "in": "query", "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "Resolved or explicitly unknown reference", "content": {"application/json": {"schema": {"$ref": "../schemas/workload-resolution.schema.json"}}}},
"400": {"description": "Invalid explicit reference"},
"503": {"description": "No accepted workload projection is available"}
}
}
}
}
}

82
hub_core/contracts/workload_projection/v1_0_0/schemas/workload-projection-page.schema.json Normal file
View file

@ -0,0 +1,82 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.helixforge.local/workload-projection/1.0.0/workload-projection-page.schema.json",
"title": "Repo Manager workload projection page",
"type": "object",
"additionalProperties": false,
"required": ["contract_id", "contract_version", "source", "snapshot", "workloads", "diagnostics"],
"properties": {
"contract_id": {"const": "helixforge.workload-projection-source"},
"contract_version": {"const": "1.0.0"},
"source": {"$ref": "#/$defs/source"},
"snapshot": {"$ref": "#/$defs/snapshot"},
"workloads": {"type": "array", "items": {"$ref": "#/$defs/workload"}},
"diagnostics": {"type": "array", "items": {"$ref": "#/$defs/diagnostic"}}
},
"$defs": {
"source": {
"type": "object",
"additionalProperties": false,
"required": ["system", "workload_contract", "workload_contract_id", "producer_revision"],
"properties": {
"system": {"const": "repo-manager"},
"workload_contract": {"const": "helixforge.workload-reference/v1"},
"workload_contract_id": {"const": "RMGR-CONTRACT-WORKLOAD-REFERENCE-0001"},
"producer_revision": {"type": "string", "pattern": "^[a-f0-9]{40,64}$"}
}
},
"snapshot": {
"type": "object",
"additionalProperties": false,
"required": ["snapshot_id", "generated_at", "source_revision", "page_cursor", "next_cursor", "final_page", "total_workload_count"],
"properties": {
"snapshot_id": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
"generated_at": {"$ref": "#/$defs/utcTimestamp"},
"source_revision": {"type": "string", "pattern": "^[a-f0-9]{40,64}$"},
"page_cursor": {"type": ["string", "null"], "maxLength": 1000},
"next_cursor": {"type": ["string", "null"], "maxLength": 1000},
"final_page": {"type": "boolean"},
"total_workload_count": {"type": "integer", "minimum": 0}
}
},
"workload": {
"type": "object",
"additionalProperties": false,
"required": ["rapp_id", "name", "declaration_repo", "declaration_path", "source_git_revision", "observed_at", "ownership_repo", "readiness_state", "data_classification", "criticality", "deployables"],
"properties": {
"rapp_id": {"type": "string", "pattern": "^rapp-[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120},
"name": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120},
"declaration_repo": {"type": "string", "pattern": "^rapp-[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120},
"declaration_path": {"type": "string", "pattern": "^rapp-[a-z0-9]+(?:-[a-z0-9]+)*/declarations/rapp\\.yaml$", "maxLength": 260},
"source_git_revision": {"type": "string", "pattern": "^[a-f0-9]{40,64}$"},
"observed_at": {"$ref": "#/$defs/utcTimestamp"},
"ownership_repo": {"type": ["string", "null"], "minLength": 1, "maxLength": 120},
"readiness_state": {"type": ["string", "null"], "minLength": 1, "maxLength": 80},
"data_classification": {"type": ["string", "null"], "minLength": 1, "maxLength": 80},
"criticality": {"type": ["string", "null"], "minLength": 1, "maxLength": 80},
"deployables": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120}
}
}
},
"diagnostic": {
"type": "object",
"additionalProperties": false,
"required": ["severity", "code", "message"],
"properties": {
"severity": {"enum": ["info", "warning", "error"]},
"code": {"type": "string", "pattern": "^[a-z][a-z0-9_.-]*$", "maxLength": 120},
"message": {"type": "string", "minLength": 1, "maxLength": 1000},
"declaration_path": {"type": "string", "maxLength": 260}
}
},
"utcTimestamp": {
"type": "string",
"format": "date-time",
"pattern": "Z$"
}
}
}

66
hub_core/contracts/workload_projection/v1_0_0/schemas/workload-projection.schema.json Normal file
View file

@ -0,0 +1,66 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.helixforge.local/workload-projection/1.0.0/workload-projection.schema.json",
"title": "Hub workload projection",
"type": "object",
"additionalProperties": false,
"required": ["contract_id", "contract_version", "projection_id", "projection_status", "source_snapshot", "source_checked_at", "rebuilt_at", "content_hash", "workloads", "diagnostics", "next_cursor", "total_workload_count"],
"properties": {
"contract_id": {"const": "helixforge.workload-projection"},
"contract_version": {"const": "1.0.0"},
"projection_id": {"const": "workloads"},
"projection_status": {"enum": ["current", "stale"]},
"source_snapshot": {"$ref": "#/$defs/sourceSnapshot"},
"source_checked_at": {"$ref": "#/$defs/utcTimestamp"},
"rebuilt_at": {"$ref": "#/$defs/utcTimestamp"},
"content_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
"workloads": {"type": "array", "items": {"$ref": "#/$defs/workload"}},
"diagnostics": {"type": "array", "items": {"$ref": "#/$defs/diagnostic"}},
"next_cursor": {"type": ["string", "null"], "maxLength": 1000},
"total_workload_count": {"type": "integer", "minimum": 0}
},
"$defs": {
"sourceSnapshot": {
"type": "object",
"additionalProperties": false,
"required": ["snapshot_id", "source_system", "source_contract", "source_revision", "generated_at"],
"properties": {
"snapshot_id": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
"source_system": {"const": "repo-manager"},
"source_contract": {"const": "helixforge.workload-reference/v1"},
"source_revision": {"type": "string", "pattern": "^[a-f0-9]{40,64}$"},
"generated_at": {"$ref": "#/$defs/utcTimestamp"}
}
},
"workload": {
"type": "object",
"additionalProperties": false,
"required": ["rapp_id", "name", "declaration_repo", "declaration_path", "source_git_revision", "observed_at", "ownership_repo", "readiness_state", "data_classification", "criticality", "deployables"],
"properties": {
"rapp_id": {"type": "string", "pattern": "^rapp-[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120},
"name": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120},
"declaration_repo": {"type": "string", "pattern": "^rapp-[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120},
"declaration_path": {"type": "string", "pattern": "^rapp-[a-z0-9]+(?:-[a-z0-9]+)*/declarations/rapp\\.yaml$", "maxLength": 260},
"source_git_revision": {"type": "string", "pattern": "^[a-f0-9]{40,64}$"},
"observed_at": {"$ref": "#/$defs/utcTimestamp"},
"ownership_repo": {"type": ["string", "null"], "minLength": 1, "maxLength": 120},
"readiness_state": {"type": ["string", "null"], "minLength": 1, "maxLength": 80},
"data_classification": {"type": ["string", "null"], "minLength": 1, "maxLength": 80},
"criticality": {"type": ["string", "null"], "minLength": 1, "maxLength": 80},
"deployables": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120}}
}
},
"diagnostic": {
"type": "object",
"additionalProperties": false,
"required": ["severity", "code", "message"],
"properties": {
"severity": {"enum": ["info", "warning", "error"]},
"code": {"type": "string", "pattern": "^[a-z][a-z0-9_.-]*$", "maxLength": 120},
"message": {"type": "string", "minLength": 1, "maxLength": 1000},
"declaration_path": {"type": "string", "maxLength": 260}
}
},
"utcTimestamp": {"type": "string", "format": "date-time", "pattern": "Z$"}
}
}

65
hub_core/contracts/workload_projection/v1_0_0/schemas/workload-resolution.schema.json Normal file
View file

@ -0,0 +1,65 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.helixforge.local/workload-projection/1.0.0/workload-resolution.schema.json",
"title": "Exact workload reference resolution",
"type": "object",
"additionalProperties": false,
"required": ["contract_id", "contract_version", "status", "reference", "source_snapshot", "content_hash", "projection_status"],
"properties": {
"contract_id": {"const": "helixforge.workload-projection"},
"contract_version": {"const": "1.0.0"},
"status": {"enum": ["resolved", "unknown"]},
"reference": {"$ref": "#/$defs/reference"},
"source_snapshot": {"$ref": "#/$defs/sourceSnapshot"},
"content_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
"projection_status": {"enum": ["current", "stale"]},
"reason": {"enum": ["not_found", "deployable_not_declared"]},
"workload": {"$ref": "#/$defs/workload"}
},
"oneOf": [
{"properties": {"status": {"const": "resolved"}}, "required": ["workload"], "not": {"required": ["reason"]}},
{"properties": {"status": {"const": "unknown"}}, "required": ["reason"], "not": {"required": ["workload"]}}
],
"$defs": {
"reference": {
"type": "object",
"additionalProperties": false,
"required": ["rapp_id", "name"],
"properties": {
"rapp_id": {"type": "string", "pattern": "^rapp-[a-z0-9]+(?:-[a-z0-9]+)*$"},
"name": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
"deployable": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"}
}
},
"sourceSnapshot": {
"type": "object",
"additionalProperties": false,
"required": ["snapshot_id", "source_system", "source_contract", "source_revision", "generated_at"],
"properties": {
"snapshot_id": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
"source_system": {"const": "repo-manager"},
"source_contract": {"const": "helixforge.workload-reference/v1"},
"source_revision": {"type": "string", "pattern": "^[a-f0-9]{40,64}$"},
"generated_at": {"type": "string", "format": "date-time", "pattern": "Z$"}
}
},
"workload": {
"type": "object",
"additionalProperties": false,
"required": ["rapp_id", "name", "declaration_repo", "declaration_path", "source_git_revision", "observed_at", "ownership_repo", "readiness_state", "data_classification", "criticality", "deployables"],
"properties": {
"rapp_id": {"type": "string"},
"name": {"type": "string"},
"declaration_repo": {"type": "string"},
"declaration_path": {"type": "string"},
"source_git_revision": {"type": "string", "pattern": "^[a-f0-9]{40,64}$"},
"observed_at": {"type": "string", "format": "date-time", "pattern": "Z$"},
"ownership_repo": {"type": ["string", "null"]},
"readiness_state": {"type": ["string", "null"]},
"data_classification": {"type": ["string", "null"]},
"criticality": {"type": ["string", "null"]},
"deployables": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string"}}
}
}
}
}

38
hub_core/mcp/server.py
View file

@ -29,6 +29,8 @@ CORE_TOOL_NAMES = frozenset({
"list_domain_repos",
"query_repository_navigation",
"get_repository_navigation_facet",
"query_workloads",
"resolve_workload_reference",
"check_repo_doi",
"get_doi_summary",
"register_service",
@ -344,6 +346,42 @@ class HubCoreMCPServer:
)
)
@register("query_workloads")
def query_workloads(
rapp_id: str | None = None,
name: str | None = None,
deployable: str | None = None,
cursor: str | None = None,
limit: int = 100,
) -> str:
"""Query normalized authoritative workload records without inference."""
return self._json(
self._get(
"/ports/projections/workloads",
{
"rapp_id": rapp_id,
"name": name,
"deployable": deployable,
"cursor": cursor,
"limit": limit,
},
)
)
@register("resolve_workload_reference")
def resolve_workload_reference(
rapp_id: str,
name: str,
deployable: str | None = None,
) -> str:
"""Resolve only an exact rapp/name/deployable reference."""
return self._json(
self._get(
"/ports/projections/workloads/resolve",
{"rapp_id": rapp_id, "name": name, "deployable": deployable},
)
)
@register("check_repo_doi")
def check_repo_doi(repo_slug: str, force_refresh: bool = False) -> str:
return self._json(

55
hub_core/migrations/versions/0004_workload_projection.py Normal file
View file

@ -0,0 +1,55 @@
"""durable authoritative workload projection
Revision ID: 0004_workload_projection
Revises: 0003_repository_navigation
Create Date: 2026-08-23
"""
from typing import Sequence, Union
import sqlalchemy as sa
from alembic import op
from sqlalchemy.dialects import postgresql
revision: str = "0004_workload_projection"
down_revision: Union[str, None] = "0003_repository_navigation"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
op.create_table(
"runtime_workload_projection_state",
sa.Column("projection_id", sa.String(80), primary_key=True),
sa.Column("projection_status", sa.String(20), nullable=False),
sa.Column("snapshot_id", sa.String(64), nullable=False, unique=True),
sa.Column("source_snapshot", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
sa.Column("source_checked_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("rebuilt_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("content_hash", sa.String(64), nullable=False),
sa.Column("workload_count", sa.Integer(), nullable=False),
sa.Column("diagnostics", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
)
op.create_table(
"runtime_workload_projection_records",
sa.Column("rapp_id", sa.String(120), primary_key=True),
sa.Column("name", sa.String(120), primary_key=True),
sa.Column("declaration_repo", sa.String(120), nullable=False),
sa.Column("declaration_path", sa.String(260), nullable=False),
sa.Column("source_git_revision", sa.String(64), nullable=False),
sa.Column("observed_at", sa.String(40), nullable=False),
sa.Column("ownership_repo", sa.String(120), nullable=True),
sa.Column("readiness_state", sa.String(80), nullable=True),
sa.Column("data_classification", sa.String(80), nullable=True),
sa.Column("criticality", sa.String(80), nullable=True),
sa.Column("deployables", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
)
op.create_index(
"ix_runtime_workload_projection_records_declaration_repo",
"runtime_workload_projection_records",
["declaration_repo"],
)
def downgrade() -> None:
op.drop_table("runtime_workload_projection_records")
op.drop_table("runtime_workload_projection_state")

21
hub_core/runtime/app.py
View file

@ -19,6 +19,12 @@ from hub_core.runtime.repository_navigation_routes import (
)
from hub_core.runtime.store import InMemoryPortStore, PortStore
from hub_core.runtime.validation import ContractValidator
from hub_core.runtime.workload_projection import (
WorkloadProjectionClient,
WorkloadProjectionRejected,
WorkloadProjectionService,
)
from hub_core.runtime.workload_projection_routes import create_workload_projection_router
def create_app(
@ -26,6 +32,7 @@ def create_app(
settings: RuntimeSettings | None = None,
port_store: PortStore | None = None,
repo_projection_client: RepoProjectionClient | None = None,
workload_projection_client: WorkloadProjectionClient | None = None,
) -> FastAPI:
resolved_settings = settings or RuntimeSettings.from_env()
resolved_store = port_store or _create_store(resolved_settings)
@ -34,6 +41,10 @@ def create_app(
client=repo_projection_client,
store=resolved_store,
)
workload_projection = WorkloadProjectionService(
client=workload_projection_client,
store=resolved_store,
)
@asynccontextmanager
async def lifespan(_: FastAPI):
@ -44,6 +55,11 @@ def create_app(
# The readiness dependency reports the rejected or absent
# projection while the API remains available for diagnosis.
pass
if workload_projection_client is not None:
try:
await workload_projection.refresh()
except WorkloadProjectionRejected:
pass
yield
if owns_store and (closer := getattr(resolved_store, "aclose", None)):
await closer()
@ -63,6 +79,7 @@ def create_app(
)
app.state.contract_validator = ContractValidator()
app.state.repository_navigation = repository_navigation
app.state.workload_projection = workload_projection
@app.get("/healthz", response_model=HealthResponse, tags=["system"])
async def healthz() -> HealthResponse:
@ -76,6 +93,7 @@ def create_app(
dependency_checks = {
**await resolved_store.readiness_checks(),
**await repository_navigation.readiness_checks(),
**await workload_projection.readiness_checks(),
}
ready = resolved_settings.is_ready(resolved_store.backend_name) and all(
value in {"ok", "not_applicable"} for value in dependency_checks.values()
@ -90,6 +108,9 @@ def create_app(
},
)
# Exact projection routes precede the generic /projections/{projection_id}
# route so Starlette dispatch cannot shadow them.
app.include_router(create_workload_projection_router())
app.include_router(create_ports_router())
app.include_router(create_repository_navigation_router())
app.include_router(create_compatibility_router())

101
hub_core/runtime/postgres_store.py
View file

@ -22,6 +22,7 @@ from hub_core.runtime.models import (
RegistryRegistration,
)
from hub_core.runtime.repository_navigation import NavigationProjection
from hub_core.runtime.workload_projection import WorkloadProjection
from hub_core.runtime.tables import (
compat_api_keys,
compat_hubs,
@ -33,6 +34,8 @@ from hub_core.runtime.tables import (
runtime_repository_navigation_repositories,
runtime_repository_navigation_state,
runtime_registrations,
runtime_workload_projection_records,
runtime_workload_projection_state,
)
@ -61,6 +64,7 @@ class PostgresPortStore:
compat_hubs,
compat_api_keys,
runtime_repository_navigation_state,
runtime_workload_projection_state,
):
await connection.execute(
sa.select(sa.literal(1)).select_from(table).limit(1)
@ -342,6 +346,103 @@ class PostgresPortStore:
)
)
async def get_workload_projection(self) -> WorkloadProjection | None:
async with self.sessions() as session:
state = (
await session.execute(
sa.select(runtime_workload_projection_state).where(
runtime_workload_projection_state.c.projection_id == "workloads"
)
)
).mappings().one_or_none()
if state is None:
return None
rows = (
await session.execute(
sa.select(runtime_workload_projection_records).order_by(
runtime_workload_projection_records.c.rapp_id,
runtime_workload_projection_records.c.name,
)
)
).mappings()
workloads = tuple(
{
"rapp_id": row["rapp_id"],
"name": row["name"],
"declaration_repo": row["declaration_repo"],
"declaration_path": row["declaration_path"],
"source_git_revision": row["source_git_revision"],
"observed_at": row["observed_at"],
"ownership_repo": row["ownership_repo"],
"readiness_state": row["readiness_state"],
"data_classification": row["data_classification"],
"criticality": row["criticality"],
"deployables": list(row["deployables"] or []),
}
for row in rows
)
return WorkloadProjection(
projection_status=state["projection_status"],
source_snapshot=dict(state["source_snapshot"]),
source_checked_at=state["source_checked_at"],
rebuilt_at=state["rebuilt_at"],
content_hash=state["content_hash"],
workloads=workloads,
diagnostics=tuple(state["diagnostics"] or []),
)
async def replace_workload_projection(self, projection: WorkloadProjection) -> None:
values = {
"projection_status": projection.projection_status,
"snapshot_id": projection.source_snapshot["snapshot_id"],
"source_snapshot": projection.source_snapshot,
"source_checked_at": projection.source_checked_at,
"rebuilt_at": projection.rebuilt_at,
"content_hash": projection.content_hash,
"workload_count": len(projection.workloads),
"diagnostics": list(projection.diagnostics),
}
async with self.sessions.begin() as session:
await session.execute(runtime_workload_projection_records.delete())
if projection.workloads:
await session.execute(
runtime_workload_projection_records.insert(),
[dict(workload) for workload in projection.workloads],
)
exists = (
await session.execute(
sa.select(runtime_workload_projection_state.c.projection_id).where(
runtime_workload_projection_state.c.projection_id == "workloads"
)
)
).scalar_one_or_none()
if exists is None:
await session.execute(
runtime_workload_projection_state.insert().values(
projection_id="workloads", **values
)
)
else:
await session.execute(
runtime_workload_projection_state.update()
.where(runtime_workload_projection_state.c.projection_id == "workloads")
.values(**values)
)
async def mark_workload_projection_stale(
self, *, checked_at: datetime, diagnostic: Mapping[str, Any]
) -> None:
async with self.sessions.begin() as session:
await session.execute(
runtime_workload_projection_state.update()
.where(runtime_workload_projection_state.c.projection_id == "workloads")
.values(
projection_status="stale",
source_checked_at=checked_at,
diagnostics=[dict(diagnostic)],
)
)
async def _append_event(
self,
command: EventCommand,

35
hub_core/runtime/store.py
View file

@ -20,6 +20,7 @@ from hub_core.runtime.models import (
RegistryRegistration,
)
from hub_core.runtime.repository_navigation import NavigationProjection
from hub_core.runtime.workload_projection import WorkloadProjection
class PortStore(Protocol):
@ -55,6 +56,14 @@ class PortStore(Protocol):
self, *, checked_at: datetime, diagnostic: Mapping[str, Any]
) -> None: ...
async def get_workload_projection(self) -> WorkloadProjection | None: ...
async def replace_workload_projection(self, projection: WorkloadProjection) -> None: ...
async def mark_workload_projection_stale(
self, *, checked_at: datetime, diagnostic: Mapping[str, Any]
) -> None: ...
class InMemoryPortStore:
"""Deterministic ephemeral backend for local runtime and conformance tests.
@ -72,6 +81,7 @@ class InMemoryPortStore:
self._progress_events: list[dict[str, Any]] = []
self._interaction_events: list[dict[str, Any]] = []
self._repository_navigation: NavigationProjection | None = None
self._workload_projection: WorkloadProjection | None = None
async def readiness_checks(self) -> dict[str, str]:
return {"database": "not_applicable"}
@ -174,6 +184,31 @@ class InMemoryPortStore:
diagnostics=(deepcopy(dict(diagnostic)),),
)
async def get_workload_projection(self) -> WorkloadProjection | None:
async with self._lock:
return deepcopy(self._workload_projection)
async def replace_workload_projection(self, projection: WorkloadProjection) -> None:
async with self._lock:
self._workload_projection = deepcopy(projection)
async def mark_workload_projection_stale(
self, *, checked_at: datetime, diagnostic: Mapping[str, Any]
) -> None:
async with self._lock:
current = self._workload_projection
if current is None:
return
self._workload_projection = WorkloadProjection(
projection_status="stale",
source_snapshot=deepcopy(current.source_snapshot),
source_checked_at=checked_at,
rebuilt_at=current.rebuilt_at,
content_hash=current.content_hash,
workloads=deepcopy(current.workloads),
diagnostics=(deepcopy(dict(diagnostic)),),
)
async def _append_event(
self,
command: EventCommand,

30
hub_core/runtime/tables.py
View file

@ -98,6 +98,36 @@ runtime_repository_navigation_facets = sa.Table(
sa.Column("repository_ids", sa.JSON(), nullable=False),
)
runtime_workload_projection_state = sa.Table(
"runtime_workload_projection_state",
runtime_metadata,
sa.Column("projection_id", sa.String(80), primary_key=True),
sa.Column("projection_status", sa.String(20), nullable=False),
sa.Column("snapshot_id", sa.String(64), nullable=False, unique=True),
sa.Column("source_snapshot", sa.JSON(), nullable=False),
sa.Column("source_checked_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("rebuilt_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("content_hash", sa.String(64), nullable=False),
sa.Column("workload_count", sa.Integer(), nullable=False),
sa.Column("diagnostics", sa.JSON(), nullable=False),
)
runtime_workload_projection_records = sa.Table(
"runtime_workload_projection_records",
runtime_metadata,
sa.Column("rapp_id", sa.String(120), primary_key=True),
sa.Column("name", sa.String(120), primary_key=True),
sa.Column("declaration_repo", sa.String(120), nullable=False, index=True),
sa.Column("declaration_path", sa.String(260), nullable=False),
sa.Column("source_git_revision", sa.String(64), nullable=False),
sa.Column("observed_at", sa.String(40), nullable=False),
sa.Column("ownership_repo", sa.String(120), nullable=True),
sa.Column("readiness_state", sa.String(80), nullable=True),
sa.Column("data_classification", sa.String(80), nullable=True),
sa.Column("criticality", sa.String(80), nullable=True),
sa.Column("deployables", sa.JSON(), nullable=False),
)
compat_hubs = sa.Table(
"compat_hubs",
runtime_metadata,

421
hub_core/runtime/workload_projection.py Normal file
View file

@ -0,0 +1,421 @@
from __future__ import annotations
import asyncio
import base64
import hashlib
import json
import re
from collections.abc import Mapping
from copy import deepcopy
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any, Literal, Protocol
from jsonschema import Draft202012Validator, FormatChecker, ValidationError
from hub_core.contracts import (
WORKLOAD_PROJECTION_CONTRACT_ID,
WORKLOAD_PROJECTION_CONTRACT_VERSION,
workload_projection_contract_root,
)
class WorkloadProjectionClient(Protocol):
"""Injected `port.repo` workload reader with transport owned by the host."""
async def fetch_workload_page(self, cursor: str | None) -> Mapping[str, Any]: ...
class WorkloadProjectionStore(Protocol):
async def get_workload_projection(self) -> WorkloadProjection | None: ...
async def replace_workload_projection(self, projection: WorkloadProjection) -> None: ...
async def mark_workload_projection_stale(
self, *, checked_at: datetime, diagnostic: Mapping[str, Any]
) -> None: ...
class WorkloadProjectionRejected(ValueError):
"""The authoritative workload transfer cannot safely replace the projection."""
class WorkloadCursorMismatch(ValueError):
"""A cursor does not belong to the active workload generation and filters."""
@dataclass(frozen=True, slots=True)
class WorkloadProjection:
projection_status: Literal["current", "stale"]
source_snapshot: dict[str, Any]
source_checked_at: datetime
rebuilt_at: datetime
content_hash: str
workloads: tuple[dict[str, Any], ...]
diagnostics: tuple[dict[str, Any], ...] = ()
def to_contract(self) -> dict[str, Any]:
return {
"contract_id": WORKLOAD_PROJECTION_CONTRACT_ID,
"contract_version": WORKLOAD_PROJECTION_CONTRACT_VERSION,
"projection_id": "workloads",
"projection_status": self.projection_status,
"source_snapshot": deepcopy(self.source_snapshot),
"source_checked_at": _utc(self.source_checked_at),
"rebuilt_at": _utc(self.rebuilt_at),
"content_hash": self.content_hash,
"workloads": deepcopy(list(self.workloads)),
"diagnostics": deepcopy(list(self.diagnostics)),
"next_cursor": None,
"total_workload_count": len(self.workloads),
}
@dataclass(frozen=True, slots=True)
class WorkloadRefreshResult:
status: Literal["accepted", "duplicate"]
snapshot_id: str
content_hash: str
workload_count: int
class WorkloadProjectionService:
"""Materialize and resolve normalized Repo Manager workload records."""
def __init__(
self,
*,
client: WorkloadProjectionClient | None,
store: WorkloadProjectionStore,
) -> None:
self.client = client
self.store = store
self._validator = _input_validator()
self._lock = asyncio.Lock()
async def readiness_checks(self) -> dict[str, str]:
if self.client is None:
return {"workload_projection": "not_applicable"}
projection = await self.store.get_workload_projection()
if projection is None:
return {"workload_projection": "unavailable"}
return {
"workload_projection": (
"ok" if projection.projection_status == "current" else "stale"
)
}
async def refresh(self) -> WorkloadRefreshResult:
if self.client is None:
raise RuntimeError("no port.repo workload projection client is configured")
async with self._lock:
checked_at = _now()
try:
pages = await self._fetch_transfer()
return await self._apply_transfer(pages, checked_at=checked_at)
except asyncio.CancelledError:
raise
except Exception as exc:
diagnostic = {
"severity": "error",
"code": "workload_projection.rejected",
"message": str(exc)[:1000] or type(exc).__name__,
}
await self.store.mark_workload_projection_stale(
checked_at=checked_at, diagnostic=diagnostic
)
if isinstance(exc, WorkloadProjectionRejected):
raise
raise WorkloadProjectionRejected(diagnostic["message"]) from exc
async def query(
self,
*,
rapp_id: str | None = None,
name: str | None = None,
deployable: str | None = None,
cursor: str | None = None,
limit: int = 100,
) -> dict[str, Any] | None:
if not 1 <= limit <= 500:
raise ValueError("limit must be between 1 and 500")
filters = _filters(rapp_id=rapp_id, name=name, deployable=deployable)
projection = await self.store.get_workload_projection()
if projection is None:
return None
filter_hash = _hash(filters)
generation_id = _hash(
[projection.source_snapshot["snapshot_id"], projection.content_hash]
)
offset = (
_decode_cursor(cursor, generation_id, filter_hash)
if cursor
else 0
)
matches = tuple(
record for record in projection.workloads if _matches(record, filters)
)
if offset > len(matches):
raise WorkloadCursorMismatch("cursor offset exceeds the result set")
page = matches[offset : offset + limit]
next_offset = offset + len(page)
result = projection.to_contract()
result["workloads"] = deepcopy(list(page))
result["total_workload_count"] = len(matches)
result["next_cursor"] = (
_encode_cursor(next_offset, generation_id, filter_hash)
if next_offset < len(matches)
else None
)
return result
async def resolve(
self, *, rapp_id: str, name: str, deployable: str | None = None
) -> dict[str, Any] | None:
filters = _filters(rapp_id=rapp_id, name=name, deployable=deployable)
projection = await self.store.get_workload_projection()
if projection is None:
return None
reference = {"rapp_id": rapp_id, "name": name}
if deployable is not None:
reference["deployable"] = deployable
exact = [
record
for record in projection.workloads
if record["rapp_id"] == rapp_id and record["name"] == name
]
metadata = {
"contract_id": WORKLOAD_PROJECTION_CONTRACT_ID,
"contract_version": WORKLOAD_PROJECTION_CONTRACT_VERSION,
"reference": reference,
"source_snapshot": deepcopy(projection.source_snapshot),
"content_hash": projection.content_hash,
"projection_status": projection.projection_status,
}
if len(exact) != 1:
return {**metadata, "status": "unknown", "reason": "not_found"}
workload = exact[0]
if deployable is not None and deployable not in workload["deployables"]:
return {
**metadata,
"status": "unknown",
"reason": "deployable_not_declared",
}
assert _matches(workload, filters)
return {**metadata, "status": "resolved", "workload": deepcopy(workload)}
async def _fetch_transfer(self) -> list[dict[str, Any]]:
assert self.client is not None
pages: list[dict[str, Any]] = []
cursor: str | None = None
seen: set[str] = set()
while True:
raw = dict(await self.client.fetch_workload_page(cursor))
try:
self._validator.validate(raw)
except ValidationError as exc:
location = ".".join(str(part) for part in exc.absolute_path) or "root"
raise WorkloadProjectionRejected(
f"invalid workload page at {location}: {exc.message}"
) from exc
pages.append(raw)
snapshot = raw["snapshot"]
next_cursor = snapshot["next_cursor"]
if snapshot["final_page"] != (next_cursor is None):
raise WorkloadProjectionRejected(
"final_page must be true exactly when next_cursor is null"
)
if snapshot["final_page"]:
return pages
if next_cursor in seen:
raise WorkloadProjectionRejected("workload projection cursor cycle detected")
seen.add(next_cursor)
cursor = next_cursor
if len(pages) >= 10000:
raise WorkloadProjectionRejected("workload transfer exceeds 10000 pages")
async def _apply_transfer(
self, pages: list[dict[str, Any]], *, checked_at: datetime
) -> WorkloadRefreshResult:
workloads = _validate_and_normalize(pages)
first = pages[0]
snapshot = first["snapshot"]
current = await self.store.get_workload_projection()
duplicate = bool(
current and current.source_snapshot["snapshot_id"] == snapshot["snapshot_id"]
)
if (
current
and not duplicate
and _parse_time(snapshot["generated_at"])
<= _parse_time(current.source_snapshot["generated_at"])
):
raise WorkloadProjectionRejected(
"workload snapshot is older than the active generation"
)
content_hash = _hash(list(workloads))
if duplicate and current and content_hash != current.content_hash:
raise WorkloadProjectionRejected(
"snapshot_id was reused with different workload content"
)
projection = WorkloadProjection(
projection_status="current",
source_snapshot={
"snapshot_id": snapshot["snapshot_id"],
"source_system": "repo-manager",
"source_contract": first["source"]["workload_contract"],
"source_revision": snapshot["source_revision"],
"generated_at": snapshot["generated_at"],
},
source_checked_at=checked_at,
rebuilt_at=_now(),
content_hash=content_hash,
workloads=workloads,
)
await self.store.replace_workload_projection(projection)
return WorkloadRefreshResult(
status="duplicate" if duplicate else "accepted",
snapshot_id=snapshot["snapshot_id"],
content_hash=content_hash,
workload_count=len(workloads),
)
def _input_validator() -> Draft202012Validator:
resource = workload_projection_contract_root().joinpath(
"schemas", "workload-projection-page.schema.json"
)
schema = json.loads(resource.read_text(encoding="utf-8"))
Draft202012Validator.check_schema(schema)
return Draft202012Validator(schema, format_checker=FormatChecker())
def _validate_and_normalize(
pages: list[dict[str, Any]],
) -> tuple[dict[str, Any], ...]:
if not pages:
raise WorkloadProjectionRejected("workload transfer contains no pages")
first = pages[0]
keys = (
"snapshot_id",
"generated_at",
"source_revision",
"total_workload_count",
)
expected = {key: first["snapshot"][key] for key in keys}
source = first["source"]
previous_cursor: str | None = None
records: list[dict[str, Any]] = []
identities: set[tuple[str, str]] = set()
deployables: set[str] = set()
for index, page in enumerate(pages):
snapshot = page["snapshot"]
if any(snapshot[key] != value for key, value in expected.items()):
raise WorkloadProjectionRejected("workload snapshot metadata changed between pages")
if page["source"] != source:
raise WorkloadProjectionRejected("workload source metadata changed between pages")
if snapshot["page_cursor"] != previous_cursor:
raise WorkloadProjectionRejected(f"page {index} does not match requested cursor")
if any(item["severity"] == "error" for item in page["diagnostics"]):
raise WorkloadProjectionRejected("workload transfer contains an error diagnostic")
previous_cursor = snapshot["next_cursor"]
for raw in page["workloads"]:
record = deepcopy(raw)
identity = (record["rapp_id"], record["name"])
if identity in identities:
raise WorkloadProjectionRejected(f"duplicate workload reference {identity!r}")
if record["declaration_repo"] != record["rapp_id"]:
raise WorkloadProjectionRejected(
f"declaration repository does not match {record['rapp_id']}"
)
expected_path = f"{record['declaration_repo']}/declarations/rapp.yaml"
if record["declaration_path"] != expected_path:
raise WorkloadProjectionRejected(
f"declaration path is not canonical for {record['rapp_id']}"
)
overlap = deployables.intersection(record["deployables"])
if overlap:
raise WorkloadProjectionRejected(
f"deployable belongs to more than one workload: {sorted(overlap)[0]}"
)
identities.add(identity)
deployables.update(record["deployables"])
record["deployables"] = sorted(record["deployables"])
records.append(record)
normalized = tuple(sorted(records, key=lambda item: (item["rapp_id"], item["name"])))
if len(normalized) != expected["total_workload_count"]:
raise WorkloadProjectionRejected("total_workload_count does not match records")
if list(normalized) != records:
raise WorkloadProjectionRejected("workloads are not ordered by exact reference")
return normalized
def _filters(
*, rapp_id: str | None, name: str | None, deployable: str | None
) -> dict[str, str]:
values = {"rapp_id": rapp_id, "name": name, "deployable": deployable}
for key, value in values.items():
if value is None:
continue
pattern = r"rapp-[a-z0-9]+(?:-[a-z0-9]+)*" if key == "rapp_id" else r"[a-z0-9]+(?:-[a-z0-9]+)*"
if len(value) > 120 or re.fullmatch(pattern, value) is None:
raise ValueError(f"invalid {key}")
return {key: value for key, value in values.items() if value is not None}
def _matches(record: Mapping[str, Any], filters: Mapping[str, str]) -> bool:
return all(
(value in record["deployables"] if key == "deployable" else record[key] == value)
for key, value in filters.items()
)
def _encode_cursor(offset: int, generation_id: str, filter_hash: str) -> str:
payload = json.dumps(
{"generation_id": generation_id, "filter_hash": filter_hash, "offset": offset},
sort_keys=True,
separators=(",", ":"),
).encode()
encoded = base64.urlsafe_b64encode(payload).decode().rstrip("=")
checksum = hashlib.sha256(b"workload-projection/1.0.0:" + payload).hexdigest()
return f"{encoded}.{checksum}"
def _decode_cursor(cursor: str, generation_id: str, filter_hash: str) -> int:
try:
encoded, checksum = cursor.split(".", 1)
payload = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4))
expected = hashlib.sha256(b"workload-projection/1.0.0:" + payload).hexdigest()
value = json.loads(payload)
if checksum != expected:
raise ValueError("checksum")
if value["generation_id"] != generation_id or value["filter_hash"] != filter_hash:
raise ValueError("generation or filters")
offset = int(value["offset"])
if offset < 0:
raise ValueError("offset")
return offset
except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
raise WorkloadCursorMismatch(
"cursor_snapshot_mismatch: restart from the first page"
) from exc
def _hash(value: Any) -> str:
encoded = json.dumps(value, sort_keys=True, separators=(",", ":")).encode()
return hashlib.sha256(encoded).hexdigest()
def _parse_time(value: str) -> datetime:
return datetime.fromisoformat(value.replace("Z", "+00:00"))
def _utc(value: datetime) -> str:
if value.tzinfo is None:
value = value.replace(tzinfo=timezone.utc)
normalized = value.astimezone(timezone.utc)
return normalized.isoformat().replace("+00:00", "Z")
def _now() -> datetime:
return datetime.now(timezone.utc)

77
hub_core/runtime/workload_projection_routes.py Normal file
View file

@ -0,0 +1,77 @@
from __future__ import annotations
from typing import Any
from fastapi import APIRouter, Depends, HTTPException, Query, Request
from hub_core.runtime.workload_projection import (
WorkloadCursorMismatch,
WorkloadProjectionService,
)
def get_workload_projection_service(request: Request) -> WorkloadProjectionService:
return request.app.state.workload_projection
def create_workload_projection_router() -> APIRouter:
router = APIRouter(prefix="/ports/projections/workloads")
@router.get(
"",
response_model=dict[str, Any],
tags=["workload-projection"],
openapi_extra={"x-port-id": "port.projection.query", "x-direction": "out"},
)
async def query_workloads(
rapp_id: str | None = None,
name: str | None = None,
deployable: str | None = None,
cursor: str | None = None,
limit: int = Query(default=100, ge=1, le=500),
service: WorkloadProjectionService = Depends(get_workload_projection_service),
) -> dict[str, Any]:
try:
result = await service.query(
rapp_id=rapp_id,
name=name,
deployable=deployable,
cursor=cursor,
limit=limit,
)
except WorkloadCursorMismatch as exc:
raise HTTPException(status_code=409, detail=str(exc)) from exc
except ValueError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
return _available(result)
@router.get(
"/resolve",
response_model=dict[str, Any],
tags=["workload-projection"],
openapi_extra={"x-port-id": "port.projection.query", "x-direction": "out"},
)
async def resolve_workload(
rapp_id: str,
name: str,
deployable: str | None = None,
service: WorkloadProjectionService = Depends(get_workload_projection_service),
) -> dict[str, Any]:
try:
result = await service.resolve(
rapp_id=rapp_id, name=name, deployable=deployable
)
except ValueError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc
return _available(result)
return router
def _available(result: dict[str, Any] | None) -> dict[str, Any]:
if result is None:
raise HTTPException(
status_code=503,
detail="no accepted workload projection is available",
)
return result