Cloud Service Profile conformance

The Cloud Service Profile is Benzene's named conformance target: the operational requirements (R1–R5, R7) a deployable service layers onto the core model — the surfaces any tool can pull from the service itself, with no collector. This port implements all six. The table maps each requirement to the Python API that satisfies it and the test that proves it. Joining a mesh is the separate meshed-service claim (mesh.md §7.1, below); its M1 and M2 were the profile's R6 and R8, ids that are retired and not reused.

The meshed-service claim (M1, M2)

A meshed service (mesh.md §7.1) is a Cloud Service plus:

The self-check reports M1/M2 on report.mesh (mesh_missing, is_meshed), never in missing or the document's profile.missing: a service that does not join a mesh still claims the profile in full. The meshed claim requires the profile — is_meshed is true only when is_conformant is too.

Claiming the profile

A service claims the profile by hosting its handlers behind a transport (R1/R2 — automatic) and wiring the operational surfaces. Over HTTP that is one StandardPaths and a ContractInfo:

from benzene.core import AppDefinition, ContractInfo, HealthChecks
from benzene.http import BenzeneHttpApp, StandardPaths

health = HealthChecks().add("db", check_db)

app = BenzeneHttpApp.from_definition(
    AppDefinition(
        router=router,
        standard_paths=StandardPaths(health=health),   # R3 (topic + route) + R4 + R5's route + R7
        contract=ContractInfo("orders"),               # R5's document
    )
)

A message-only service (a queue consumer, no HTTP surface) meets R3 by intercepting benzene:healthcheck — AppDefinition(middleware=[health_interception(health)], ...) — and needs no /benzene/health; StandardPaths(health=...) on the definition installs the same interception, so an HTTP service declares its health once for both faces.

The same standard_paths= argument works on GcpFunctionsApp, AwsLambdaApp, and AzureFunctionsApp, so a service claims the HTTP surfaces identically whether it runs under ASGI or a cloud function. Add trace_middleware and the MeshFeedSender (registering the same document) to be meshed too (M1/M2) — see joining the mesh.

A service booted from a BenzeneStartUp declares the surfaces once, in the composition root, by returning them on its AppDefinition (alongside router and middleware) — then every host and the test harness pick them up from that one declaration:

class OrdersStartUp(BenzeneStartUp):
    def configure(self, services, config) -> AppDefinition:
        router, outbound = ...   # the handlers, and the events and sends this service declares
        return AppDefinition(
            router=router,
            outbound=outbound,
            standard_paths=StandardPaths(health=health),
            contract=ContractInfo("orders", service_version="1.4.2", version_scheme="semver"),
        )

One document: served and registered

R5's Contract Document is derived from the registrations once, at the composition root, and the mesh registration (M1) reuses it rather than describing the service a second time:

• Served — /benzene/spec and the reserved benzene:spec topic answer with it (contract-document.md): {schemaDialect, service, serviceVersion?, versionScheme?, description?, runtime?, placement?, profile?, degraded?, messageEndpoint?, transports?, contractHash, registrationHash, requests[], events[], sends[], components}, the single input every language's client generator parses. Its schemas are OpenAPI 3.0 Schema Objects with named components. Depends only on benzene-core.
• Registered — the benzene:mesh:register body is that same document (benzene.mesh.registration_document(definition), mesh.md §2). The deployment-side fields (runtime, placement, profile, degraded) are declared on ContractInfo and sit outside both hashes, so the two can never disagree; heartbeats carry its registrationHash.

The self-check's verdict rides on the document's profile (benzene.mesh.declare_cloud_service_profile): {"name": "cloud-service", "missing": [...]}, where missing lists only R1–R5/R7 ids and is omitted when none. The probe audits R5's topic half by invoking benzene:spec over /benzene/invoke, and its HTTP half at /benzene/spec; R3 likewise, by invoking benzene:healthcheck over /benzene/invoke and reading /benzene/health.

Edit this page on GitHub