Use Case Transactions

1. Status

This document defines target transactional behavior after the breaking model alignment.

The old gateway and client-configuration transactions should be removed during implementation.

2. Create Enrollment Token

Transaction:

1. Resolve tenant context.
2. Check entitlement for max nodes and requested initial capability roles.
3. Create deployment token with token hash.
4. Store node source type and initial capability intent.
5. Return install command with plaintext token once.

3. Edge Runtime Register

Transaction:

1. Lock deployment token.
2. Validate token status and expiry.
3. Validate device identity payload.
4. Create or reuse Node for the same device identity according to token policy.
5. Create or update EdgeRuntime record.
6. Create initial CapabilityBinding rows from token intent.
7. Create initial RuntimeBinding rows when the intent has default runtime mapping.
8. Mark token used.
9. Return node_id, edge_runtime_id, runtime install profiles, and control plane URL.

4. Heartbeat

Transaction:

1. Verify node-scoped Edge Runtime signature.
2. Load Node and EdgeRuntime.
3. Update Node last_seen_at and status.
4. Update RuntimeBinding statuses.
5. Update CapabilityBinding statuses.
6. Store heartbeat errors as safe strings.

5. Publish Desired State

Transaction:

1. Load Node.
2. Load active CapabilityBindings.
3. Load active RuntimeBindings.
4. Load Endpoints, Domains, Certificates, Subscriptions, TrafficPolicies, QuotaEnforcements.
5. Build desired state spec.
6. Compile runtime configurations per RuntimeBinding.
7. Store DesiredState with incremented node-scoped version.
8. Store RuntimeConfiguration rows.
9. Publish desired state.

6. Create Subscription

Transaction:

1. Resolve tenant and user.
2. Check entitlement.
3. Select ready traffic.entry endpoints.
4. Generate stable subscription credential.
5. Store token hash.
6. Create Subscription row.
7. Create SubscriptionEndpoint rows.
8. Publish DesiredState for affected Nodes.
9. Return public subscription URL.

7. Fetch Public Subscription

Transaction:

1. Hash token and find active Subscription.
2. Verify tenant and user are active.
3. Verify entitlement.
4. Verify no blocking quota enforcement applies.
5. Load ready endpoint set.
6. Render requested output format.
7. Update last_used_at.
8. Write usage-neutral access event.

8. Rotate Subscription

Transaction:

1. Lock Subscription.
2. Generate new token.
3. Store new token hash.
4. Keep subscription ID and protocol credential stable unless explicit credential rotation is requested.
5. Return new public URL.

9. Revoke Subscription

Transaction:

1. Lock Subscription.
2. Mark status revoked and set revoked_at.
3. Publish DesiredState for affected Nodes so runtime credentials are removed.

10. Delete Subscription

Transaction:

1. Allow only revoked or disabled subscriptions.
2. Mark deleted_at.
3. Exclude from normal list APIs.

11. Update Traffic Policy

Transaction:

1. Lock TrafficPolicy.
2. Validate DSL.
3. Store policy and rules.
4. Preview affected routes when requested.
5. Determine affected Nodes through traffic.entry runtime bindings.
6. Publish DesiredState for affected Nodes.

12. Report Usage

Transaction:

1. Verify Edge Runtime signature.
2. Validate Node ownership.
3. Validate runtime_binding_id belongs to Node.
4. Map principal key to Subscription.
5. Insert usage samples.
6. Update rollups idempotently or enqueue aggregation.
7. Re-evaluate quota policies.
8. Publish DesiredState when enforcement state changes.

13. Certificate Reconcile

Transaction:

1. Load domains and endpoints requiring TLS.
2. Create or update ACME order.
3. Reconcile DNS challenge.
4. Store certificate metadata and material reference.
5. Update EndpointTLSBinding status.
6. Publish DesiredState for affected Nodes when readiness changes.

14. Concurrency Rules

• Token use locks deployment token rows.
• Subscription rotation locks subscription rows.
• DesiredState version increments are node-scoped and serialized.
• Usage sample ingestion is append-only.
• Quota enforcement changes are idempotent per policy and period.