User Settings

User Settings

Edge adaptation of the upstream namespace-based settings system.

Upstream reference: User Settings

What Upstream Provides

The settings system organizes configuration by namespace. Each plugin registers a schemastery schema via ctx.settings.register(), getting a SettingsScope handle for get/watch/update/replace. Values resolve through three layers: schema defaults → composition base → user overrides. The abstract SettingsProvider seam (ctx.settings) handles document persistence; the settings service handles namespace registration, schema validation, and change events.

What Edge Changed

Direct Reuse Settings service

The upstream settings service (ctx.settings) is used as-is. Namespace registration, three-layer resolution, get()/watch()/update()/replace(), and change events (settings/document-updated, settings/updated) are entirely upstream code.

Replacement Settings provider → DO KV

DurableObjectSettingsProvider extends the upstream SettingsProvider abstract class. Persists the entire settings document as a single DO KV entry at dsh-edge:settings-document. Implements load() (read from KV on startup) and persist() (write to KV on change). Reports writable: true and hasDocument based on whether a stored document exists.

What Edge Did NOT Change

• Namespace registration and schema validation
• Three-layer resolution (defaults → base → user)
• Serialized write ordering within namespaces
• Change event semantics (settings/document-updated vs settings/updated)
• Settings RPC (describe/update/replace/mutate) — handled by apiproxy
• Secret role handling — secret values never appear in responses

Performance Characteristics

Settings read/write

The settings document is loaded once at DO initialization and cached in memory. Reads are O(1) from cache. Writes serialize the full document to a single storage.put() call. Since settings changes are infrequent (user-initiated via the UI), the single-document approach has no practical performance concern.

Architecture Summary

Component	Category	Edge Code
Settings service	Reuse	Upstream — namespace registration, resolution, events
DurableObjectSettingsProvider	Replace	~30 lines — extends SettingsProvider, persists to DO KV

Key observation: The settings provider is a textbook minimal replacement — extends the upstream abstract class, implements two methods (load and persist), and delegates everything else to upstream. The entire settings UI, namespace system, and validation are upstream.