AGENT SKILL

sdk-setup

Ditto SDK setup, lifecycle, and production security (Flutter, JavaScript, Kotlin, Swift): DittoConfig, the authentication expiration handler, system parameters, sync start and stop, close, transports, presence, keys, permissions, revocation. Use when initializing Ditto, writing Ditto login, startup, shutdown, or background code, configuring Ditto transports, reviewing Ditto security, or when Ditto sync never starts or devices do not connect.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 0
Forks
0

01 前言 Front Matter

name
sdk-setup
description
Ditto SDK setup, lifecycle, and production security (Flutter, JavaScript, Kotlin, Swift): DittoConfig, the authentication expiration handler, system parameters, sync start and stop, close, transports, presence, keys, permissions, revocation. Use when initializing Ditto, writing Ditto login, startup, shutdown, or background code, configuring Ditto transports, reviewing Ditto security, or when Ditto sync never starts or devices do not connect.

02 资源文件 3

03 SKILL.md 正文

Ditto SDK Setup, Lifecycle, and Security

Opening Ditto, authenticating, starting and stopping sync, shutting down, transports and presence, and securing a production deployment. Targets Ditto SDK 5.2.0 in every SDK; the code for each SDK is on its page.

Before You Apply

  • Identify the project's SDK and version: Flutter (ditto_live in pubspec.yaml / pubspec.lock), JavaScript (@dittolive/ditto in package.json), Kotlin (com.ditto:ditto-kotlin in Gradle files), or Swift (DittoSwift in Package.swift, Package.resolved, or the Xcode project). These rules target SDK 5.2.0; for devices that still run 5.1.0, also apply § Known Issues in SDK 5.1.0. Note (SDK 5.1.0 and 5.2.0) and Note (SDK 5.1.0) mark easy-to-miss behavior seen on those releases, with the safe pattern; (SDK 5.1+) / (SDK 5.2+) mark features introduced in that release.
  • For API calls, Grep the outline of that SDK's page, ${CLAUDE_SKILL_DIR}/../guide/reference/best-practices/platforms/<sdk>.md (flutter, javascript, kotlin, swift), with ^#{1,3} and read only the section you need, not the whole page; sections are named <Topic> in <SDK>.
  • § <Heading> cites the full guide: Grep the heading as a fixed string in best-practices/ and knowledge/ under ${CLAUDE_SKILL_DIR}/../guide/reference/, then read that section.
  • Report each finding at the severity of its item in § Anti-Pattern Checklist (the checklist decides; Grep a phrase of the item there). The labels below rank the rules, not each item in them.

Prevents

  • A second open of an open persistence directory; a Swift instance released while in use
  • Small-peers-only without a private key; hardcoded keys or tokens; the development token in a release build
  • Errors escaping the authentication expiration handler; unchecked login results
  • System parameters assumed to persist, set with ALTER SYSTEM after open, or changed after sync has started
  • Closing Ditto in the background; a transport configuration built from scratch; TCP hubs with more than six clients
  • Secrets or personal data in peer metadata; presence recorded in documents on every callback
  • Access control via mutable fields, syncGroup, or client checks; revocation checking disabled

Workflow

App startup order (§ Complete app startup; the service for each SDK: App startup in <SDK> on the SDK page):

Startup:
- [ ] 1. Configure the logger before opening (Flutter: await Ditto.init() first)
- [ ] 2. Open the single shared instance with DittoConfig(..., system parameters); share it
- [ ] 3. Server: set the expiration handler | Small peers: setOfflineOnlyLicenseToken(token)
- [ ] 4. CREATE INDEX IF NOT EXISTS ... (skip on in-memory stores)
- [ ] 5. Long-lived ditto.sync.registerSubscription(...)
- [ ] 6. ditto.sync.start()
- [ ] If a step after 2 fails: close the instance, then report the error
- [ ] SDK 5.1: ALTER SYSTEM SET ... after step 3, before step 6
Flutter JavaScript Kotlin Swift
Open await Ditto.open(DittoConfig(...)) await Ditto.open(config) (Web: await init() first) DittoFactory.create(config) try await Ditto.open(config:)
Start sync ditto.sync.start() (void; throws) ditto.sync.start() ditto.sync.start() (throws) try ditto.sync.start()
Login failure AuthResponse.exception; does not throw Result error; does not throw Throws Completion handler error

