Cross-domain replication
A consumer doctype can copy a field from a source doctype that lives in another domain. The copy is a local field on the consumer document, filled from the source document it points at. Facet keeps the copy current through the event bus. A domain grant controls what may cross the boundary.
Explanation
Section titled “Explanation”How the copy works
Section titled “How the copy works”The replica field on the consumer doctype carries a replicate config. It
names a local reference field (the via) and the source field to copy. On
create, or when the reference field changes, Facet pulls the initial value
from the source document. After that, every source change propagates. The
handler reads the source’s current value from PostgreSQL. It compares that
value with each consumer’s copy and writes only the difference.
Replica fields are read-only. You cannot write a replica field yourself.
The document write gate rejects the key, and the field cannot be required or
unique.
The copy lags the source. Delivery rides the event bus, so the copy lags the source: it is eventually consistent. Delivery is at-most-once. A lost update waits for the next change to the source document.
Deletion follows a policy. When a source document is deleted, the replica
follows the field’s on_source_delete policy. keep (the default) leaves the
copied value in place. unset clears it on every referencing consumer.
One hop
Section titled “One hop”A replica never feeds another replica. The doctype validator checks the
definition when you save it. It rejects a replica used as a replication
source. It also rejects a via field that is itself a replica. At runtime, the
write that updates a replica carries a reentrant flag. A handler that receives
a reentrant event skips it. The chain stops at one hop, always.
Grants gate the boundary
Section titled “Grants gate the boundary”A cross-domain edge needs an active domain grant, stored under the producer domain. The grant names the consumer domain and the producer resources it may read, at tag grain. Facet re-checks coverage at two points:
| Check | When it runs | Without grant coverage |
|---|---|---|
| Registry build | at server start, and after any doctype or grant change | the binding is dropped, so updates stop |
| Write-time pull | at consumer create, or when the reference field changes | the replica stays null |
Same-domain edges need no grant. A domain reading itself is not a sharing decision.
Revoking a grant stops the updates. When the grant is revoked, the registry drops the binding on its next rebuild. Updates stop. The values already copied stay in place — no sweep deletes them. Reactivation does not backfill. The next change to a referenced source document pushes its current value into the copy. A consumer domain that gains its first binding late replays the retained stream. History then fills the replicas within the stream’s retention.
The limits follow from the design. One hop stops chains: you cannot route a field from A to B to C, even through a computed field. Two consumers of the same source each declare their own edge. And a revoked grant leaves the last copied value in place, so the consumer serves frozen data.
Related
Section titled “Related”- Domains and isolation — why domains stay separate, and what crosses.
- Events and delivery guarantees — the bus that carries replication updates.
- Sharing data across domains — declare the
replicateconfig on a field and grant cross-domain access. - Internals on GitHub: replication.md, domain-grants.md.