subduction-policy

Reference for configuring SubductionPolicy authorization hooks controlling peer replication access.

518|49|Updated Apr 7, 2021
One-click install
npx skills add https://github.com/dxos/dxos --skill subduction-policy
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: subduction-policy
Source: https://github.com/dxos/dxos/tree/main/.agents/skills/subduction
Command: npx skills add https://github.com/dxos/dxos --skill subduction-policy

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Designing client-side access control over Subduction-replicated Automerge data is error-prone because the four policy hooks fire at different, non-obvious points in the sync protocol, and older documentation mischaracterized their behavior. This Skill provides the verified, empirically tested reference for exactly where each hook is consulted, what denial does, and how to recover after flipping a policy from deny to allow.

Core Features & Use Cases

  • Hook-by-hook call-site reference: Documents exactly where authorizeConnect, authorizeFetch, authorizePut, and filterAuthorizedFetch fire in the subduction-core source, including the subscriber-only caveat for filterAuthorizedFetch and the local-write bypass of authorizePut.
  • Client-side gating patterns: Explains how to gate inbound replication with authorizePut and outbound serving with authorizeFetch without any server cooperation, using subduction-level Ed25519 peer identities.
  • Recovery and sync-reliability guidance: Covers shareConfigChanged() recovery semantics, the 60-second round timeout amplifier, the O(N²) bulk-sync cliff, connection replacement strategy, and workerd alarm-pump pitfalls via the bundled sync-reliability reference.
  • Use Case: A developer debugging why a document did not replicate to a peer consults this Skill to determine which hook denied the transfer, then applies the documented recovery path (e.g., a fresh holder commit after an authorizePut deny).

Quick Start

Ask the assistant to explain which SubductionPolicy hook to deny in order to stop a specific peer from receiving a specific document, and how to recover after re-allowing it.

Frequently Asked Questions about subduction-policy

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I gate which peers receive my Automerge documents with SubductionPolicy?

Use authorizeFetch to gate outbound serving per peer and per sedimentree; it fires on every batch-sync send_requested_data call. Denial blocks that peer from receiving the document on that sync round, with no server cooperation required.

What is the difference between authorizeFetch and filterAuthorizedFetch?

authorizeFetch gates all outbound data sends during batch-sync rounds, while filterAuthorizedFetch only gates proactive broadcasts of new local commits to explicitly subscribed peers. For most flows, authorizeFetch is the hook that actually fires.

Can I block incoming commits from a specific author with SubductionPolicy?

Yes, authorizePut receives both the immediate sender (requestor) and the original commit signer (author), so you can deny by original author even through a relay. Note it is not called for the holder's own local writes, which bypass policy by design.

Why does a document not recover after I flip authorizePut from deny to allow?

An authorizePut denial leaves a failed entry that shareConfigChanged and transport reconnects do not retry. The only reliable recovery is a fresh commit on the holder, which enqueues a new outbound batch that sidesteps the stuck entry.

Why does Subduction sync stall around 60 seconds and then freeze?

Each sync round has a fire-and-wait 60-second WASM timeout with no abort or re-ask, so any lost frame or slow round costs the full timeout. Combined with O(N²) bulk-sync cost past roughly 2500-4500 documents, rounds exceed the timeout and sync freezes permanently.

Should I drain old connections when replacing a Subduction connection?

No, close or evict the replaced connection immediately. Measured A/B results show immediate close recovers in about 0.3 seconds while any drain window takes about 66 seconds, because the drain itself creates the same-peer sibling condition that strands pending requests.