More: § Platform Differences.

Rules

1. Open Ditto once and share the instance (CRITICAL)

Only one Ditto instance can use a persistence directory at a time. What a second open of an open directory does differs by SDK; never rely on it to fail.

Note (SDK 5.1.0): In Flutter, Ditto.open() on a directory that is already open may never complete instead of throwing.

✅ DO: open at app start and pass the instance through DI or a service; let concurrent callers wait for one pending open (reset it on failure); where a tool restarts your code without ending the process (Flutter hot restart), use a new persistenceDirectory per start in debug builds, and a fixed one in release. ❌ DON'T: open per screen or request; reopen before closing has completed; touch, partly delete, or copy the persistence directory (sync silently diverges); in Swift, hold only ditto.store or ditto.sync (they reference Ditto weakly; without a strong reference the instance shuts down at once).

Flutter: Ditto.open() initializes the SDK (SDK 5.1+); call await Ditto.init() first only before Ditto.openSync(), DittoLogger, or Ditto.defaultRootDirectory, or for custom Web asset URLs.

§ One instance per persistence directory, § Opening Ditto in Flutter, § Opening Ditto in Swift · Example: One shared instance in <SDK> on the SDK page

2. Choose the connection mode deliberately (CRITICAL)

Connection (Flutter name) Use for Peer authentication
Server URL (DittoConfigConnectServer(url: ...)) Production with real users Webhook login; TLS
Small peers with a key (DittoConfigConnectSmallPeersOnly(privateKey: key)) Small peers only (closed networks) Shared key; TLS 1.3
Small peers without a key (the default) Local store tests, development None; documented as unencrypted

✅ DO: copy the Server URL from the Ditto Portal exactly; check no placeholder databaseID remains (open() may not reject it); in small-peers mode pass a base64 P-256 PKCS#8 DER privateKey from secure provisioning (MDM) and call setOfflineOnlyLicenseToken(token) before you start sync; roll out a new key to all devices together. ❌ DON'T: ship the keyless mode; hardcode keys, tokens, or API keys (binaries can be decompiled); use a shared key when you need per-user permissions or single-device revocation.

§ DittoConfig, § Small-Peers-Only Deployments · Code: DittoConfig in <SDK> · Details: reference/security.md

3. Set a non-throwing expiration handler before sync starts (CRITICAL)

With a server connection, starting sync fails until a handler is set. It runs before the first login and when credentials near or pass expiry. How login reports failure differs by SDK (Login failure above): Kotlin throws.

✅ DO: set the handler before you start sync; fetch a fresh token inside it; check the login result the way your SDK reports it; catch your own errors. ❌ DON'T: let an error escape from the handler (Ditto does not receive it, and it becomes unhandled); cache one token for the app's lifetime; ship the development provider or the Portal development token.

auth.logout() stops sync; start it again after the next login. Logout with a cleanup callback (SDK 5.2+) runs after sync stops and may only EVICT; it swallows exceptions, so verify the result.

§ Authentication, § Authentication in Production · Code: Authentication in <SDK> · Details: reference/startup-and-lifecycle.md

4. Pass system parameters in DittoConfig on every open (CRITICAL)

System parameters are in memory only and reset on restart or reopen. The system parameters of DittoConfig (SDK 5.2+) are applied before Ditto starts, so startup-only parameters take effect, and an unknown name or a wrong type makes opening fail. Startup-only parameters set later with ALTER SYSTEM have no effect.

✅ DO: pass the app's settings in one map on every open; use ALTER SYSTEM only to change a value while the app runs; confirm with SHOW <parameter>. On SDK 5.1: ALTER SYSTEM after opening and before sync starts, queries, or observers (subscriptions may come first). ❌ DON'T: run ALTER SYSTEM once in a migration; change DQL_STRICT_MODE (default false) after sync, queries, or observers have run.

§ Applying System Parameters, § System Parameters Reference, § Strict Mode · Code: DittoConfig in <SDK> on the SDK page

5. Start sync after its prerequisites; never close on background (CRITICAL)

Starting sync fails without the expiration handler or license token; it does nothing if already active (sync.isActive). After sync.stop() the local store stays usable, connections close, subscriptions stay registered, and changes sync after start(). Flutter's start() and stop() return void (do not await).

