Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Harden the relay plan against review
Damian Legawiecd22cb183af0c
diff --git a/docs/plans/6.1-marketplace-message-relay.md b/docs/plans/6.1-marketplace-message-relay.mdindex a4647979ac..57c2fcdc79 100644--- a/docs/plans/6.1-marketplace-message-relay.md+++ b/docs/plans/6.1-marketplace-message-relay.md@@ -52,23 +52,34 @@ already carrying the marketplace core.off it. A per-message alias would multiply the addresses a leak couldexpose and give the buyer a different reply-to every time.-4. **A thread is bound to an order and expires with it.** Relay is for+4. **The thread's own relay domain is stored on it, not read live.** A store+ that changes its relay domain would otherwise orphan every alias already+ in the wild — the buyer replies to an address the resolver no longer+ recognises. The thread records the domain it was opened under, and+ inbound accepts a token against the domain it was issued for.++5. **Expiry is a time, and inbound enforces it.** `closes_at` is what closes+ a thread, not a `status` column that something has to remember to write.+ Inbound checks the clock; a job flipping statuses is a convenience for+ the UI, never the gate.++6. **A thread is bound to an order and expires with it.** Relay is for"where is my parcel", not a general channel — it opens when the order isplaced and closes a fixed window after the order is fulfilled or canceled.An alias that never expires is a permanent forwarding address to acustomer's inbox.-5. **Inbound is provider-agnostic.** Action Mailbox's own ingresses+7. **Inbound is provider-agnostic.** Action Mailbox's own ingresses(Mailgun, Mandrill, Postmark, SendGrid, and the generic `relay` for aself-hosted MTA) are the supported surface. Spree registers a mailbox anddocuments the ingress choice; it does not wrap or prefer one provider.-6. **The relay is optional and off by default.** A store preference, and an+8. **The relay is optional and off by default.** A store preference, and aninstallation that has not configured inbound mail simply does not offerit — the seller order keeps the shipping phone it already has. Nothing infulfillment may depend on the relay existing.-7. **Messages are stored, not merely forwarded.** The marketplace is the one+9. **Messages are stored, not merely forwarded.** The marketplace is the onewho has to answer "what did the seller tell my customer" in a dispute.A forward-only relay leaves the operator with nothing to look at.@@ -77,27 +88,44 @@ already carrying the marketplace core.### Models- `Spree::MessageThread` — `store_id`, `order_id`, `seller_id`, `token`- (`has_secure_token`), `status` (`open` | `closed`), `closes_at`.-- `Spree::Message` — `message_thread_id`, `sender_type` (`customer` |- `seller` | `operator`), `sender_id`, `body`, `delivered_at`.+ (`has_secure_token`), `relay_domain`, `closes_at`. Unique on `token`, and+ unique on `(order_id, seller_id)` so a second thread cannot open for a pair+ that already has one.+- `Spree::Message` — `message_thread_id`, `store_id`, `sender_type`+ (`customer` | `seller` | `operator`), `sender_id`, `body`,+ `inbound_message_id` (unique, nullable), `delivered_at`.-Both `Spree::SingleStoreResource`. `status` is a plain `has_status`, moved by-workflows, per `6.0-service-workflows.md` — no state machine.+Both `Spree::SingleStoreResource`, so both carry `store_id`.++`inbound_message_id` is the sender's `Message-ID`: a provider that retries a+webhook must not deliver the same reply twice, and a unique index is the only+thing that actually holds under a retry.++Note the order the thread binds to is the **seller's child order**, not the+order group — a basket spanning several sellers is several orders, and a+thread that spanned them would show one seller another seller's buyer.### Outbound-`Spree::MessageMailer` sends the body to the counterparty with-`reply_to: "#{thread.token}@#{store.preferred_relay_domain}"`. The `from` is-the marketplace's own address, as every other Spree email is.+`Spree::MessageMailer` sends the body to the counterparty from the thread's+own alias — `#{thread.token}@#{thread.relay_domain}` — in both `from` and+`reply_to`. Decision 1 is why `from` is the alias rather than the+marketplace's usual address: a `from` that carried the sender's real address+would mask nothing, whatever `reply_to` said.### Inbound`Spree::RelayMailbox` routes on the alias:-- resolve the thread by token; unknown or closed token is dropped, never- bounced (a bounce confirms to a guesser which aliases exist)+- resolve the thread by token *and* the domain the alias was issued for;+ unknown, expired (`closes_at` in the past) or unmatched is dropped, never+ bounced — a bounce confirms to a guesser which aliases exist- identify the sender by the envelope against the thread's two participants;- a third party is dropped+ a third party is dropped. The envelope is a claim, not proof: an alias that+ leaks is repliable by anyone who spoofs the address, which is why the+ window is short and the alias is per-thread+- drop a `Message-ID` already stored, so a provider's retry does not deliver+ the reply twice- store the message, then mail the counterparty### API and panel@@ -123,6 +151,13 @@ the marketplace's own address, as every other Spree email is.and a seller must be able to ship without it.- A relay alias is never derived from anything guessable.+## Retention++Message bodies are personal data about two identified people. The plan is that+they live as long as the dispute window the operator needs them for, and a+store preference sets it; a job deletes past it. Deciding that window is the+operator's, but core must not leave the default as "forever".+## Open Questions- Whether the operator should be able to *post* into a thread or only read it.