react-native-cloud-sync 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +360 -0
- package/app.plugin.js +3 -0
- package/ios/CloudSyncError.swift +144 -0
- package/ios/CloudSyncImpl.swift +1263 -0
- package/ios/RNCloudSync.h +25 -0
- package/ios/RNCloudSync.mm +477 -0
- package/jest-mock.js +136 -0
- package/lib/commonjs/config.js +85 -0
- package/lib/commonjs/config.js.map +1 -0
- package/lib/commonjs/errors.js +244 -0
- package/lib/commonjs/errors.js.map +1 -0
- package/lib/commonjs/hooks.js +257 -0
- package/lib/commonjs/hooks.js.map +1 -0
- package/lib/commonjs/index.js +244 -0
- package/lib/commonjs/index.js.map +1 -0
- package/lib/commonjs/internal/autoFlush.js +65 -0
- package/lib/commonjs/internal/autoFlush.js.map +1 -0
- package/lib/commonjs/internal/base64.js +58 -0
- package/lib/commonjs/internal/base64.js.map +1 -0
- package/lib/commonjs/internal/bytes.js +32 -0
- package/lib/commonjs/internal/bytes.js.map +1 -0
- package/lib/commonjs/internal/cloudKitRest.js +527 -0
- package/lib/commonjs/internal/cloudKitRest.js.map +1 -0
- package/lib/commonjs/internal/enums.js +23 -0
- package/lib/commonjs/internal/enums.js.map +1 -0
- package/lib/commonjs/internal/googleDriveRest.js +624 -0
- package/lib/commonjs/internal/googleDriveRest.js.map +1 -0
- package/lib/commonjs/internal/keys.js +139 -0
- package/lib/commonjs/internal/keys.js.map +1 -0
- package/lib/commonjs/internal/logger.js +29 -0
- package/lib/commonjs/internal/logger.js.map +1 -0
- package/lib/commonjs/internal/nativeModule.js +125 -0
- package/lib/commonjs/internal/nativeModule.js.map +1 -0
- package/lib/commonjs/internal/timeout.js +72 -0
- package/lib/commonjs/internal/timeout.js.map +1 -0
- package/lib/commonjs/package.json +1 -0
- package/lib/commonjs/providers/cloudKit.js +398 -0
- package/lib/commonjs/providers/cloudKit.js.map +1 -0
- package/lib/commonjs/providers/cloudKitBackup.js +86 -0
- package/lib/commonjs/providers/cloudKitBackup.js.map +1 -0
- package/lib/commonjs/providers/cloudKitEncrypted.js +150 -0
- package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -0
- package/lib/commonjs/providers/googleDrive.js +219 -0
- package/lib/commonjs/providers/googleDrive.js.map +1 -0
- package/lib/commonjs/providers/googleDriveFiles.js +68 -0
- package/lib/commonjs/providers/googleDriveFiles.js.map +1 -0
- package/lib/commonjs/providers/icloudDocuments.js +121 -0
- package/lib/commonjs/providers/icloudDocuments.js.map +1 -0
- package/lib/commonjs/providers/icloudKV.js +171 -0
- package/lib/commonjs/providers/icloudKV.js.map +1 -0
- package/lib/commonjs/providers/icloudKV.web.js +42 -0
- package/lib/commonjs/providers/icloudKV.web.js.map +1 -0
- package/lib/commonjs/providers/memory.js +201 -0
- package/lib/commonjs/providers/memory.js.map +1 -0
- package/lib/commonjs/resolvers.js +128 -0
- package/lib/commonjs/resolvers.js.map +1 -0
- package/lib/commonjs/specs/NativeRNCloudSync.js +14 -0
- package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -0
- package/lib/commonjs/store.js +1064 -0
- package/lib/commonjs/store.js.map +1 -0
- package/lib/commonjs/testing.js +32 -0
- package/lib/commonjs/testing.js.map +1 -0
- package/lib/commonjs/types.js +86 -0
- package/lib/commonjs/types.js.map +1 -0
- package/lib/module/config.js +72 -0
- package/lib/module/config.js.map +1 -0
- package/lib/module/errors.js +231 -0
- package/lib/module/errors.js.map +1 -0
- package/lib/module/hooks.js +250 -0
- package/lib/module/hooks.js.map +1 -0
- package/lib/module/index.js +46 -0
- package/lib/module/index.js.map +1 -0
- package/lib/module/internal/autoFlush.js +62 -0
- package/lib/module/internal/autoFlush.js.map +1 -0
- package/lib/module/internal/base64.js +53 -0
- package/lib/module/internal/base64.js.map +1 -0
- package/lib/module/internal/bytes.js +28 -0
- package/lib/module/internal/bytes.js.map +1 -0
- package/lib/module/internal/cloudKitRest.js +518 -0
- package/lib/module/internal/cloudKitRest.js.map +1 -0
- package/lib/module/internal/enums.js +18 -0
- package/lib/module/internal/enums.js.map +1 -0
- package/lib/module/internal/googleDriveRest.js +620 -0
- package/lib/module/internal/googleDriveRest.js.map +1 -0
- package/lib/module/internal/keys.js +134 -0
- package/lib/module/internal/keys.js.map +1 -0
- package/lib/module/internal/logger.js +23 -0
- package/lib/module/internal/logger.js.map +1 -0
- package/lib/module/internal/nativeModule.js +117 -0
- package/lib/module/internal/nativeModule.js.map +1 -0
- package/lib/module/internal/timeout.js +67 -0
- package/lib/module/internal/timeout.js.map +1 -0
- package/lib/module/package.json +1 -0
- package/lib/module/providers/cloudKit.js +392 -0
- package/lib/module/providers/cloudKit.js.map +1 -0
- package/lib/module/providers/cloudKitBackup.js +82 -0
- package/lib/module/providers/cloudKitBackup.js.map +1 -0
- package/lib/module/providers/cloudKitEncrypted.js +146 -0
- package/lib/module/providers/cloudKitEncrypted.js.map +1 -0
- package/lib/module/providers/googleDrive.js +214 -0
- package/lib/module/providers/googleDrive.js.map +1 -0
- package/lib/module/providers/googleDriveFiles.js +64 -0
- package/lib/module/providers/googleDriveFiles.js.map +1 -0
- package/lib/module/providers/icloudDocuments.js +117 -0
- package/lib/module/providers/icloudDocuments.js.map +1 -0
- package/lib/module/providers/icloudKV.js +165 -0
- package/lib/module/providers/icloudKV.js.map +1 -0
- package/lib/module/providers/icloudKV.web.js +36 -0
- package/lib/module/providers/icloudKV.web.js.map +1 -0
- package/lib/module/providers/memory.js +197 -0
- package/lib/module/providers/memory.js.map +1 -0
- package/lib/module/resolvers.js +120 -0
- package/lib/module/resolvers.js.map +1 -0
- package/lib/module/specs/NativeRNCloudSync.js +12 -0
- package/lib/module/specs/NativeRNCloudSync.js.map +1 -0
- package/lib/module/store.js +1061 -0
- package/lib/module/store.js.map +1 -0
- package/lib/module/testing.js +17 -0
- package/lib/module/testing.js.map +1 -0
- package/lib/module/types.js +82 -0
- package/lib/module/types.js.map +1 -0
- package/lib/typescript/commonjs/config.d.ts +33 -0
- package/lib/typescript/commonjs/config.d.ts.map +1 -0
- package/lib/typescript/commonjs/errors.d.ts +140 -0
- package/lib/typescript/commonjs/errors.d.ts.map +1 -0
- package/lib/typescript/commonjs/hooks.d.ts +109 -0
- package/lib/typescript/commonjs/hooks.d.ts.map +1 -0
- package/lib/typescript/commonjs/index.d.ts +37 -0
- package/lib/typescript/commonjs/index.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/autoFlush.d.ts +45 -0
- package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/base64.d.ts +12 -0
- package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/bytes.d.ts +12 -0
- package/lib/typescript/commonjs/internal/bytes.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +149 -0
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/enums.d.ts +10 -0
- package/lib/typescript/commonjs/internal/enums.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +232 -0
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/keys.d.ts +28 -0
- package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/logger.d.ts +10 -0
- package/lib/typescript/commonjs/internal/logger.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/nativeModule.d.ts +29 -0
- package/lib/typescript/commonjs/internal/nativeModule.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/timeout.d.ts +36 -0
- package/lib/typescript/commonjs/internal/timeout.d.ts.map +1 -0
- package/lib/typescript/commonjs/package.json +1 -0
- package/lib/typescript/commonjs/providers/cloudKit.d.ts +86 -0
- package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +65 -0
- package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts +37 -0
- package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/googleDrive.d.ts +35 -0
- package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts +59 -0
- package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +101 -0
- package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/icloudKV.d.ts +26 -0
- package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/icloudKV.web.d.ts +12 -0
- package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/memory.d.ts +90 -0
- package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -0
- package/lib/typescript/commonjs/resolvers.d.ts +60 -0
- package/lib/typescript/commonjs/resolvers.d.ts.map +1 -0
- package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +133 -0
- package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -0
- package/lib/typescript/commonjs/store.d.ts +118 -0
- package/lib/typescript/commonjs/store.d.ts.map +1 -0
- package/lib/typescript/commonjs/testing.d.ts +16 -0
- package/lib/typescript/commonjs/testing.d.ts.map +1 -0
- package/lib/typescript/commonjs/types.d.ts +367 -0
- package/lib/typescript/commonjs/types.d.ts.map +1 -0
- package/lib/typescript/module/config.d.ts +33 -0
- package/lib/typescript/module/config.d.ts.map +1 -0
- package/lib/typescript/module/errors.d.ts +140 -0
- package/lib/typescript/module/errors.d.ts.map +1 -0
- package/lib/typescript/module/hooks.d.ts +109 -0
- package/lib/typescript/module/hooks.d.ts.map +1 -0
- package/lib/typescript/module/index.d.ts +37 -0
- package/lib/typescript/module/index.d.ts.map +1 -0
- package/lib/typescript/module/internal/autoFlush.d.ts +45 -0
- package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -0
- package/lib/typescript/module/internal/base64.d.ts +12 -0
- package/lib/typescript/module/internal/base64.d.ts.map +1 -0
- package/lib/typescript/module/internal/bytes.d.ts +12 -0
- package/lib/typescript/module/internal/bytes.d.ts.map +1 -0
- package/lib/typescript/module/internal/cloudKitRest.d.ts +149 -0
- package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -0
- package/lib/typescript/module/internal/enums.d.ts +10 -0
- package/lib/typescript/module/internal/enums.d.ts.map +1 -0
- package/lib/typescript/module/internal/googleDriveRest.d.ts +232 -0
- package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -0
- package/lib/typescript/module/internal/keys.d.ts +28 -0
- package/lib/typescript/module/internal/keys.d.ts.map +1 -0
- package/lib/typescript/module/internal/logger.d.ts +10 -0
- package/lib/typescript/module/internal/logger.d.ts.map +1 -0
- package/lib/typescript/module/internal/nativeModule.d.ts +29 -0
- package/lib/typescript/module/internal/nativeModule.d.ts.map +1 -0
- package/lib/typescript/module/internal/timeout.d.ts +36 -0
- package/lib/typescript/module/internal/timeout.d.ts.map +1 -0
- package/lib/typescript/module/package.json +1 -0
- package/lib/typescript/module/providers/cloudKit.d.ts +86 -0
- package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -0
- package/lib/typescript/module/providers/cloudKitBackup.d.ts +65 -0
- package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -0
- package/lib/typescript/module/providers/cloudKitEncrypted.d.ts +37 -0
- package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -0
- package/lib/typescript/module/providers/googleDrive.d.ts +35 -0
- package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -0
- package/lib/typescript/module/providers/googleDriveFiles.d.ts +59 -0
- package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -0
- package/lib/typescript/module/providers/icloudDocuments.d.ts +101 -0
- package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -0
- package/lib/typescript/module/providers/icloudKV.d.ts +26 -0
- package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -0
- package/lib/typescript/module/providers/icloudKV.web.d.ts +12 -0
- package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -0
- package/lib/typescript/module/providers/memory.d.ts +90 -0
- package/lib/typescript/module/providers/memory.d.ts.map +1 -0
- package/lib/typescript/module/resolvers.d.ts +60 -0
- package/lib/typescript/module/resolvers.d.ts.map +1 -0
- package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +133 -0
- package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -0
- package/lib/typescript/module/store.d.ts +118 -0
- package/lib/typescript/module/store.d.ts.map +1 -0
- package/lib/typescript/module/testing.d.ts +16 -0
- package/lib/typescript/module/testing.d.ts.map +1 -0
- package/lib/typescript/module/types.d.ts +367 -0
- package/lib/typescript/module/types.d.ts.map +1 -0
- package/package.json +186 -0
- package/plugin/build/index.d.ts +45 -0
- package/plugin/build/index.js +93 -0
- package/react-native-cloud-sync.podspec +48 -0
- package/src/config.ts +94 -0
- package/src/errors.ts +263 -0
- package/src/hooks.ts +337 -0
- package/src/index.ts +113 -0
- package/src/internal/autoFlush.ts +87 -0
- package/src/internal/base64.ts +63 -0
- package/src/internal/bytes.ts +28 -0
- package/src/internal/cloudKitRest.ts +654 -0
- package/src/internal/enums.ts +35 -0
- package/src/internal/googleDriveRest.ts +765 -0
- package/src/internal/keys.ts +160 -0
- package/src/internal/logger.ts +23 -0
- package/src/internal/nativeModule.ts +149 -0
- package/src/internal/timeout.ts +83 -0
- package/src/providers/cloudKit.ts +510 -0
- package/src/providers/cloudKitBackup.ts +124 -0
- package/src/providers/cloudKitEncrypted.ts +175 -0
- package/src/providers/googleDrive.ts +251 -0
- package/src/providers/googleDriveFiles.ts +117 -0
- package/src/providers/icloudDocuments.ts +175 -0
- package/src/providers/icloudKV.ts +206 -0
- package/src/providers/icloudKV.web.ts +41 -0
- package/src/providers/memory.ts +302 -0
- package/src/resolvers.ts +133 -0
- package/src/specs/NativeRNCloudSync.ts +184 -0
- package/src/store.ts +1288 -0
- package/src/testing.ts +22 -0
- package/src/types.ts +426 -0
package/src/store.ts
ADDED
|
@@ -0,0 +1,1288 @@
|
|
|
1
|
+
import { icloudKV } from './providers/icloudKV'
|
|
2
|
+
import { cloudKit } from './providers/cloudKit'
|
|
3
|
+
import { cloudKitEncrypted } from './providers/cloudKitEncrypted'
|
|
4
|
+
import { googleDrive } from './providers/googleDrive'
|
|
5
|
+
import { byteLength } from './internal/bytes'
|
|
6
|
+
import { assertKey } from './internal/keys'
|
|
7
|
+
import { withTimeout } from './internal/timeout'
|
|
8
|
+
import { attachAutoFlush } from './internal/autoFlush'
|
|
9
|
+
import { CloudSyncError, ErrorCode, isRetryable, normalizeError } from './errors'
|
|
10
|
+
import {
|
|
11
|
+
DEFAULT_TIERING,
|
|
12
|
+
type AccountChangeEvent,
|
|
13
|
+
type CloudProvider,
|
|
14
|
+
type CloudStoreOptions,
|
|
15
|
+
type DropReason,
|
|
16
|
+
type DroppedWrite,
|
|
17
|
+
type ItemWithMeta,
|
|
18
|
+
type OutboxEntry,
|
|
19
|
+
type ProviderName,
|
|
20
|
+
type QuotaInfo,
|
|
21
|
+
type RemoteChangeEvent,
|
|
22
|
+
type ResolveCandidate,
|
|
23
|
+
type TieringConfig,
|
|
24
|
+
type Unsubscribe,
|
|
25
|
+
type ValueCodec,
|
|
26
|
+
} from './types'
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* A durable place to park failed writes.
|
|
30
|
+
*
|
|
31
|
+
* Defaults to memory, which is honest but loses the queue on app restart. Pass
|
|
32
|
+
* an MMKV-backed adapter in production so an offline write survives being
|
|
33
|
+
* killed - that is the whole point of the outbox.
|
|
34
|
+
*
|
|
35
|
+
* Both methods are synchronous: the outbox is read and rewritten on the write
|
|
36
|
+
* path, where there is nowhere to await. AsyncStorage therefore cannot be
|
|
37
|
+
* wrapped directly; keep a synchronous cache in front of it if that is the
|
|
38
|
+
* only store you have.
|
|
39
|
+
*/
|
|
40
|
+
export interface OutboxStorage {
|
|
41
|
+
getString: (key: string) => string | null | undefined
|
|
42
|
+
set: (key: string, value: string) => void
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const OUTBOX_KEY = 'rncs.outbox.v1'
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Identity of a queued write: one entry per (provider, key).
|
|
49
|
+
*
|
|
50
|
+
* A single helper rather than a template literal at each site, because the two
|
|
51
|
+
* places that build it have to agree exactly - when they did not, a flush
|
|
52
|
+
* failed to recognise the entries it had just processed and wrote every one of
|
|
53
|
+
* them straight back, so a drained queue never shrank.
|
|
54
|
+
*
|
|
55
|
+
* The separator is an escaped NUL, which cannot appear in a provider name or a
|
|
56
|
+
* key, so the two halves can never run together and make two different pairs
|
|
57
|
+
* collide.
|
|
58
|
+
*/
|
|
59
|
+
function outboxId(provider: ProviderName, key: string): string {
|
|
60
|
+
return `${provider}\u0000${key}`
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const DEFAULT_OUTBOX_MAX_ENTRIES = 1000
|
|
64
|
+
const DEFAULT_OUTBOX_MAX_ATTEMPTS = 12
|
|
65
|
+
const DEFAULT_OUTBOX_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
|
|
66
|
+
const DEFAULT_AVAILABILITY_TTL_MS = 3_000
|
|
67
|
+
|
|
68
|
+
const BUILT_IN: Record<string, CloudProvider> = {
|
|
69
|
+
icloudKV,
|
|
70
|
+
cloudKit,
|
|
71
|
+
cloudKitEncrypted,
|
|
72
|
+
googleDrive,
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export interface MigrateOptions {
|
|
76
|
+
from: ProviderName
|
|
77
|
+
to: ProviderName
|
|
78
|
+
/**
|
|
79
|
+
* Keep going when a single key fails instead of aborting the whole
|
|
80
|
+
* migration. Default true.
|
|
81
|
+
*
|
|
82
|
+
* A serial loop that throws on the first bad key leaves the user half
|
|
83
|
+
* migrated with no record of how far it got, which is the worst of both
|
|
84
|
+
* outcomes. The failures come back in the result instead.
|
|
85
|
+
*/
|
|
86
|
+
continueOnError?: boolean
|
|
87
|
+
/** Only migrate keys this returns true for. */
|
|
88
|
+
filter?: (key: string) => boolean
|
|
89
|
+
/** Called after each key, for a progress bar over a long migration. */
|
|
90
|
+
onProgress?: (done: number, total: number) => void
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export interface MigrateResult {
|
|
94
|
+
copied: string[]
|
|
95
|
+
/** Keys that held no value at the source and so had nothing to copy. */
|
|
96
|
+
skipped: string[]
|
|
97
|
+
/** Keys that could not be copied, with the reason for each. */
|
|
98
|
+
failed: { key: string; error: CloudSyncError }[]
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export interface FlushResult {
|
|
102
|
+
drained: number
|
|
103
|
+
remaining: number
|
|
104
|
+
/** Entries abandoned during this flush. Also reported through `onDropped`. */
|
|
105
|
+
dropped: DroppedWrite[]
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export interface CloudStore {
|
|
109
|
+
getItem: (key: string) => Promise<string | null>
|
|
110
|
+
setItem: (key: string, value: string) => Promise<void>
|
|
111
|
+
removeItem: (key: string) => Promise<void>
|
|
112
|
+
getAllKeys: () => Promise<string[]>
|
|
113
|
+
|
|
114
|
+
/** Reads many keys, batching per provider where the provider supports it. */
|
|
115
|
+
multiGet: (keys: string[]) => Promise<[string, string | null][]>
|
|
116
|
+
/** Writes many pairs, batching per destination. */
|
|
117
|
+
multiSet: (entries: [string, string][]) => Promise<void>
|
|
118
|
+
/** Removes many keys, batching per provider. */
|
|
119
|
+
multiRemove: (keys: string[]) => Promise<void>
|
|
120
|
+
/**
|
|
121
|
+
* Removes every key this store can see. Enumerated, not hardcoded - a
|
|
122
|
+
* "delete my data" flow that forgets a key has not deleted the user's data.
|
|
123
|
+
*/
|
|
124
|
+
clear: () => Promise<{ removed: string[] }>
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Every key and value the store can see, as one object.
|
|
128
|
+
*
|
|
129
|
+
* `getAllKeys()` followed by `multiGet()`, so it costs whatever those cost -
|
|
130
|
+
* one batched request per provider that batches, a loop where one does not.
|
|
131
|
+
* Here because it is the shape a debug screen or an export actually wants,
|
|
132
|
+
* and because every key-value library being migrated from has it.
|
|
133
|
+
*/
|
|
134
|
+
getAllItems: () => Promise<Record<string, string>>
|
|
135
|
+
|
|
136
|
+
/** Per-provider storage usage, for the providers that report it. */
|
|
137
|
+
getQuota: () => Promise<QuotaInfo[]>
|
|
138
|
+
|
|
139
|
+
/** Copies every key from one provider to another. Does not delete the source. */
|
|
140
|
+
migrate: (opts: MigrateOptions) => Promise<MigrateResult>
|
|
141
|
+
|
|
142
|
+
/** Attempts to drain queued writes. Safe to call on reconnect or foreground. */
|
|
143
|
+
flushOutbox: () => Promise<FlushResult>
|
|
144
|
+
/** Entries still waiting, for surfacing a "pending sync" indicator. */
|
|
145
|
+
pendingWrites: () => OutboxEntry[]
|
|
146
|
+
/**
|
|
147
|
+
* Abandons queued writes, optionally only those matching `filter`. Returns
|
|
148
|
+
* how many were removed.
|
|
149
|
+
*
|
|
150
|
+
* The counterpart to `pendingWrites()`: a UI that can show a stuck write
|
|
151
|
+
* should be able to let the user give up on it.
|
|
152
|
+
*/
|
|
153
|
+
discardPendingWrites: (filter?: (e: OutboxEntry) => boolean) => number
|
|
154
|
+
|
|
155
|
+
/** Registers an extra provider (e.g. the in-memory test double). */
|
|
156
|
+
registerProvider: (provider: CloudProvider) => void
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Remote-change events from every configured provider, merged.
|
|
160
|
+
*
|
|
161
|
+
* Previously only the raw providers exposed this, so the facade - the
|
|
162
|
+
* recommended entry point - could not be subscribed to at all.
|
|
163
|
+
*/
|
|
164
|
+
onRemoteChange: (listener: (e: RemoteChangeEvent) => void) => Unsubscribe
|
|
165
|
+
/**
|
|
166
|
+
* Account-change events from every configured provider, merged.
|
|
167
|
+
*
|
|
168
|
+
* The store also acts on these itself: an `identityChanged` event drops
|
|
169
|
+
* provider caches and abandons queued writes, because both belong to the
|
|
170
|
+
* account that just went away.
|
|
171
|
+
*/
|
|
172
|
+
onAccountChange: (listener: (e: AccountChangeEvent) => void) => Unsubscribe
|
|
173
|
+
|
|
174
|
+
/** Releases the store's own provider subscriptions. */
|
|
175
|
+
dispose: () => void
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
export function createCloudStore(
|
|
179
|
+
options: CloudStoreOptions & { outboxStorage?: OutboxStorage }
|
|
180
|
+
): CloudStore {
|
|
181
|
+
const custom = new Map<string, CloudProvider>()
|
|
182
|
+
const useOutbox = options.outbox ?? true
|
|
183
|
+
const writeMode = options.writeMode ?? 'failover'
|
|
184
|
+
const resolveValue = options.resolve
|
|
185
|
+
// Repair defaults on with a resolver: without it the losing store keeps its
|
|
186
|
+
// old value and every read has to resolve again, forever.
|
|
187
|
+
const repairOnRead = options.repairOnRead ?? (resolveValue != null)
|
|
188
|
+
const storage: OutboxStorage = options.outboxStorage ?? createMemoryOutboxStorage()
|
|
189
|
+
const codec: ValueCodec | null = options.codec ?? null
|
|
190
|
+
const validateKeys = options.validateKeys ?? true
|
|
191
|
+
const timeoutMs = options.timeoutMs
|
|
192
|
+
const availabilityTtlMs = options.availabilityTtlMs ?? DEFAULT_AVAILABILITY_TTL_MS
|
|
193
|
+
const maxEntries = options.outboxMaxEntries ?? DEFAULT_OUTBOX_MAX_ENTRIES
|
|
194
|
+
const maxAttempts = options.outboxMaxAttempts ?? DEFAULT_OUTBOX_MAX_ATTEMPTS
|
|
195
|
+
const maxAgeMs = options.outboxMaxAgeMs ?? DEFAULT_OUTBOX_MAX_AGE_MS
|
|
196
|
+
|
|
197
|
+
const tiering: TieringConfig | null
|
|
198
|
+
= options.tiering === 'off'
|
|
199
|
+
? null
|
|
200
|
+
: options.tiering === 'auto' || options.tiering == null
|
|
201
|
+
? DEFAULT_TIERING
|
|
202
|
+
: options.tiering
|
|
203
|
+
|
|
204
|
+
// ------------------------------------------------------------- providers
|
|
205
|
+
|
|
206
|
+
function resolveProvider(name: ProviderName): CloudProvider {
|
|
207
|
+
const found = custom.get(name) ?? BUILT_IN[name]
|
|
208
|
+
if (found == null)
|
|
209
|
+
throw new CloudSyncError(
|
|
210
|
+
ErrorCode.CONTAINER_MISCONFIGURED,
|
|
211
|
+
`[RNCloudSync] Unknown provider '${name}'. Register it with registerProvider() first.`
|
|
212
|
+
)
|
|
213
|
+
|
|
214
|
+
return found
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* Memoised `isAvailable()`.
|
|
219
|
+
*
|
|
220
|
+
* The store asks before every operation, and for `icloudKV` that is a bridge
|
|
221
|
+
* hop while for `googleDrive` it invokes the host's `getAccessToken`. A loop
|
|
222
|
+
* over 100 keys used to cost 100+ probes on top of the work itself. Held
|
|
223
|
+
* briefly, so a token expiring mid-session is still noticed quickly.
|
|
224
|
+
*/
|
|
225
|
+
const availability = new Map<string, { at: number; ok: boolean }>()
|
|
226
|
+
|
|
227
|
+
async function isAvailable(p: CloudProvider): Promise<boolean> {
|
|
228
|
+
if (availabilityTtlMs <= 0) return probe(p)
|
|
229
|
+
|
|
230
|
+
const now = Date.now()
|
|
231
|
+
const cached = availability.get(p.name)
|
|
232
|
+
if (cached != null && now - cached.at < availabilityTtlMs) return cached.ok
|
|
233
|
+
|
|
234
|
+
const ok = await probe(p)
|
|
235
|
+
availability.set(p.name, { at: Date.now(), ok })
|
|
236
|
+
return ok
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
async function probe(p: CloudProvider): Promise<boolean> {
|
|
240
|
+
try {
|
|
241
|
+
return await run(p, () => p.isAvailable())
|
|
242
|
+
}
|
|
243
|
+
catch {
|
|
244
|
+
// `isAvailable` is documented as non-throwing, but a timeout wrapper or a
|
|
245
|
+
// third-party provider can still reject. Unavailable is the safe reading.
|
|
246
|
+
return false
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
function invalidateAvailability(): void {
|
|
251
|
+
availability.clear()
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/** Applies the configured per-operation timeout, if any. */
|
|
255
|
+
function run<T>(p: CloudProvider, op: () => Promise<T>): Promise<T> {
|
|
256
|
+
if (timeoutMs == null) return op()
|
|
257
|
+
return withTimeout(op(), timeoutMs, p.name)
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* Every configured provider that is currently usable, in preference order.
|
|
262
|
+
*
|
|
263
|
+
* Ordering is preserved so `mirror` writes hit the preferred store first -
|
|
264
|
+
* if the process dies mid-write, the copy that landed is the one reads reach
|
|
265
|
+
* first.
|
|
266
|
+
*/
|
|
267
|
+
async function allAvailable(): Promise<CloudProvider[]> {
|
|
268
|
+
const found: CloudProvider[] = []
|
|
269
|
+
for (const name of options.providers) {
|
|
270
|
+
const p = resolveProvider(name)
|
|
271
|
+
if (await isAvailable(p)) found.push(p)
|
|
272
|
+
}
|
|
273
|
+
return found
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/** First configured+available provider, in the caller's preference order. */
|
|
277
|
+
async function primary(): Promise<CloudProvider> {
|
|
278
|
+
for (const name of options.providers) {
|
|
279
|
+
const p = resolveProvider(name)
|
|
280
|
+
if (await isAvailable(p)) return p
|
|
281
|
+
}
|
|
282
|
+
throw noneAvailable()
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
function noneAvailable(): CloudSyncError {
|
|
286
|
+
return new CloudSyncError(
|
|
287
|
+
ErrorCode.NOT_SIGNED_IN,
|
|
288
|
+
`[RNCloudSync] None of the configured providers (${options.providers.join(', ')}) `
|
|
289
|
+
+ `is currently available.`
|
|
290
|
+
)
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
function checkKey(key: string): void {
|
|
294
|
+
if (validateKeys) assertKey(key, options.providers)
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
// ----------------------------------------------------------------- codec
|
|
298
|
+
|
|
299
|
+
async function encode(key: string, value: string): Promise<string> {
|
|
300
|
+
return codec == null ? value : await codec.encode(value, key)
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
async function decode(key: string, value: string): Promise<string> {
|
|
304
|
+
return codec == null ? value : await codec.decode(value, key)
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// ---------------------------------------------------------------- outbox
|
|
308
|
+
|
|
309
|
+
function readOutbox(): OutboxEntry[] {
|
|
310
|
+
const raw = storage.getString(OUTBOX_KEY)
|
|
311
|
+
if (raw == null) return []
|
|
312
|
+
try {
|
|
313
|
+
const parsed: unknown = JSON.parse(raw)
|
|
314
|
+
return Array.isArray(parsed) ? (parsed as OutboxEntry[]) : []
|
|
315
|
+
}
|
|
316
|
+
catch {
|
|
317
|
+
return []
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
function writeOutbox(entries: OutboxEntry[]): void {
|
|
322
|
+
storage.set(OUTBOX_KEY, JSON.stringify(entries))
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
function reportDropped(entry: OutboxEntry, reason: DropReason, error?: CloudSyncError): void {
|
|
326
|
+
options.onDropped?.({ entry, reason, error })
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
function enqueue(
|
|
330
|
+
key: string,
|
|
331
|
+
value: string | null,
|
|
332
|
+
provider: ProviderName,
|
|
333
|
+
lastErrorCode?: string
|
|
334
|
+
): void {
|
|
335
|
+
if (!useOutbox) return
|
|
336
|
+
const entries = readOutbox().filter(e => !(e.key === key && e.provider === provider))
|
|
337
|
+
entries.push({
|
|
338
|
+
key,
|
|
339
|
+
value,
|
|
340
|
+
provider,
|
|
341
|
+
attempts: 0,
|
|
342
|
+
nextAttemptAt: Date.now(),
|
|
343
|
+
enqueuedAt: Date.now(),
|
|
344
|
+
lastErrorCode,
|
|
345
|
+
})
|
|
346
|
+
|
|
347
|
+
// An unbounded queue is a slow leak: every enqueue rewrites the whole blob,
|
|
348
|
+
// so a long offline stretch degrades the write path itself. Drop the oldest
|
|
349
|
+
// and say so, rather than growing without limit or failing silently.
|
|
350
|
+
while (entries.length > maxEntries) {
|
|
351
|
+
const evicted = entries.shift()
|
|
352
|
+
if (evicted != null) reportDropped(evicted, 'queueFull')
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
writeOutbox(entries)
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* Forgets any queued write for this key/provider.
|
|
360
|
+
*
|
|
361
|
+
* Called after a *successful* direct write, and this is not an optimisation.
|
|
362
|
+
* Without it: an offline `setItem(k, v1)` queues v1, a later online
|
|
363
|
+
* `setItem(k, v2)` succeeds directly, and the next flush writes v1 back over
|
|
364
|
+
* v2. The queue has to be invalidated by the newer write that superseded it.
|
|
365
|
+
*/
|
|
366
|
+
function dequeue(key: string, provider: ProviderName): void {
|
|
367
|
+
if (!useOutbox) return
|
|
368
|
+
const entries = readOutbox()
|
|
369
|
+
const kept = entries.filter(e => !(e.key === key && e.provider === provider))
|
|
370
|
+
if (kept.length !== entries.length) writeOutbox(kept)
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
function dequeueMany(keys: string[], provider: ProviderName): void {
|
|
374
|
+
if (!useOutbox || keys.length === 0) return
|
|
375
|
+
const drop = new Set(keys)
|
|
376
|
+
const entries = readOutbox()
|
|
377
|
+
const kept = entries.filter(e => !(drop.has(e.key) && e.provider === provider))
|
|
378
|
+
if (kept.length !== entries.length) writeOutbox(kept)
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
// ------------------------------------------------------------ size rules
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* The byte ceiling tiering imposes on a provider, or null when it imposes
|
|
385
|
+
* none. This is what routes a value to the right backing store by size.
|
|
386
|
+
*
|
|
387
|
+
* Both thresholds are honoured. Drive stores whole files and has no
|
|
388
|
+
* comparable small ceiling, so it is the destination of last resort.
|
|
389
|
+
*/
|
|
390
|
+
function limitFor(provider: CloudProvider): number | null {
|
|
391
|
+
if (tiering == null) return null
|
|
392
|
+
if (provider.name === 'icloudKV') return tiering.kvMaxBytes
|
|
393
|
+
if (provider.name === 'cloudKit') return tiering.recordMaxBytes
|
|
394
|
+
return null
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
function canHold(provider: CloudProvider, value: string): boolean {
|
|
398
|
+
const limit = limitFor(provider)
|
|
399
|
+
return limit == null || byteLength(value) <= limit
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* Picks the destination for a `failover` write when the preferred provider is
|
|
404
|
+
* too small for the value.
|
|
405
|
+
*
|
|
406
|
+
* Candidates must be both large enough AND currently available: routing to a
|
|
407
|
+
* provider that is configured but unreachable just converts a size problem
|
|
408
|
+
* into a write failure.
|
|
409
|
+
*/
|
|
410
|
+
async function providerForSize(
|
|
411
|
+
value: string,
|
|
412
|
+
preferred: CloudProvider
|
|
413
|
+
): Promise<CloudProvider> {
|
|
414
|
+
if (canHold(preferred, value)) return preferred
|
|
415
|
+
|
|
416
|
+
const bytes = byteLength(value)
|
|
417
|
+
for (const name of options.providers) {
|
|
418
|
+
if (name === preferred.name) continue
|
|
419
|
+
const candidate = resolveProvider(name)
|
|
420
|
+
if (!canHold(candidate, value)) continue
|
|
421
|
+
if (!(await isAvailable(candidate))) continue
|
|
422
|
+
return candidate
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
throw new CloudSyncError(
|
|
426
|
+
ErrorCode.PAYLOAD_TOO_LARGE,
|
|
427
|
+
`[RNCloudSync] Value is ${bytes} bytes, above the ${limitFor(preferred)}-byte limit for `
|
|
428
|
+
+ `'${preferred.name}', and no larger-capacity provider is configured and available. Add `
|
|
429
|
+
+ `'cloudKit' or 'googleDrive' to providers.`,
|
|
430
|
+
{ limitBytes: limitFor(preferred) ?? undefined, actualBytes: bytes, provider: preferred.name }
|
|
431
|
+
)
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
// ----------------------------------------------------------------- reads
|
|
435
|
+
|
|
436
|
+
async function readOne(p: CloudProvider, key: string): Promise<ItemWithMeta | null> {
|
|
437
|
+
if (p.getItemWithMeta != null) return await run(p, () => p.getItemWithMeta!(key))
|
|
438
|
+
const value = await run(p, () => p.getItem(key))
|
|
439
|
+
return value == null ? null : { value }
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
async function readBatch(p: CloudProvider, keys: string[]): Promise<(string | null)[]> {
|
|
443
|
+
if (p.multiGet != null) return await run(p, () => p.multiGet!(keys))
|
|
444
|
+
|
|
445
|
+
const out: (string | null)[] = []
|
|
446
|
+
for (const key of keys) out.push(await run(p, () => p.getItem(key)))
|
|
447
|
+
return out
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
async function writeBatch(p: CloudProvider, entries: [string, string][]): Promise<void> {
|
|
451
|
+
if (entries.length === 0) return
|
|
452
|
+
if (p.multiSet != null) {
|
|
453
|
+
await run(p, () => p.multiSet!(entries))
|
|
454
|
+
return
|
|
455
|
+
}
|
|
456
|
+
for (const [key, value] of entries) await run(p, () => p.setItem(key, value))
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
async function removeBatch(p: CloudProvider, keys: string[]): Promise<void> {
|
|
460
|
+
if (keys.length === 0) return
|
|
461
|
+
if (p.multiRemove != null) {
|
|
462
|
+
await run(p, () => p.multiRemove!(keys))
|
|
463
|
+
return
|
|
464
|
+
}
|
|
465
|
+
for (const key of keys) await run(p, () => p.removeItem(key))
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
// ---------------------------------------------------------------- writes
|
|
469
|
+
|
|
470
|
+
/** Single-destination write, queueing a retryable failure. */
|
|
471
|
+
async function writeOne(target: CloudProvider, key: string, value: string): Promise<void> {
|
|
472
|
+
try {
|
|
473
|
+
await run(target, () => target.setItem(key, value))
|
|
474
|
+
// This write supersedes anything queued for the same destination.
|
|
475
|
+
dequeue(key, target.name)
|
|
476
|
+
}
|
|
477
|
+
catch (e) {
|
|
478
|
+
const err = normalizeError(e, target.name)
|
|
479
|
+
if (useOutbox && isRetryable(err)) {
|
|
480
|
+
enqueue(key, value, target.name, err.code)
|
|
481
|
+
options.onError?.(err)
|
|
482
|
+
return
|
|
483
|
+
}
|
|
484
|
+
throw err
|
|
485
|
+
}
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
/**
|
|
489
|
+
* Removes a key from providers that are reachable but cannot hold this value.
|
|
490
|
+
*
|
|
491
|
+
* Without this, `mirror` plus tiering strands stale data: a value that grows
|
|
492
|
+
* past `kvMaxBytes` is written to CloudKit and Drive and *skipped* on the
|
|
493
|
+
* key-value store, which keeps the older, smaller copy. A read with no
|
|
494
|
+
* resolver prefers that provider and returns the stale value forever, and
|
|
495
|
+
* read repair never cleans it up because it applies the same size guard.
|
|
496
|
+
* The copy the value no longer fits in has to go.
|
|
497
|
+
*/
|
|
498
|
+
async function evictWhereTooLarge(
|
|
499
|
+
targets: CloudProvider[],
|
|
500
|
+
key: string,
|
|
501
|
+
value: string
|
|
502
|
+
): Promise<void> {
|
|
503
|
+
for (const target of targets) {
|
|
504
|
+
if (canHold(target, value)) continue
|
|
505
|
+
try {
|
|
506
|
+
await run(target, () => target.removeItem(key))
|
|
507
|
+
dequeue(key, target.name)
|
|
508
|
+
}
|
|
509
|
+
catch (e) {
|
|
510
|
+
// Best effort. A stale copy left behind is reported, not fatal - the
|
|
511
|
+
// value itself did land somewhere.
|
|
512
|
+
options.onError?.(normalizeError(e, target.name))
|
|
513
|
+
}
|
|
514
|
+
}
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
/**
|
|
518
|
+
* Mirrored write.
|
|
519
|
+
*
|
|
520
|
+
* Succeeds if at least one destination took the value, because one good copy
|
|
521
|
+
* plus a queued retry is a better outcome than rejecting a write the user has
|
|
522
|
+
* already been told about. Retryable failures go to the outbox per provider,
|
|
523
|
+
* so they converge without re-sending to the ones that already succeeded.
|
|
524
|
+
*
|
|
525
|
+
* Rejects only when nothing stored it - silence there would be the false
|
|
526
|
+
* success this package exists to avoid.
|
|
527
|
+
*/
|
|
528
|
+
async function writeMany(targets: CloudProvider[], key: string, value: string): Promise<void> {
|
|
529
|
+
const eligible = targets.filter(t => canHold(t, value))
|
|
530
|
+
|
|
531
|
+
if (eligible.length === 0) {
|
|
532
|
+
if (targets.length === 0) throw noneAvailable()
|
|
533
|
+
|
|
534
|
+
// Every destination exists but the value is too large for all of them.
|
|
535
|
+
const bytes = byteLength(value)
|
|
536
|
+
const largest = targets
|
|
537
|
+
.map(limitFor)
|
|
538
|
+
.filter((n): n is number => n != null)
|
|
539
|
+
.reduce<number | undefined>((a, b) => (a == null || b > a ? b : a), undefined)
|
|
540
|
+
throw new CloudSyncError(
|
|
541
|
+
ErrorCode.PAYLOAD_TOO_LARGE,
|
|
542
|
+
`[RNCloudSync] Value is ${bytes} bytes and does not fit in any configured provider.`,
|
|
543
|
+
{ actualBytes: bytes, limitBytes: largest }
|
|
544
|
+
)
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
let stored = 0
|
|
548
|
+
let fatal: CloudSyncError | null = null
|
|
549
|
+
|
|
550
|
+
for (const target of eligible)
|
|
551
|
+
try {
|
|
552
|
+
await run(target, () => target.setItem(key, value))
|
|
553
|
+
dequeue(key, target.name)
|
|
554
|
+
stored += 1
|
|
555
|
+
}
|
|
556
|
+
catch (e) {
|
|
557
|
+
const err = normalizeError(e, target.name)
|
|
558
|
+
if (useOutbox && isRetryable(err)) {
|
|
559
|
+
enqueue(key, value, target.name, err.code)
|
|
560
|
+
options.onError?.(err)
|
|
561
|
+
continue
|
|
562
|
+
}
|
|
563
|
+
fatal ??= err
|
|
564
|
+
options.onError?.(err)
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
// Only once the value has a home somewhere: dropping the old copy first
|
|
568
|
+
// would open a window in which the key exists nowhere.
|
|
569
|
+
if (stored > 0) await evictWhereTooLarge(targets, key, value)
|
|
570
|
+
|
|
571
|
+
// Nothing stored it and nothing was queued - that has to surface.
|
|
572
|
+
if (stored === 0 && fatal != null) throw fatal
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/** Mirrored delete, with the same at-least-one rule. */
|
|
576
|
+
async function removeMany(targets: CloudProvider[], key: string): Promise<void> {
|
|
577
|
+
// Nothing to delete from is a failed delete, not a completed one. Without
|
|
578
|
+
// this, a mirrored `removeItem` with every provider unavailable resolved
|
|
579
|
+
// successfully having removed the key from nowhere - the same false success
|
|
580
|
+
// this package exists to avoid, and which `writeMany` already refuses.
|
|
581
|
+
if (targets.length === 0) throw noneAvailable()
|
|
582
|
+
|
|
583
|
+
let removed = 0
|
|
584
|
+
let fatal: CloudSyncError | null = null
|
|
585
|
+
|
|
586
|
+
for (const target of targets)
|
|
587
|
+
try {
|
|
588
|
+
await run(target, () => target.removeItem(key))
|
|
589
|
+
dequeue(key, target.name)
|
|
590
|
+
removed += 1
|
|
591
|
+
}
|
|
592
|
+
catch (e) {
|
|
593
|
+
const err = normalizeError(e, target.name)
|
|
594
|
+
if (useOutbox && isRetryable(err)) {
|
|
595
|
+
enqueue(key, null, target.name, err.code)
|
|
596
|
+
options.onError?.(err)
|
|
597
|
+
continue
|
|
598
|
+
}
|
|
599
|
+
fatal ??= err
|
|
600
|
+
options.onError?.(err)
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
if (removed === 0 && fatal != null) throw fatal
|
|
604
|
+
}
|
|
605
|
+
|
|
606
|
+
/**
|
|
607
|
+
* Writes the resolved value back to providers that disagreed, and to
|
|
608
|
+
* reachable providers that were missing it entirely.
|
|
609
|
+
*
|
|
610
|
+
* A provider the winner no longer fits in has its stale copy removed instead
|
|
611
|
+
* of being silently left holding it - see {@link evictWhereTooLarge}.
|
|
612
|
+
*/
|
|
613
|
+
async function repair(
|
|
614
|
+
key: string,
|
|
615
|
+
winner: string,
|
|
616
|
+
candidates: ResolveCandidate[],
|
|
617
|
+
reachable: Map<ProviderName, CloudProvider>
|
|
618
|
+
): Promise<void> {
|
|
619
|
+
const byProvider = new Map(candidates.map(c => [c.provider, c.value]))
|
|
620
|
+
const stored = await encode(key, winner)
|
|
621
|
+
|
|
622
|
+
for (const [name, provider] of reachable) {
|
|
623
|
+
if (byProvider.get(name) === winner) continue
|
|
624
|
+
|
|
625
|
+
if (!canHold(provider, stored)) {
|
|
626
|
+
if (!byProvider.has(name)) continue
|
|
627
|
+
try {
|
|
628
|
+
await run(provider, () => provider.removeItem(key))
|
|
629
|
+
}
|
|
630
|
+
catch (e) {
|
|
631
|
+
options.onError?.(normalizeError(e, name))
|
|
632
|
+
}
|
|
633
|
+
continue
|
|
634
|
+
}
|
|
635
|
+
|
|
636
|
+
try {
|
|
637
|
+
await run(provider, () => provider.setItem(key, stored))
|
|
638
|
+
}
|
|
639
|
+
catch (e) {
|
|
640
|
+
options.onError?.(normalizeError(e, name))
|
|
641
|
+
}
|
|
642
|
+
}
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
// ---------------------------------------------------------------- events
|
|
646
|
+
|
|
647
|
+
const remoteListeners = new Set<(e: RemoteChangeEvent) => void>()
|
|
648
|
+
const accountListeners = new Set<(e: AccountChangeEvent) => void>()
|
|
649
|
+
let providerSubscriptions: Unsubscribe[] | null = null
|
|
650
|
+
let flushing: Promise<FlushResult> | null = null
|
|
651
|
+
|
|
652
|
+
/**
|
|
653
|
+
* Subscribes to every configured provider exactly once, lazily.
|
|
654
|
+
*
|
|
655
|
+
* Lazy because `createCloudStore` is often called at module scope, before the
|
|
656
|
+
* native module or a Drive token exists, and eagerly subscribing there would
|
|
657
|
+
* resolve providers too early.
|
|
658
|
+
*/
|
|
659
|
+
function ensureSubscribed(): void {
|
|
660
|
+
if (providerSubscriptions != null) return
|
|
661
|
+
providerSubscriptions = []
|
|
662
|
+
|
|
663
|
+
for (const name of options.providers) {
|
|
664
|
+
let p: CloudProvider
|
|
665
|
+
try {
|
|
666
|
+
p = resolveProvider(name)
|
|
667
|
+
}
|
|
668
|
+
catch {
|
|
669
|
+
// An unregistered provider is reported loudly by every other path;
|
|
670
|
+
// subscription should not be the thing that throws first.
|
|
671
|
+
continue
|
|
672
|
+
}
|
|
673
|
+
|
|
674
|
+
if (p.onRemoteChange != null)
|
|
675
|
+
providerSubscriptions.push(p.onRemoteChange((e) => {
|
|
676
|
+
for (const l of remoteListeners) l(e)
|
|
677
|
+
}))
|
|
678
|
+
|
|
679
|
+
if (p.onAccountChange != null)
|
|
680
|
+
providerSubscriptions.push(p.onAccountChange((e) => {
|
|
681
|
+
if (isDuplicateAccountEvent(e)) return
|
|
682
|
+
handleAccountChange(e)
|
|
683
|
+
for (const l of accountListeners) l(e)
|
|
684
|
+
}))
|
|
685
|
+
}
|
|
686
|
+
}
|
|
687
|
+
|
|
688
|
+
/**
|
|
689
|
+
* Collapses the same account event arriving from several providers at once.
|
|
690
|
+
*
|
|
691
|
+
* On Apple platforms `icloudKV` and `cloudKit` both listen to the same two
|
|
692
|
+
* system notifications and relabel them with their own provider name -
|
|
693
|
+
* correctly, because an Apple ID change matters to both. The consequence is
|
|
694
|
+
* that a store configured with both delivers one system event to app
|
|
695
|
+
* listeners twice.
|
|
696
|
+
*
|
|
697
|
+
* Deduplicated on the event's content rather than its provider, over a short
|
|
698
|
+
* window: the providers emit within the same tick, so anything that looks
|
|
699
|
+
* identical that soon after is the same underlying notification. A genuine
|
|
700
|
+
* second change of the same shape inside the window is vanishingly unlikely,
|
|
701
|
+
* and would only cost a repeat of work that is already idempotent.
|
|
702
|
+
*/
|
|
703
|
+
const ACCOUNT_EVENT_DEDUPE_MS = 250
|
|
704
|
+
let lastAccountEvent: { key: string; at: number } | null = null
|
|
705
|
+
|
|
706
|
+
function isDuplicateAccountEvent(e: AccountChangeEvent): boolean {
|
|
707
|
+
const key = `${e.status}\u0000${String(e.identityChanged)}`
|
|
708
|
+
const now = Date.now()
|
|
709
|
+
const seen = lastAccountEvent != null
|
|
710
|
+
&& lastAccountEvent.key === key
|
|
711
|
+
&& now - lastAccountEvent.at < ACCOUNT_EVENT_DEDUPE_MS
|
|
712
|
+
|
|
713
|
+
lastAccountEvent = { key, at: now }
|
|
714
|
+
return seen
|
|
715
|
+
}
|
|
716
|
+
|
|
717
|
+
/**
|
|
718
|
+
* The store's own reaction to an account event.
|
|
719
|
+
*
|
|
720
|
+
* A different Apple ID or Google account is now signed in, so three pieces of
|
|
721
|
+
* state belong to somebody who is no longer here: memoised availability,
|
|
722
|
+
* whatever the providers cached (Drive file ids, CloudKit reachability), and
|
|
723
|
+
* the outbox. Queued writes are the dangerous one - an entry carries no
|
|
724
|
+
* account identity, so flushing after a switch would write the previous
|
|
725
|
+
* user's data into the new user's account.
|
|
726
|
+
*/
|
|
727
|
+
function handleAccountChange(e: AccountChangeEvent): void {
|
|
728
|
+
invalidateAvailability()
|
|
729
|
+
if (!e.identityChanged) return
|
|
730
|
+
|
|
731
|
+
for (const name of options.providers)
|
|
732
|
+
try {
|
|
733
|
+
resolveProvider(name).clearCaches?.()
|
|
734
|
+
}
|
|
735
|
+
catch {
|
|
736
|
+
// Nothing to clear on a provider that will not resolve.
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
const pending = readOutbox()
|
|
740
|
+
if (pending.length === 0) return
|
|
741
|
+
writeOutbox([])
|
|
742
|
+
for (const entry of pending) reportDropped(entry, 'accountChanged')
|
|
743
|
+
}
|
|
744
|
+
|
|
745
|
+
// ------------------------------------------------------------------ read
|
|
746
|
+
|
|
747
|
+
/**
|
|
748
|
+
* Reads one key across the configured providers.
|
|
749
|
+
*
|
|
750
|
+
* Returns `{ found: false }` only when at least one provider was reachable
|
|
751
|
+
* and none of them held the key. When *nothing* was reachable the caller is
|
|
752
|
+
* told, because resolving `null` there is indistinguishable from "no such
|
|
753
|
+
* key" - and the documented first-launch recipe reacts to `null` by seeding
|
|
754
|
+
* empty state, which is how a signed-out user's real backup gets overwritten.
|
|
755
|
+
*/
|
|
756
|
+
async function readAcross(
|
|
757
|
+
key: string
|
|
758
|
+
): Promise<{ found: boolean; value: string | null; reachedAny: boolean }> {
|
|
759
|
+
let lastError: unknown = null
|
|
760
|
+
let reachedAny = false
|
|
761
|
+
|
|
762
|
+
// No resolver: first non-null wins and we stop looking. Cheap, and right
|
|
763
|
+
// when only one population of devices ever writes.
|
|
764
|
+
if (resolveValue == null) {
|
|
765
|
+
for (const name of options.providers) {
|
|
766
|
+
const p = resolveProvider(name)
|
|
767
|
+
try {
|
|
768
|
+
if (!(await isAvailable(p))) continue
|
|
769
|
+
const hit = await readOne(p, key)
|
|
770
|
+
reachedAny = true
|
|
771
|
+
if (hit != null) return { found: true, value: await decode(key, hit.value), reachedAny }
|
|
772
|
+
}
|
|
773
|
+
catch (e) {
|
|
774
|
+
lastError = e
|
|
775
|
+
}
|
|
776
|
+
}
|
|
777
|
+
if (lastError != null) throw normalizeError(lastError)
|
|
778
|
+
return { found: false, value: null, reachedAny }
|
|
779
|
+
}
|
|
780
|
+
|
|
781
|
+
// With a resolver: consult every available provider, because the first one
|
|
782
|
+
// holding a value is not necessarily holding the newest. This is what makes
|
|
783
|
+
// sync work in both directions across a mixed fleet.
|
|
784
|
+
const candidates: ResolveCandidate[] = []
|
|
785
|
+
const reachable = new Map<ProviderName, CloudProvider>()
|
|
786
|
+
|
|
787
|
+
for (const name of options.providers) {
|
|
788
|
+
const p = resolveProvider(name)
|
|
789
|
+
try {
|
|
790
|
+
if (!(await isAvailable(p))) continue
|
|
791
|
+
const hit = await readOne(p, key)
|
|
792
|
+
// Only a provider we actually read from is a repair target. Marking it
|
|
793
|
+
// reachable before the read meant a provider whose read merely failed
|
|
794
|
+
// - a transient network blip - was repaired too, overwriting whatever
|
|
795
|
+
// it held with another provider's value. If the copy we could not read
|
|
796
|
+
// was the newer one, that silently destroyed it.
|
|
797
|
+
reachable.set(p.name, p)
|
|
798
|
+
reachedAny = true
|
|
799
|
+
if (hit != null)
|
|
800
|
+
candidates.push({
|
|
801
|
+
provider: p.name,
|
|
802
|
+
value: await decode(key, hit.value),
|
|
803
|
+
modifiedAt: hit.modifiedAt,
|
|
804
|
+
})
|
|
805
|
+
}
|
|
806
|
+
catch (e) {
|
|
807
|
+
lastError = e
|
|
808
|
+
}
|
|
809
|
+
}
|
|
810
|
+
|
|
811
|
+
if (candidates.length === 0) {
|
|
812
|
+
if (lastError != null) throw normalizeError(lastError)
|
|
813
|
+
return { found: false, value: null, reachedAny }
|
|
814
|
+
}
|
|
815
|
+
|
|
816
|
+
const winner = resolveValue(candidates)
|
|
817
|
+
if (winner == null) return { found: false, value: null, reachedAny }
|
|
818
|
+
|
|
819
|
+
// Best-effort convergence. Never fails the read - the caller already has
|
|
820
|
+
// the right answer, and a failed repair only costs another resolve later.
|
|
821
|
+
if (repairOnRead) void repair(key, winner, candidates, reachable)
|
|
822
|
+
|
|
823
|
+
return { found: true, value: winner, reachedAny }
|
|
824
|
+
}
|
|
825
|
+
|
|
826
|
+
// ------------------------------------------------------------------ API
|
|
827
|
+
|
|
828
|
+
const store: CloudStore = {
|
|
829
|
+
getItem: async (key: string) => {
|
|
830
|
+
checkKey(key)
|
|
831
|
+
const result = await readAcross(key)
|
|
832
|
+
// Nothing was reachable, so this is not an absent key - it is an unknown
|
|
833
|
+
// one. Saying `null` here is the false negative the error contract exists
|
|
834
|
+
// to prevent.
|
|
835
|
+
if (!result.reachedAny) throw noneAvailable()
|
|
836
|
+
return result.found ? result.value : null
|
|
837
|
+
},
|
|
838
|
+
|
|
839
|
+
setItem: async (key: string, value: string) => {
|
|
840
|
+
checkKey(key)
|
|
841
|
+
const stored = await encode(key, value)
|
|
842
|
+
|
|
843
|
+
if (writeMode === 'failover') {
|
|
844
|
+
const target = await providerForSize(stored, await primary())
|
|
845
|
+
await writeOne(target, key, stored)
|
|
846
|
+
return
|
|
847
|
+
}
|
|
848
|
+
await writeMany(await allAvailable(), key, stored)
|
|
849
|
+
},
|
|
850
|
+
|
|
851
|
+
removeItem: async (key: string) => {
|
|
852
|
+
checkKey(key)
|
|
853
|
+
// A mirrored write must be a mirrored delete. Removing from only the
|
|
854
|
+
// preferred provider would leave a copy behind that reads then fall
|
|
855
|
+
// through to and resurrect.
|
|
856
|
+
const targets = writeMode === 'mirror' ? await allAvailable() : [await primary()]
|
|
857
|
+
await removeMany(targets, key)
|
|
858
|
+
},
|
|
859
|
+
|
|
860
|
+
getAllKeys: async () => {
|
|
861
|
+
const seen = new Set<string>()
|
|
862
|
+
for (const name of options.providers) {
|
|
863
|
+
const p = resolveProvider(name)
|
|
864
|
+
try {
|
|
865
|
+
if (!(await isAvailable(p))) continue
|
|
866
|
+
for (const k of await run(p, () => p.getAllKeys())) seen.add(k)
|
|
867
|
+
}
|
|
868
|
+
catch {
|
|
869
|
+
// A provider that cannot list should not hide the ones that can.
|
|
870
|
+
}
|
|
871
|
+
}
|
|
872
|
+
return [...seen]
|
|
873
|
+
},
|
|
874
|
+
|
|
875
|
+
multiGet: async (keys: string[]) => {
|
|
876
|
+
for (const key of keys) checkKey(key)
|
|
877
|
+
if (keys.length === 0) return []
|
|
878
|
+
|
|
879
|
+
const answers = new Map<string, string | null>()
|
|
880
|
+
|
|
881
|
+
// A resolving read has to see every provider's copy of every key, so
|
|
882
|
+
// there is no early exit to exploit - but each provider is still a single
|
|
883
|
+
// batched request rather than one per key.
|
|
884
|
+
if (resolveValue != null) {
|
|
885
|
+
const perKey = new Map<string, ResolveCandidate[]>(keys.map(k => [k, []]))
|
|
886
|
+
let reachedAny = false
|
|
887
|
+
|
|
888
|
+
for (const name of options.providers) {
|
|
889
|
+
const p = resolveProvider(name)
|
|
890
|
+
try {
|
|
891
|
+
if (!(await isAvailable(p))) continue
|
|
892
|
+
const values = await readBatch(p, keys)
|
|
893
|
+
reachedAny = true
|
|
894
|
+
for (let i = 0; i < keys.length; i += 1) {
|
|
895
|
+
const raw = values[i]
|
|
896
|
+
if (raw == null) continue
|
|
897
|
+
perKey.get(keys[i])!.push({ provider: p.name, value: await decode(keys[i], raw) })
|
|
898
|
+
}
|
|
899
|
+
}
|
|
900
|
+
catch {
|
|
901
|
+
// Same rule as `getAllKeys`: one provider failing to answer must not
|
|
902
|
+
// erase the answers the others gave.
|
|
903
|
+
}
|
|
904
|
+
}
|
|
905
|
+
|
|
906
|
+
if (!reachedAny) throw noneAvailable()
|
|
907
|
+
for (const key of keys) {
|
|
908
|
+
const candidates = perKey.get(key)!
|
|
909
|
+
answers.set(key, candidates.length === 0 ? null : resolveValue(candidates))
|
|
910
|
+
}
|
|
911
|
+
return keys.map(k => [k, answers.get(k) ?? null] as [string, string | null])
|
|
912
|
+
}
|
|
913
|
+
|
|
914
|
+
// No resolver: ask each provider only for the keys still unanswered, so a
|
|
915
|
+
// second provider is consulted for the tail rather than for everything.
|
|
916
|
+
let outstanding = [...keys]
|
|
917
|
+
let reachedAny = false
|
|
918
|
+
|
|
919
|
+
for (const name of options.providers) {
|
|
920
|
+
if (outstanding.length === 0) break
|
|
921
|
+
const p = resolveProvider(name)
|
|
922
|
+
try {
|
|
923
|
+
if (!(await isAvailable(p))) continue
|
|
924
|
+
const values = await readBatch(p, outstanding)
|
|
925
|
+
reachedAny = true
|
|
926
|
+
const stillMissing: string[] = []
|
|
927
|
+
for (let i = 0; i < outstanding.length; i += 1) {
|
|
928
|
+
const raw = values[i]
|
|
929
|
+
if (raw == null) stillMissing.push(outstanding[i])
|
|
930
|
+
else answers.set(outstanding[i], await decode(outstanding[i], raw))
|
|
931
|
+
}
|
|
932
|
+
outstanding = stillMissing
|
|
933
|
+
}
|
|
934
|
+
catch {
|
|
935
|
+
// Leave those keys outstanding for the next provider.
|
|
936
|
+
}
|
|
937
|
+
}
|
|
938
|
+
|
|
939
|
+
if (!reachedAny) throw noneAvailable()
|
|
940
|
+
return keys.map(k => [k, answers.get(k) ?? null] as [string, string | null])
|
|
941
|
+
},
|
|
942
|
+
|
|
943
|
+
multiSet: async (entries: [string, string][]) => {
|
|
944
|
+
for (const [key] of entries) checkKey(key)
|
|
945
|
+
if (entries.length === 0) return
|
|
946
|
+
|
|
947
|
+
const encoded: [string, string][] = []
|
|
948
|
+
for (const [key, value] of entries) encoded.push([key, await encode(key, value)])
|
|
949
|
+
|
|
950
|
+
if (writeMode === 'failover') {
|
|
951
|
+
// Tiering can route two values in the same batch to two different
|
|
952
|
+
// providers, so group by destination rather than assuming one target.
|
|
953
|
+
const preferred = await primary()
|
|
954
|
+
const byTarget = new Map<string, { provider: CloudProvider; items: [string, string][] }>()
|
|
955
|
+
|
|
956
|
+
for (const [key, value] of encoded) {
|
|
957
|
+
const target = await providerForSize(value, preferred)
|
|
958
|
+
const bucket = byTarget.get(target.name)
|
|
959
|
+
?? { provider: target, items: [] as [string, string][] }
|
|
960
|
+
bucket.items.push([key, value])
|
|
961
|
+
byTarget.set(target.name, bucket)
|
|
962
|
+
}
|
|
963
|
+
|
|
964
|
+
for (const { provider, items } of byTarget.values())
|
|
965
|
+
try {
|
|
966
|
+
await writeBatch(provider, items)
|
|
967
|
+
dequeueMany(items.map(([k]) => k), provider.name)
|
|
968
|
+
}
|
|
969
|
+
catch (e) {
|
|
970
|
+
const err = normalizeError(e, provider.name)
|
|
971
|
+
if (useOutbox && isRetryable(err)) {
|
|
972
|
+
for (const [key, value] of items) enqueue(key, value, provider.name, err.code)
|
|
973
|
+
options.onError?.(err)
|
|
974
|
+
continue
|
|
975
|
+
}
|
|
976
|
+
throw err
|
|
977
|
+
}
|
|
978
|
+
return
|
|
979
|
+
}
|
|
980
|
+
|
|
981
|
+
const targets = await allAvailable()
|
|
982
|
+
if (targets.length === 0) throw noneAvailable()
|
|
983
|
+
|
|
984
|
+
let anyStored = false
|
|
985
|
+
let fatal: CloudSyncError | null = null
|
|
986
|
+
|
|
987
|
+
for (const target of targets) {
|
|
988
|
+
const fits = encoded.filter(([, value]) => canHold(target, value))
|
|
989
|
+
if (fits.length === 0) continue
|
|
990
|
+
try {
|
|
991
|
+
await writeBatch(target, fits)
|
|
992
|
+
dequeueMany(fits.map(([k]) => k), target.name)
|
|
993
|
+
anyStored = true
|
|
994
|
+
}
|
|
995
|
+
catch (e) {
|
|
996
|
+
const err = normalizeError(e, target.name)
|
|
997
|
+
if (useOutbox && isRetryable(err)) {
|
|
998
|
+
for (const [key, value] of fits) enqueue(key, value, target.name, err.code)
|
|
999
|
+
options.onError?.(err)
|
|
1000
|
+
continue
|
|
1001
|
+
}
|
|
1002
|
+
fatal ??= err
|
|
1003
|
+
options.onError?.(err)
|
|
1004
|
+
}
|
|
1005
|
+
}
|
|
1006
|
+
|
|
1007
|
+
if (anyStored)
|
|
1008
|
+
for (const [key, value] of encoded) await evictWhereTooLarge(targets, key, value)
|
|
1009
|
+
|
|
1010
|
+
if (!anyStored && fatal != null) throw fatal
|
|
1011
|
+
if (!anyStored && fatal == null) {
|
|
1012
|
+
const bytes = Math.max(...encoded.map(([, v]) => byteLength(v)))
|
|
1013
|
+
throw new CloudSyncError(
|
|
1014
|
+
ErrorCode.PAYLOAD_TOO_LARGE,
|
|
1015
|
+
`[RNCloudSync] No configured provider can hold these values (largest is ${bytes} bytes).`,
|
|
1016
|
+
{ actualBytes: bytes }
|
|
1017
|
+
)
|
|
1018
|
+
}
|
|
1019
|
+
},
|
|
1020
|
+
|
|
1021
|
+
multiRemove: async (keys: string[]) => {
|
|
1022
|
+
for (const key of keys) checkKey(key)
|
|
1023
|
+
if (keys.length === 0) return
|
|
1024
|
+
|
|
1025
|
+
const targets = writeMode === 'mirror' ? await allAvailable() : [await primary()]
|
|
1026
|
+
if (targets.length === 0) throw noneAvailable()
|
|
1027
|
+
|
|
1028
|
+
let removedAnywhere = false
|
|
1029
|
+
let fatal: CloudSyncError | null = null
|
|
1030
|
+
|
|
1031
|
+
for (const target of targets)
|
|
1032
|
+
try {
|
|
1033
|
+
await removeBatch(target, keys)
|
|
1034
|
+
dequeueMany(keys, target.name)
|
|
1035
|
+
removedAnywhere = true
|
|
1036
|
+
}
|
|
1037
|
+
catch (e) {
|
|
1038
|
+
const err = normalizeError(e, target.name)
|
|
1039
|
+
if (useOutbox && isRetryable(err)) {
|
|
1040
|
+
for (const key of keys) enqueue(key, null, target.name, err.code)
|
|
1041
|
+
options.onError?.(err)
|
|
1042
|
+
continue
|
|
1043
|
+
}
|
|
1044
|
+
fatal ??= err
|
|
1045
|
+
options.onError?.(err)
|
|
1046
|
+
}
|
|
1047
|
+
|
|
1048
|
+
if (!removedAnywhere && fatal != null) throw fatal
|
|
1049
|
+
},
|
|
1050
|
+
|
|
1051
|
+
clear: async () => {
|
|
1052
|
+
const keys = await store.getAllKeys()
|
|
1053
|
+
if (keys.length === 0) return { removed: [] }
|
|
1054
|
+
await store.multiRemove(keys)
|
|
1055
|
+
return { removed: keys }
|
|
1056
|
+
},
|
|
1057
|
+
|
|
1058
|
+
getAllItems: async () => {
|
|
1059
|
+
const keys = await store.getAllKeys()
|
|
1060
|
+
if (keys.length === 0) return {}
|
|
1061
|
+
|
|
1062
|
+
const out: Record<string, string> = {}
|
|
1063
|
+
for (const [key, value] of await store.multiGet(keys))
|
|
1064
|
+
if (value != null) out[key] = value
|
|
1065
|
+
|
|
1066
|
+
return out
|
|
1067
|
+
},
|
|
1068
|
+
|
|
1069
|
+
getQuota: async () => {
|
|
1070
|
+
const out: QuotaInfo[] = []
|
|
1071
|
+
for (const name of options.providers) {
|
|
1072
|
+
const p = resolveProvider(name)
|
|
1073
|
+
if (p.getQuota == null) continue
|
|
1074
|
+
try {
|
|
1075
|
+
if (!(await isAvailable(p))) continue
|
|
1076
|
+
const quota = await run(p, () => p.getQuota!())
|
|
1077
|
+
if (quota != null) out.push(quota)
|
|
1078
|
+
}
|
|
1079
|
+
catch (e) {
|
|
1080
|
+
options.onError?.(normalizeError(e, name))
|
|
1081
|
+
}
|
|
1082
|
+
}
|
|
1083
|
+
return out
|
|
1084
|
+
},
|
|
1085
|
+
|
|
1086
|
+
migrate: async ({ from, to, continueOnError = true, filter, onProgress }) => {
|
|
1087
|
+
const src = resolveProvider(from)
|
|
1088
|
+
const dst = resolveProvider(to)
|
|
1089
|
+
const all = await run(src, () => src.getAllKeys())
|
|
1090
|
+
const keys = filter == null ? all : all.filter(filter)
|
|
1091
|
+
|
|
1092
|
+
const copied: string[] = []
|
|
1093
|
+
const skipped: string[] = []
|
|
1094
|
+
const failed: { key: string; error: CloudSyncError }[] = []
|
|
1095
|
+
|
|
1096
|
+
// Values move verbatim. Both ends sit behind the same codec, so decoding
|
|
1097
|
+
// on the way out only to re-encode on the way in would be wasted work -
|
|
1098
|
+
// and, for a codec with a random nonce, would rewrite every byte.
|
|
1099
|
+
for (const key of keys) {
|
|
1100
|
+
try {
|
|
1101
|
+
const value = await run(src, () => src.getItem(key))
|
|
1102
|
+
if (value == null) {
|
|
1103
|
+
skipped.push(key)
|
|
1104
|
+
}
|
|
1105
|
+
else {
|
|
1106
|
+
await run(dst, () => dst.setItem(key, value))
|
|
1107
|
+
copied.push(key)
|
|
1108
|
+
}
|
|
1109
|
+
}
|
|
1110
|
+
catch (e) {
|
|
1111
|
+
const err = normalizeError(e, from)
|
|
1112
|
+
failed.push({ key, error: err })
|
|
1113
|
+
options.onError?.(err)
|
|
1114
|
+
// Aborting on the first bad key leaves the user half migrated with no
|
|
1115
|
+
// record of how far it got, which is the worst of both outcomes.
|
|
1116
|
+
if (!continueOnError) break
|
|
1117
|
+
}
|
|
1118
|
+
onProgress?.(copied.length + skipped.length + failed.length, keys.length)
|
|
1119
|
+
}
|
|
1120
|
+
|
|
1121
|
+
return { copied, skipped, failed }
|
|
1122
|
+
},
|
|
1123
|
+
|
|
1124
|
+
flushOutbox: async () => {
|
|
1125
|
+
// Two flushes at once - a reconnect and a foreground firing together -
|
|
1126
|
+
// would each snapshot the queue and each re-send every entry in it.
|
|
1127
|
+
if (flushing != null) return await flushing
|
|
1128
|
+
flushing = drain().finally(() => {
|
|
1129
|
+
flushing = null
|
|
1130
|
+
})
|
|
1131
|
+
return await flushing
|
|
1132
|
+
},
|
|
1133
|
+
|
|
1134
|
+
pendingWrites: () => readOutbox(),
|
|
1135
|
+
|
|
1136
|
+
discardPendingWrites: (filter) => {
|
|
1137
|
+
const entries = readOutbox()
|
|
1138
|
+
const kept: OutboxEntry[] = []
|
|
1139
|
+
const removed: OutboxEntry[] = []
|
|
1140
|
+
for (const entry of entries)
|
|
1141
|
+
if (filter == null || filter(entry)) removed.push(entry)
|
|
1142
|
+
else kept.push(entry)
|
|
1143
|
+
|
|
1144
|
+
if (removed.length === 0) return 0
|
|
1145
|
+
writeOutbox(kept)
|
|
1146
|
+
for (const entry of removed) reportDropped(entry, 'discarded')
|
|
1147
|
+
return removed.length
|
|
1148
|
+
},
|
|
1149
|
+
|
|
1150
|
+
registerProvider: (provider: CloudProvider) => {
|
|
1151
|
+
custom.set(provider.name, provider)
|
|
1152
|
+
availability.delete(provider.name)
|
|
1153
|
+
// A provider registered after the first subscription would otherwise
|
|
1154
|
+
// never be listened to. Cheapest correct fix is to resubscribe.
|
|
1155
|
+
if (providerSubscriptions != null) {
|
|
1156
|
+
for (const un of providerSubscriptions) un()
|
|
1157
|
+
providerSubscriptions = null
|
|
1158
|
+
if (remoteListeners.size > 0 || accountListeners.size > 0) ensureSubscribed()
|
|
1159
|
+
}
|
|
1160
|
+
},
|
|
1161
|
+
|
|
1162
|
+
onRemoteChange: (listener) => {
|
|
1163
|
+
ensureSubscribed()
|
|
1164
|
+
remoteListeners.add(listener)
|
|
1165
|
+
return () => {
|
|
1166
|
+
remoteListeners.delete(listener)
|
|
1167
|
+
}
|
|
1168
|
+
},
|
|
1169
|
+
|
|
1170
|
+
onAccountChange: (listener) => {
|
|
1171
|
+
ensureSubscribed()
|
|
1172
|
+
accountListeners.add(listener)
|
|
1173
|
+
return () => {
|
|
1174
|
+
accountListeners.delete(listener)
|
|
1175
|
+
}
|
|
1176
|
+
},
|
|
1177
|
+
|
|
1178
|
+
dispose: () => {
|
|
1179
|
+
if (providerSubscriptions != null) for (const un of providerSubscriptions) un()
|
|
1180
|
+
providerSubscriptions = null
|
|
1181
|
+
remoteListeners.clear()
|
|
1182
|
+
accountListeners.clear()
|
|
1183
|
+
detachAutoFlush?.()
|
|
1184
|
+
detachAutoFlush = null
|
|
1185
|
+
},
|
|
1186
|
+
}
|
|
1187
|
+
|
|
1188
|
+
// Attached last, so the store it flushes is fully built by the time the first
|
|
1189
|
+
// foreground event or timer tick can reach it.
|
|
1190
|
+
let detachAutoFlush: Unsubscribe | null = null
|
|
1191
|
+
if (options.autoFlush != null && options.autoFlush !== false)
|
|
1192
|
+
detachAutoFlush = attachAutoFlush(
|
|
1193
|
+
() => store.flushOutbox(),
|
|
1194
|
+
options.autoFlush === true ? {} : options.autoFlush
|
|
1195
|
+
)
|
|
1196
|
+
|
|
1197
|
+
async function drain(): Promise<FlushResult> {
|
|
1198
|
+
const entries = readOutbox()
|
|
1199
|
+
if (entries.length === 0) return { drained: 0, remaining: 0, dropped: [] }
|
|
1200
|
+
|
|
1201
|
+
const now = Date.now()
|
|
1202
|
+
const keep: OutboxEntry[] = []
|
|
1203
|
+
const dropped: DroppedWrite[] = []
|
|
1204
|
+
const handled = new Set<string>()
|
|
1205
|
+
let drained = 0
|
|
1206
|
+
|
|
1207
|
+
function drop(entry: OutboxEntry, reason: DropReason, error?: CloudSyncError): void {
|
|
1208
|
+
dropped.push({ entry, reason, error })
|
|
1209
|
+
reportDropped(entry, reason, error)
|
|
1210
|
+
}
|
|
1211
|
+
|
|
1212
|
+
for (const entry of entries) {
|
|
1213
|
+
handled.add(outboxId(entry.provider, entry.key))
|
|
1214
|
+
|
|
1215
|
+
if (now - entry.enqueuedAt > maxAgeMs) {
|
|
1216
|
+
drop(entry, 'expired')
|
|
1217
|
+
continue
|
|
1218
|
+
}
|
|
1219
|
+
if (entry.nextAttemptAt > now) {
|
|
1220
|
+
keep.push(entry)
|
|
1221
|
+
continue
|
|
1222
|
+
}
|
|
1223
|
+
|
|
1224
|
+
let p: CloudProvider
|
|
1225
|
+
try {
|
|
1226
|
+
p = resolveProvider(entry.provider)
|
|
1227
|
+
}
|
|
1228
|
+
catch (e) {
|
|
1229
|
+
// The provider it targeted is gone. Nothing will ever drain this.
|
|
1230
|
+
drop(entry, 'notRetryable', normalizeError(e, entry.provider))
|
|
1231
|
+
continue
|
|
1232
|
+
}
|
|
1233
|
+
|
|
1234
|
+
try {
|
|
1235
|
+
if (entry.value == null) await run(p, () => p.removeItem(entry.key))
|
|
1236
|
+
else await run(p, () => p.setItem(entry.key, entry.value!))
|
|
1237
|
+
drained += 1
|
|
1238
|
+
}
|
|
1239
|
+
catch (e) {
|
|
1240
|
+
const err = normalizeError(e, entry.provider)
|
|
1241
|
+
options.onError?.(err)
|
|
1242
|
+
|
|
1243
|
+
// A write only enters the queue for a retryable reason. If retrying it
|
|
1244
|
+
// now fails for one the user must act on - quota, signed out, a payload
|
|
1245
|
+
// the store will never accept - re-queueing turns it into a poison
|
|
1246
|
+
// entry that retries forever, never drains, and never surfaces.
|
|
1247
|
+
if (!isRetryable(err)) {
|
|
1248
|
+
drop(entry, 'notRetryable', err)
|
|
1249
|
+
continue
|
|
1250
|
+
}
|
|
1251
|
+
|
|
1252
|
+
const attempts = entry.attempts + 1
|
|
1253
|
+
if (attempts >= maxAttempts) {
|
|
1254
|
+
drop({ ...entry, attempts, lastErrorCode: err.code }, 'tooManyAttempts', err)
|
|
1255
|
+
continue
|
|
1256
|
+
}
|
|
1257
|
+
|
|
1258
|
+
// Exponential backoff, honouring a server-supplied retry hint when
|
|
1259
|
+
// there is one (CloudKit sends `retryAfter`, Drive `Retry-After`).
|
|
1260
|
+
const backoff = err.retryAfterMs ?? Math.min(2 ** attempts * 1000, 5 * 60_000)
|
|
1261
|
+
keep.push({
|
|
1262
|
+
...entry,
|
|
1263
|
+
attempts,
|
|
1264
|
+
nextAttemptAt: Date.now() + backoff,
|
|
1265
|
+
lastErrorCode: err.code,
|
|
1266
|
+
})
|
|
1267
|
+
}
|
|
1268
|
+
}
|
|
1269
|
+
|
|
1270
|
+
// Merge rather than overwrite. A `setItem` that failed while this flush was
|
|
1271
|
+
// awaiting the network enqueued itself into storage; writing the snapshot
|
|
1272
|
+
// back wholesale would silently discard it.
|
|
1273
|
+
const arrived = readOutbox().filter(e => !handled.has(outboxId(e.provider, e.key)))
|
|
1274
|
+
writeOutbox([...keep, ...arrived])
|
|
1275
|
+
|
|
1276
|
+
return { drained, remaining: keep.length + arrived.length, dropped }
|
|
1277
|
+
}
|
|
1278
|
+
|
|
1279
|
+
return store
|
|
1280
|
+
}
|
|
1281
|
+
|
|
1282
|
+
function createMemoryOutboxStorage(): OutboxStorage {
|
|
1283
|
+
const map = new Map<string, string>()
|
|
1284
|
+
return {
|
|
1285
|
+
getString: (k: string) => map.get(k),
|
|
1286
|
+
set: (k: string, v: string) => { map.set(k, v) },
|
|
1287
|
+
}
|
|
1288
|
+
}
|