✅ DO: keep Ditto open in the background; if the app must not sync there, stop sync when the app goes to the background and restart on return only the sync you paused. ❌ DON'T: close Ditto when the app goes to the background: closing is final, later calls fail, and every subscription and observer must be re-created.

Background sync: iOS is best-effort and needs the Bluetooth central and peripheral background modes; Android needs Ditto's foreground service in AndroidManifest.xml.

§ Starting and Stopping Sync · Code: Sync and the App Lifecycle in <SDK> on the SDK page

6. Change transports with updateTransportConfig (CRITICAL)

A new, empty transport configuration has every transport disabled, including the peer-to-peer transports a default instance enables. The Server URL is used automatically.

✅ DO: ditto.updateTransportConfig, changing only what you need (all peer-to-peer transports, peerToPeer.bluetoothLE, listen.tcp, connect.tcpServers). ❌ DON'T: assign a fresh transport configuration (Flutter: TransportConfig()); treat global.syncGroup as a security boundary.

Invalid values do not throw; they only log. WebSocket sync between Small Peers is off by default; enable it only with TLS. Use Multicast (Beta) (SDK 5.1+) only with Ditto support.

§ Transport Configuration, § Multicast (Beta) (SDK 5.1+) · Code: Transports and Presence in <SDK> · Details: reference/transports-and-presence.md

7. Raise the TCP connection limit on hubs with more than six clients (CRITICAL)

Note (SDK 5.1.0 and 5.2.0): A device accepts 6 TCP connections by default (MESH_CHOOSER_MAX_WLAN_CONNECTIONS). In testing, extra clients got no data and no API error; only a WARN log ... at capacity for this transport. On 5.2.0, connections it opened itself also count when it accepts one, so a hub that also dials out admits fewer.

✅ DO: on the hub, pass MESH_CHOOSER_MAX_WLAN_CONNECTIONS (for example 12) in the system parameters of DittoConfig on every open (SDK 5.2+); on SDK 5.1, ALTER SYSTEM after opening and before sync starts. ❌ DON'T: raise it after sync started (rejected clients stayed out in testing).

§ Transport Configuration · Details: reference/transports-and-presence.md

8. Keep metadata non-sensitive; record presence sparingly (CRITICAL)

ditto.presence.peerMetadata and the webhook's identityServiceMetadata reach every peer in the mesh.

✅ DO: keep peer metadata small (max 4096 bytes encoded; larger throws), set once at startup; stop() presence observers when their screen goes away. ❌ DON'T: put secrets, tokens, or personal data in either; treat self-set peerMetadata as a security check. Recording presence (HIGH): write a peer only when its stored time is older than the needed precision, in one transaction, not per callback; keep writers of one peer from writing at once (e.g. random timers); never write from the observer that reads the record.

§ Presence, § Recording presence in documents, § Identity metadata is visible to the mesh · Code: Transports and Presence in <SDK> · Details: reference/transports-and-presence.md

9. Enforce access with webhook permissions scoped by _id (CRITICAL)

The webhook returns per-collection read and write rules (each with everything and queriesByCollection) that can reference only _id, in legacy syntax (_id.storeId == 'store-1'; "true" matches all), not DQL.

✅ DO: encode access boundaries (user, store, organization) in a structured _id before shipping; grant the narrowest rules per role; reject unknown users with {"authenticated": false}; keep expirationSeconds moderate so permission changes arrive on re-authentication; account for relaying: peer-to-peer data needs mutual write permission, so read-only roles cannot relay it. ❌ DON'T: rely on mutable fields, syncGroup, sync scopes, or client checks; embed long-lived secrets to mint tokens on the device.

§ Permissions, § Design `_id` for permission scoping, § Write authority and peer-to-peer relaying · Details: reference/security.md

10. Revoke by rejecting in the webhook first (CRITICAL)

Certificate revocation (SDK 5.1+) covers server-authenticated identities only and certificates issued before it; it is permanent.

✅ DO: reject the identity in the webhook, then revoke via the Ditto Server HTTP API; keep PEER_CERTIFICATE_REVOCATION_CHECK_ENABLED enabled (default). ❌ DON'T: disable revocation checking in production; expect revocation with a shared key.

