Digital Twin Service

Implementation reference for the twin-service. For its architectural role, see Digital Twin Service Architecture; for the domain model, see Building Management.

A Rust / Axum service. It is the spatial source of truth: it stores buildings and rooms, and on every change it synchronises a lightweight clone to the dependent services (see Downstream Synchronisation below — the two services that receive that clone, and what happens if sending it fails).

Source Layout

graph TD
    MAIN["main.rs\nentry point"] --> LIB["lib.rs\nbuilds the Router"]
    LIB --> API["api/buildings.rs\nall HTTP handlers"]
    API --> CLAIMS["infra/claims.rs\nGatewayClaims extractor"]
    API --> AUTHZ["infra/authz.rs\nCedar Read/Edit checks"]
    API --> DB["infra/db.rs\nMongo access"]
    API --> OUT["infra/outbound.rs\nsensor/contracts sync"]
    API --> MODELS["models.rs\nBuilding/Room, AppError"]
    LIB --> METRICS["infra/metrics.rs\nPrometheus layer"]
    LIB --> RATE["infra/ratelimit.rs\nper-IP limiter"]
    AUTHZ -.->|"include_str!, compile time"| POLICY["backend/auth-policy\npolicy.cedar + schema"]

Configuration

Data Model

struct Building {
    id: String,        // server-generated UUID (uuid::Uuid::new_v4); unique
    name: String,
    rooms: Vec<Room>,
    domains: Vec<String>,
}

struct Room {
    id: String,         // client-supplied on /register and PUT rooms; server-generated on POST room
    name: String,
    capacity: f64,
    position: Coordinates,     // { x, y, z }
    dimensions: Dimensions,    // { width, height, depth }
    color: Option<String>,
}

• id is generated server-side on POST /register and POST /building/:id/room; a client-supplied id there is ignored. PUT /building/:id/rooms (bulk replace) takes client-supplied room ids.
• The Mongo collection carries a unique index on id and a non-unique index on domains (Building.find({ domains: X }) stays an index seek).
• No internal database fields (_id, a document version, timestamps) leak into API responses — the Building/Room structs only carry fields a client actually reads.

HTTP API

Name Normalisation

Free functions in src/models.rs.

• normalize_building_name(name, id) resolves to the trimmed name, else id, else the literal "Building".
• normalize_room_name(name, id) trims the room name, falling back to the room id.
• Every building load (GET, and every mutating handler’s initial fetch) backfills blank names and persists the fix if anything changed — so a document with a blank name gets healed the next time it’s touched, without a separate migration.

Downstream Synchronisation

A building’s structure is mirrored to two services. The two paths have different failure semantics, which matters operationally.

sequenceDiagram
    autonumber
    participant C as Client
    participant T as twin-service
    participant DB as twin-db
    participant S as sensor-service
    participant K as contracts-service
    C->>T: POST /register { name, rooms, domains }
    Note over T: normalise names, validate geometry, assign UUID
    T->>DB: insert
    T->>S: PUT /thresholds/buildings/:id (clone)
    Note over T,S: fails the registration on a non-2xx response
    T->>K: POST /preferences/init/:id
    Note over T,K: best-effort — errors logged, swallowed
    T-->>C: 201 building

• Sensor threshold clone (sync_building_clone, src/infra/outbound.rs): a PUT carrying { name, rooms: [{ id, name }], maxTemperature? }. Skipped entirely under NODE_ENV=test, and returns an error (failing the building operation) on a non-2xx response. Forwards the caller’s x-gateway-claims header verbatim — sensor-service reads the same mesh-injected identity twin trusts; mTLS already authenticates the hop, the header just carries who the original caller was.
• Contracts preference seeding (init_building_preferences): a POST, best-effort — logged and swallowed on any error, never blocks building creation.

Error Handling

AppError (src/models.rs) implements IntoResponse, mapping to a stable { type, message } JSON shape and status code: Validation → 400, NotFound → 404, Unauthorized → 401, Forbidden → 403. Unexpected errors (a Mongo failure, a Cedar entity-build failure) are logged via log::error! and mapped to a generic 500 — every error is logged, and no internal detail leaks past the generic 500 message.

Metrics

track_metrics is an Axum Router::layer, which wraps the entire request/response cycle regardless of how the inner handler responds — MatchedPath (the route template, e.g. /building/{id}, not the literal path with real ids) is available to layers added this way, so every registered route is observed regardless of the response it produces. Verified live: registering a building and then curling /metrics shows real http_requests_total/http_request_duration_seconds/http_error_requests_total series with the correct method/route/status_code labels.

Cedar Authorization

src/infra/authz.rs embeds the shared backend/auth-policy bundle via include_str! — resolved at compile time, the same way Go’s //go:embed does. Only Python’s binding reads schema.cedarschema/policy.cedar from disk, at process start, since it has no equivalent embed mechanism. Compile-time embedding here means the production Docker image doesn’t need backend/auth-policy present at all; only the builder stage does, since the bytes are already baked into the compiled binary by the time cargo build finishes. See Auth Policy for the full Cedar model (pre-expanded role-tier sets, \.contains() vs in, the golden conformance suite).

twin-service uses two of Cedar’s five shared actions: Read (is_member_of/scope_to_memberships) and Edit (can_edit_domains, tried against every one of a building’s domains — permits if any qualifies). A third function, authorize_any, exists purely so the golden conformance suite can exercise all five actions through this binding too, matching the precedent set by agent-service’s can_override_model.