Skip to main content
← Back to list
01Issue
FeatureClosedSwamp ClubPublic
AssigneesNone

Relationships

#3164 Docs: document DatastoreSyncService.fetchContent in the datastore provider reference

Opened by zack · 10/7/2026

What changed

swamp-club#3159 adds an optional method to the DatastoreSyncService contract that extension datastores implement:

fetchContent(relPath, options) returns the bytes of one file as the remote holds it, or null when the remote has no such file. It writes nothing to the local cache.

Page to update

content/manual/reference/extensions/datastore-provider.md. Its sync service method table lists hydrateFile but has no row for fetchContent.

Suggested content

A table row: fetchContent, signature (relPath: string, options?: DatastoreSyncOptions) => Promise of Uint8Array or null, not required, reads one remote file without touching the local cache.

A short paragraph with the contract:

  • Returns the file's bytes, or null when the remote has no such file. Any other failure rejects, so an unreachable remote is never read as a deleted file.
  • Writes nothing locally: no cache file, dirty state or pull watermark changes, and a differing local file is left alone.
  • relPath is cache-relative and forward-slash-normalised. With a namespace it already starts with the namespace, so the implementation must not add it again. With no namespace in options, the path is read from the datastore root.
  • A relPath that is absolute or has a dot-dot segment is rejected.
  • The returned bytes are not kept on the service instance.
  • Core treats the method's presence as the capability; there is no SyncCapabilities flag.

Also mention that the round-trip conformance suite in the testing package has two cases for it, fetch-content and fetch-content-namespace, and that the options paragraph on that page should list fetchContent among the methods that take DatastoreSyncOptions.

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

10/8/2026, 6:34:13 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

system commented 10/7/2026, 9:40:07 PM

Classified automatically when this issue was filed.

  • Source: Swamp Club

If you feel this classification is incorrect, add a ripple to tell us so.

stack72 commented 10/8/2026, 6:34:13 PM

Documented in swamp-club PR #1314 (merged). content/manual/reference/extensions/datastore-provider.md: a fetchContent row in the DatastoreSyncService table and a contract paragraph (null only for a missing file and any other failure rejects; writes nothing locally; relPath is cache-relative and already includes the namespace; absolute and dot-dot paths are rejected; bytes are not retained; the method's presence is the capability). fetchContent is added to the DatastoreSyncOptions methods, namespace is added to the options table, and the round-trip conformance cases are listed. The source also has a third case, fetch-content-error (skipped unless the fixture provides failNextFetch), so it is documented alongside fetch-content and fetch-content-namespace.

Sign in to post a ripple.