§ Certificate Revocation (SDK 5.1+) · Details: reference/security.md

11. Validate input, protect data at rest, secure the webhook (CRITICAL)

Only Swift and Kotlin can encrypt the local store at rest (SDK 5.2+): a 32-byte key in DittoConfig.encryptionKey on every open, kept in the Keychain or Android Keystore; switching an existing store means deleting it (deleteStore) and syncing again.

✅ DO: validate before writes and pass values as :parameters; treat peer documents as untrusted; without Ditto encryption, rely on OS protection and encrypt sensitive fields in the app (keys in secure storage); serve the webhook over HTTPS, validate tokens, and verify the ditto-signature header. ❌ DON'T: interpolate input into DQL; store tokens or keys in documents.

§ Input Validation and Query Parameters, § Data at Rest, § Webhook Security · Details: reference/security.md

12. Shut down in order, only when the app is done with Ditto (HIGH; CRITICAL in Flutter)

Release observers, subscriptions, presence and transport-condition observers, fetchers, and the connection request handler explicitly. Closing is final, stops sync, and releases resources, but does not wait for unsent changes. In-flight work: Flutter fails pending execute() calls, and stops the isolate if a transaction is open (on 5.2.0, reopening in the same process can also stop: § Changes in SDK 5.2.0); JavaScript and Kotlin wait; Swift has no close() (5.1.0, 5.2.0): releasing the last reference shuts Ditto down and waits for an open transaction. Flutter's close() also does not end changes streams and resets DittoLogger.customLogCallback.

✅ DO: await pending work (if data must reach a peer, its confirmed commit ID), release observers, then close. A growing count in ditto.store.observers across screens reveals observers never released. ❌ DON'T: rely on garbage collection; send the Flutter Ditto or Store to another isolate.

§ Resource Cleanup and Shutdown, § Forwarding logs to your own pipeline · Code: Closing Ditto in <SDK> on the SDK page

13. Filter connections with a fast, non-throwing handler (MEDIUM; CRITICAL in Kotlin)

ditto.presence.connectionRequestHandler returns allow or deny within 10 s, or the peer is rejected; catch every error (a throw ends a Kotlin app).

✅ DO: catch errors and return deny at once; keep permissions as the primary control.

§ Controlling Incoming Connections · Code: Transports and Presence in <SDK> · Details: reference/security.md

14. Plan for platform requirements and Web limits (MEDIUM)

Pin the exact SDK version; request Bluetooth, Wi-Fi, local network, and nearby-device permissions before sync. Android, SDK 5.2+: multicast permissions are requested separately. Flutter 5.2: the root is application support, also for a relative persistenceDirectory, so pass the absolute 5.1 path or 5.1 data is not found. Flutter Web and the JavaScript SDK in browsers: in-memory store, no indexes; Flutter Web syncs only over WebSocket with Ditto Server.

§ Requirements, § DittoConfig, § Upgrading from SDK 5.1 · Code: Installing the <SDK> SDK · Details: reference/startup-and-lifecycle.md

Diagnose: Sync Never Starts or Devices Do Not Connect

Symptom Cause
Opening fails with system parameters Unknown name or wrong type (rule 4)
start(): "an authentication expiration handler has not yet been set" No handler (rule 3)
start(): "...not yet activated" No offline license token (small peers)
"The license failed verification" setOfflineOnlyLicenseToken fails: invalid token; a peer without a valid token is invisible
Server login fails silently Unchecked login result (rule 3)
Sync stopped after sign-out logout() stops sync
WARN BadSignature / DecryptError Mismatched shared keys
WARN at capacity for this transport Hub TCP limit (rule 7)
No peers, no error Fresh transport configuration, missing permissions, radios off: observe transport conditions; check Android permissions (SDK 5.1+)
TRANSPORTS_DISCOVERED_PEERS connects nothing LAN transport disabled; use connect.tcpServers
No relay through a middle device It lacks write permission

§ Diagnosing transport problems (SDK 5.1+), § When Data Does Not Sync · Details: reference/transports-and-presence.md

