Part of Stem. This page defines the Sync method of the sync RPC specification. It is the one call a client makes when it shows a resource.

The formal schema is attached as the schemaDefinition of this page: a struct {key, input, output} with key pinned to Sync.

Asks the local daemon to bring a scope up to date now, from the space's authority peers and any peers named by policy. Replaces DiscoverEntity and Subscribe: calling it also marks the scope hot for a short while. Standing interest is expressed in the sync policy, not here.

Input

field	type	required	meaning
`scope`	data/scope	yes	What to sync.
`version`	data/version	no	Stop as soon as this version of the scope's node is held.
`wait`	boolean	no	Block until the run finishes. Default false: start or touch the run and return its status.

Output

The output is rpc/type/sync-status.

Rules

The daemon runs the sync run for scope against the space's authority peers, trusted peers and any peers the matching policy rule names. If a run is already in progress for the scope the call joins it.

With version set, the run stops as soon as the scope's node is held at that version, and returns done without contacting more peers if it already is.

With wait false (the default) the call returns the current status at once; with wait true it returns when the run finishes or fails.

Calling Sync marks the scope hot: the daemon keeps a Watch open on the authority peers for a short period after the last call, and reruns on notifications. It does not change the policy; a client that wants standing interest calls SetPolicy.

A scope whose policy rule is ignore returns failed with an error and runs nothing.

Today (HM24)

HM24 splits this between Entities.DiscoverEntity (hot, polled, with /*, /** and :profile suffixes in the id) and Subscriptions.Subscribe (cold rows, one-minute cadence), both feeding one scheduler; the web app adds a /hm/api/discover route and a JavaScript-gated DiscoveryStatus key. The roadmap asks for one sync API with fine-grained addressing. Sync plus the policy resource is that API; the scope carries the depth and facets the URL suffixes carried.

Example

{"key": "Sync", "input": {"scope": {"space": {"/": {"bytes": "7QEA…"}}, "node": "bafyrein6a6wfhym6l3vfz5zfkkibj5j6wjibagi3mnbqnspuq2idw52ijb", "depth": "subtree"}, "wait": true}}

{"scope": {"space": {"/": {"bytes": "7QEA…"}}, "node": "bafyrein6a6wfhym6l3vfz5zfkkibj5j6wjibagi3mnbqnspuq2idw52ijb", "depth": "subtree"}, "state": "done", "version": "bafy…13", "lastRun": 1759910470000, "peersAsked": 2, "peersOk": 2, "blobsWanted": 2, "blobsReceived": 2, "error": null}

Input

Output

Rules

Today (HM24)

Example

See also