​

StateSet API → StateSet Sync Server (gRPC) Order Dispatch Flow

​

Goal

​

Key Interfaces (as implemented today)

• Sync Server proto: proto/order_integration.proto (stateset.sync.v1.OrderIntegrationService)
  • Primary RPC: SubmitOrder(SubmitOrderRequest) returns (SubmitOrderResponse)
• Sync Server gRPC server: src/grpc/mod.rs (implements submit_order)
• Sync Server listen port: src/server.rs (server.grpc_port, default 50051)
• Sync Server auth: x-stateset-api-key metadata header (src/http/auth.rs)
• StateSet API durable trigger: outbox enqueue on order create (stateset-api/src/services/orders.rs)
  • Outbox worker: stateset-api/src/events/outbox.rs
  • Event loop hook point: stateset-api/src/events/mod.rs (handle_order_created)

​

High-Level Flow

1. A client creates an order in stateset-api (HTTP or gRPC).
2. stateset-api commits the order + items to its DB and enqueues an OrderCreated outbox row in the same transaction.
3. An outbox worker polls for pending events and triggers a Sync dispatch step.
4. The dispatcher loads the order + items, builds a SubmitOrderRequest, and calls stateset.sync.v1.OrderIntegrationService/SubmitOrder on the Sync Server.
5. The Sync Server validates tenant + API key, then invokes its per-tenant orchestrators to call downstream integrations.
6. On success, the outbox row is marked delivered; on retryable failure, it is rescheduled with backoff.

​

Sequence Diagram

​

Request Construction (what stateset-api sends)

​

Minimal viable request (using existing proto)

• stateset_order (CreateOrderPayload) for “StateSet order create” inside the Sync Server
• netsuite, dcl, cart (all google.protobuf.Struct) for direct downstream submission

​

Mapping from stateset-api order model to CreateOrderPayload

• Order: stateset-api/src/entities/order.rs
• Order items: stateset-api/src/entities/order_item.rs

• shopify_order_id (string)
• order_number (string)
• created_at (google.protobuf.Timestamp)
• line_items[] with title, quantity, price, sku, etc.

• CreateOrderPayload.order_number ← orders.order_number
• CreateOrderPayload.created_at ← orders.created_at (or order_date, choose one consistently)
• OrderLineItem.title ← order_items.name
• OrderLineItem.quantity ← order_items.quantity (convert i32 → f64)
• OrderLineItem.price ← order_items.unit_price (convert Decimal → f64, mind rounding)
• OrderLineItem.sku ← order_items.sku
• CreateOrderPayload.shopify_order_id:
  • If you have a true external/channel order id, use it.
  • If not, use the stateset-api order UUID string as a stable idempotency key.

​

Calling it by hand

grpcurl -plaintext \
  -proto proto/order_integration.proto \
  -H 'x-stateset-api-key: ss_sync_...' \
  -d '{
    "tenant_id": "tnt_4471",
    "order": {
      "shopify_order_id": "0b7f1c62-1f3a-4a5e-9a0c-2f9a1d7b0e11",
      "order_number": "SO-10428",
      "created_at": "2026-08-29T12:00:00Z",
      "line_items": [
        { "sku": "TS-CREW-NAVY-M", "title": "Crew Neck — Navy, M", "quantity": 1, "price": 68.00 }
      ]
    }
  }' \
  sync.internal:50051 stateset.sync.v1.OrderIntegrationService/SubmitOrder

{
  "success": true,
  "results": [
    { "target": "netsuite", "success": true, "external_id": "SO-99120" },
    { "target": "dcl", "success": true, "external_id": "DCL-77341" }
  ],
  "errors": []
}

​

Auth & Tenancy

• Set gRPC metadata header x-stateset-api-key (same key used for the Sync Server’s HTTP API).
• Provide tenant_id in every request; Sync Server resolves tenant configuration and validates the key before executing orchestrators (src/grpc/mod.rs).

​

Delivery Semantics (reliability)

​

Recommended: outbox-driven gRPC dispatch

​

Retry policy

• Retry on transport/transient errors (UNAVAILABLE, DEADLINE_EXCEEDED, timeouts).
• Do not retry on permanent validation errors without operator action (INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED).
• Treat application-level partial failures carefully:
  • SubmitOrder can return OK but success=false with errors[] per integration target (src/grpc/mod.rs).
  • Decide which targets are “required” vs “best-effort” and only consider the outbox event delivered when your required targets succeeded.

​

Observability

• order_id, tenant_id, target grpc_addr
• attempt count + backoff delay
• gRPC status code on failure
• SubmitOrderResponse.success and errors[].target/message on application-level failures

​

Implementation Notes (code placement)

• Add a Sync dispatcher call in stateset-api/src/events/mod.rs inside handle_order_created.
• For true durability, move the gRPC call into the outbox worker path (stateset-api/src/events/outbox.rs) so outbox “delivered” reflects remote delivery rather than local enqueue.

​

Open Questions / Future Improvements

• The current Sync Server gRPC proto is integration-oriented and uses google.protobuf.Struct for downstream payloads. If you want Sync Server to derive NetSuite/DCL/Cart payloads from the canonical stateset-api order model, add a new RPC/message that accepts a first-class “StateSet order” envelope rather than expecting pre-mapped JSON structs.
• TLS: the Sync Server gRPC listener is plaintext by default; deploy behind a TLS-terminating proxy or add tonic TLS configuration if needed.

​

Next steps