Checklist

  • [ ] One shared instance (Swift: a strong reference to Ditto itself); failed startup closes it
  • [ ] Server + webhook, or small peers with provisioned privateKey and license token
  • [ ] No keys, tokens, or development provider in release builds
  • [ ] Expiration handler set before sync.start(); checks the login result the way the SDK reports it (Login failure above); never throws
  • [ ] System parameters in DittoConfig.systemParameters on every open (5.1: ALTER SYSTEM before sync)
  • [ ] Sync started after its prerequisites (Flutter: start() not awaited); no close() when the app goes to the background
  • [ ] Pending work awaited and observers cancelled before close()
  • [ ] Transports via updateTransportConfig(); hub TCP limit raised before sync
  • [ ] No secrets in peer or identity metadata
  • [ ] Permissions scoped by _id, narrowest per role; revocation checking on
  • [ ] Inputs parameterized; sensitive data encrypted (store key on Swift/Kotlin, or fields); webhook signatures verified

More

  • Reference: reference/startup-and-lifecycle.md (requirements, DittoConfig, startup, auth, system parameters, shutdown), reference/transports-and-presence.md (transports, TCP hubs, diagnostics, presence), reference/security.md (keys, webhook, _id design, revocation, data at rest)
  • Related skills: query-sync (subscriptions), performance-observability (logging, diagnostics), storage-lifecycle (tombstone parameters), testing (local store tests), audit (whole-app review)

04 同仓库更多 Skills

ditto-examples
ditto-examples/ditto-cookbook

transactions-attachments

Ditto SDK transactions and attachments (Flutter, JavaScript, Kotlin, Swift): ditto.store.transaction with tx.execute only, no nesting, short scopes, rollback, close(); newAttachment, ATTACHMENT declarations, lazy fetchAttachment with a stall timeout, immutability, thumbnails, and blob availability. Use when writing or reviewing ditto.store.transaction, newAttachment, or fetchAttachment code, or when displaying photos or files stored in Ditto.

★ 0
ditto-examples
ditto-examples/ditto-cookbook

testing

Ditto SDK testing strategies in Flutter, JavaScript, Kotlin, or Swift: local-store test helper, tests for DQL statements, MISSING/NULL filters, merge-sensitive writes, soft delete, observer lifecycle, subscription rules, and multi-peer sync tests in one process. Use when writing or reviewing tests for code that uses Ditto, setting up a Ditto test harness, or reproducing a Ditto sync or merge bug.

测试与质量
★ 0
ditto-examples
ditto-examples/ditto-cookbook

storage-lifecycle

Ditto SDK data removal and local storage management covering DELETE vs soft delete vs EVICT, tombstones and their TTL, husk documents, eviction with complementary subscriptions, retention cleanup, and storage monitoring. Use when writing Ditto DELETE or EVICT statements, soft-delete flags or retention cleanup for Ditto documents, or TOMBSTONE_TTL_HOURS, or when deleted Ditto data came back or evicted documents sync back.

★ 0
ditto-examples
ditto-examples/ditto-cookbook

query-sync

Ditto SDK DQL reads and writes, subscriptions, and store observers (Flutter, JavaScript, Kotlin, Swift): query parameters, MISSING vs NULL, membership filters, subscription and observer lifecycle, ON ID CONFLICT upserts, JOIN, RETURNING. Use when writing or reviewing ditto.store.execute, ditto.sync.registerSubscription, registerObserver, or DQL in an app that uses Ditto, or when Ditto data does not sync or a Ditto query returns nothing.

★ 0
ditto-examples
ditto-examples/ditto-cookbook

performance-observability

Ditto SDK store observer performance and diagnostics (Flutter, JavaScript, Kotlin, Swift): observer lifecycle, backpressure (registerObserverV2, signalNext, suspending handlers), narrow UI updates, differs, redundant writes, indexes, ADVISE, EXPLAIN, PROFILE, logging, and system: collections. Use when a Ditto query is slow, a screen showing Ditto data janks, Ditto observers grow memory, Ditto upserts repeat, or when setting up Ditto logging.

★ 0
ditto-examples
ditto-examples/ditto-cookbook

guide

Searches the complete Ditto SDK best practices guide (SDK 5.2.0, Flutter, JavaScript, Kotlin, Swift) bundled with this plugin, for answers the focused ditto skills do not cover. Use to look up a Ditto API, DQL keyword or function, system parameter, error message, an SDK's API or behavior, or the reasoning behind a rule, or when a Ditto question spans several topics.

★ 0