@litebackup/sdk 0.0.0-stage → 0.3.18

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.
@@ -0,0 +1,284 @@
1
+ import { isAbsolute, resolve } from "node:path";
2
+ import { Backup } from "./backup.js";
3
+ import { camelize } from "./case.js";
4
+ import { milliseconds } from "./duration.js";
5
+ import { Failover } from "./failover.js";
6
+ import { launchDaemon } from "./launch.js";
7
+ import { sessionSocket } from "./paths.js";
8
+ import { socketFetch } from "./socket.js";
9
+ import { LitebackupError, sdkVersion, } from "./types.js";
10
+ /** Header names of the daemon's version negotiation. */
11
+ const sdkVersionHeader = "x-litebackup-sdk-version";
12
+ const clientVersionHeader = "x-litebackup-client-version";
13
+ /** Resolves a path against the working directory; the daemon needs absolute paths. */
14
+ export function absolutePath(path) {
15
+ return isAbsolute(path) ? resolve(path) : resolve(process.cwd(), path);
16
+ }
17
+ /** Talks to the Litebackup daemon of one session over its unix socket. */
18
+ export class Litebackup {
19
+ session;
20
+ socketPath;
21
+ /** The daemon's version, known after the first call. */
22
+ clientVersion = "";
23
+ /** Backups and failovers running on this machine. */
24
+ backups;
25
+ /** Prefix replicas and replicas on this machine. */
26
+ replicas;
27
+ /** Local copies set aside because they diverged: list and delete. */
28
+ conflicts;
29
+ /** @internal */
30
+ /** Failovers this client follows; close() stops following them. @internal */
31
+ failovers = new Set();
32
+ /** @internal */
33
+ closed = false;
34
+ /** Use Litebackup.connect, which starts the daemon when needed. */
35
+ constructor(session, socketPath) {
36
+ this.session = session;
37
+ this.socketPath = socketPath;
38
+ this.backups = {
39
+ list: async () => (await this.call("GET", "/v1/backups/list")).backups,
40
+ stop: async (target) => {
41
+ const body = "path" in target ? { path: absolutePath(target.path) } : target;
42
+ await this.call("POST", "/v1/backups/stop", body);
43
+ },
44
+ };
45
+ this.replicas = {
46
+ list: () => this.call("GET", "/v1/replicas/list"),
47
+ stop: async (name) => {
48
+ await this.call("POST", "/v1/replicas/stop", { name });
49
+ },
50
+ };
51
+ this.conflicts = {
52
+ list: async () => (await this.call("GET", "/v1/conflicts/list")).conflicts,
53
+ delete: async (id) => {
54
+ await this.call("POST", "/v1/conflicts/delete", { id });
55
+ },
56
+ };
57
+ }
58
+ /** Connects to a session, starting its daemon like the CLI does. */
59
+ static async connect(options = {}) {
60
+ const environment = options.environment ?? process.env;
61
+ let session = options.session ?? "";
62
+ let socketPath = options.socketPath;
63
+ if (!socketPath) {
64
+ const resolved = sessionSocket(options.session, environment);
65
+ session = resolved.session;
66
+ socketPath = resolved.socketPath;
67
+ if (options.launch !== false) {
68
+ await launchDaemon({ session, socketPath, environment, token: options.token });
69
+ }
70
+ }
71
+ const litebackup = new Litebackup(session, socketPath);
72
+ await litebackup.status();
73
+ return litebackup;
74
+ }
75
+ /**
76
+ * Sends one call and decodes its JSON answer into camelCase, throwing
77
+ * LitebackupError on failure.
78
+ * @internal
79
+ */
80
+ async call(method, path, body, signal) {
81
+ const response = await socketFetch({
82
+ socketPath: this.socketPath,
83
+ method,
84
+ path,
85
+ headers: { [sdkVersionHeader]: `typescript/${sdkVersion}` },
86
+ body: body === undefined ? undefined : JSON.stringify(body),
87
+ signal,
88
+ });
89
+ this.clientVersion = response.headers[clientVersionHeader] ?? this.clientVersion;
90
+ if (response.status !== 200) {
91
+ let code = `http_${response.status}`;
92
+ let message = response.body.trim();
93
+ try {
94
+ const decoded = JSON.parse(response.body);
95
+ code = decoded.code ?? code;
96
+ message = decoded.message ?? message;
97
+ }
98
+ catch {
99
+ // A non-JSON error body keeps its text as the message.
100
+ }
101
+ throw new LitebackupError(code, message, response.status);
102
+ }
103
+ return camelize(JSON.parse(response.body));
104
+ }
105
+ /**
106
+ * Backs up a database, given as a path or a better-sqlite3 handle, and
107
+ * keeps syncing it. Returns at once; see Backup for how failures surface.
108
+ */
109
+ backup(source, options = {}) {
110
+ return new Backup(Promise.resolve(this), source, options);
111
+ }
112
+ /**
113
+ * Runs a database on several identical machines: the first to take the
114
+ * write lock is the origin, the others keep live read-only replicas at the
115
+ * same path and take over when the origin's lease runs out.
116
+ */
117
+ failover(path, options = {}) {
118
+ return Failover.start(this, path, options);
119
+ }
120
+ /** Keeps a live read-only replica of a database and resolves once its first version is local. */
121
+ async replicate(name, options = {}) {
122
+ const body = { name };
123
+ if (options.to) {
124
+ body.to = absolutePath(options.to);
125
+ }
126
+ if (options.writeProtection) {
127
+ body.write_protection = options.writeProtection;
128
+ }
129
+ if (options.timeout !== undefined) {
130
+ body.timeout_millis = milliseconds(options.timeout);
131
+ }
132
+ const result = (await this.call("POST", "/v1/replicas/start", body));
133
+ if (!result.database) {
134
+ throw new LitebackupError("invalid_response", "the daemon did not return the replica", 200);
135
+ }
136
+ return result.database;
137
+ }
138
+ /** Writes a version of a database to a new file and checks it. An existing file is never overwritten (exists). */
139
+ restore(name, options) {
140
+ if (!options?.to) {
141
+ throw new LitebackupError("invalid_argument", "restore needs a path to write to", 0);
142
+ }
143
+ if (options.version !== undefined && options.time !== undefined) {
144
+ throw new LitebackupError("invalid_argument", "restore takes a version or a time, not both", 0);
145
+ }
146
+ const body = { name, path: absolutePath(options.to) };
147
+ if (options.version !== undefined) {
148
+ body.version = options.version;
149
+ }
150
+ if (options.time !== undefined) {
151
+ body.time = options.time instanceof Date ? options.time.toISOString() : options.time;
152
+ }
153
+ return this.call("POST", "/v1/databases/restore", body);
154
+ }
155
+ /** The versions of a database the server can restore, oldest first. */
156
+ async versions(name, options = {}) {
157
+ const versions = [];
158
+ let after = options.after ?? 0;
159
+ for (;;) {
160
+ const query = new URLSearchParams({ name });
161
+ if (after > 0) {
162
+ query.set("after", String(after));
163
+ }
164
+ if (options.limit !== undefined) {
165
+ query.set("limit", String(options.limit - versions.length));
166
+ }
167
+ const page = (await this.call("GET", `/v1/databases/versions?${query}`));
168
+ versions.push(...page.versions);
169
+ const limited = options.limit !== undefined && versions.length >= options.limit;
170
+ if (!page.next || page.next <= after || page.versions.length === 0 || limited) {
171
+ return versions;
172
+ }
173
+ after = page.next;
174
+ }
175
+ }
176
+ /** Takes the write lock on a database and makes the local file the server head, for worker pools that move databases between machines. */
177
+ acquire(name, options = {}) {
178
+ const body = { name };
179
+ if (options.to) {
180
+ body.path = absolutePath(options.to);
181
+ }
182
+ if (options.maintenance !== undefined) {
183
+ body.maintenance = options.maintenance;
184
+ }
185
+ if (options.offload) {
186
+ body.offload = options.offload;
187
+ }
188
+ if (options.machineLabel) {
189
+ body.machine_label = options.machineLabel;
190
+ }
191
+ if (options.onLost) {
192
+ body.on_lost = options.onLost;
193
+ }
194
+ if (options.timeout !== undefined) {
195
+ body.timeout_millis = milliseconds(options.timeout);
196
+ }
197
+ return this.call("POST", "/v1/databases/acquire", body);
198
+ }
199
+ /** Syncs an acquired database a final time, runs its maintenance, and releases its write lock. */
200
+ release(name, options = {}) {
201
+ const body = { name };
202
+ if (options.wait) {
203
+ body.wait = options.wait;
204
+ }
205
+ if (options.offload !== undefined) {
206
+ body.offload = options.offload;
207
+ }
208
+ if (options.timeout !== undefined) {
209
+ body.timeout_millis = milliseconds(options.timeout);
210
+ }
211
+ return this.call("POST", "/v1/databases/release", body);
212
+ }
213
+ /** Which machine writes a database, when its lease runs out, and whether it ran out. */
214
+ writer(name) {
215
+ return this.call("GET", `/v1/databases/writer?${new URLSearchParams({ name })}`);
216
+ }
217
+ /** The session, its server, and every database on this machine. */
218
+ status() {
219
+ return this.call("GET", "/v1/status/show");
220
+ }
221
+ /** Every database on this machine with its role and state. */
222
+ async databases() {
223
+ return (await this.call("GET", "/v1/databases/list")).databases;
224
+ }
225
+ /** One database: its role, state, and the versions the server and the bucket hold. */
226
+ database(name) {
227
+ return this.call("GET", `/v1/databases/status?${new URLSearchParams({ name })}`);
228
+ }
229
+ /** Syncs a database now and resolves once the server acknowledged it. */
230
+ sync(name) {
231
+ return this.call("POST", "/v1/databases/sync", { name });
232
+ }
233
+ /** Removes the local file of a released database once the bucket holds its last version; acquire brings it back. */
234
+ offload(name) {
235
+ return this.call("POST", "/v1/databases/offload", { name });
236
+ }
237
+ /** One page of events after an ID, waiting up to waitMillis for the first. */
238
+ async eventPage(options = {}) {
239
+ const query = new URLSearchParams();
240
+ if (options.after) {
241
+ // -1 answers no events and, as next, where the log ends.
242
+ query.set("after", String(options.after));
243
+ }
244
+ if (options.waitMillis) {
245
+ query.set("wait_millis", String(options.waitMillis));
246
+ }
247
+ if (options.limit) {
248
+ query.set("limit", String(options.limit));
249
+ }
250
+ const suffix = query.size > 0 ? `?${query}` : "";
251
+ return this.call("GET", `/v1/events/list${suffix}`, undefined, options.signal);
252
+ }
253
+ /** Yields events, oldest first, by long-polling the daemon until the signal aborts. */
254
+ async *events(options = {}) {
255
+ let after = options.after ?? 0;
256
+ const waitMillis = milliseconds(options.wait ?? 30_000);
257
+ while (!options.signal?.aborted) {
258
+ const page = await this.eventPage({ after, waitMillis, signal: options.signal });
259
+ for (const event of page.events) {
260
+ yield event;
261
+ }
262
+ after = Math.max(after, page.next);
263
+ }
264
+ }
265
+ /** Syncs every database a final time, releases every write lock, ends the session, and stops the daemon. */
266
+ shutdown(options = {}) {
267
+ const body = {};
268
+ if (options.wait) {
269
+ body.wait = options.wait;
270
+ }
271
+ if (options.timeout !== undefined) {
272
+ body.timeout_millis = milliseconds(options.timeout);
273
+ }
274
+ return this.call("POST", "/v1/session/shutdown", body);
275
+ }
276
+ /** Stops watching failovers. The daemon keeps running. */
277
+ close() {
278
+ this.closed = true;
279
+ for (const failover of this.failovers) {
280
+ failover.end();
281
+ }
282
+ this.failovers.clear();
283
+ }
284
+ }
@@ -0,0 +1,4 @@
1
+ /** Milliseconds as a number, or a duration such as "500ms", "60s", "2m", or "1h". */
2
+ export type Duration = number | string;
3
+ /** Converts a Duration to whole milliseconds. */
4
+ export declare function milliseconds(duration: Duration): number;
@@ -0,0 +1,15 @@
1
+ const units = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
2
+ /** Converts a Duration to whole milliseconds. */
3
+ export function milliseconds(duration) {
4
+ if (typeof duration === "number") {
5
+ if (!Number.isFinite(duration) || duration < 0) {
6
+ throw new TypeError(`a duration must be a non-negative number of milliseconds, got ${duration}`);
7
+ }
8
+ return Math.round(duration);
9
+ }
10
+ const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)\s*$/.exec(duration);
11
+ if (!match) {
12
+ throw new TypeError(`durations look like 500ms, 60s, 2m, or 1h, got ${JSON.stringify(duration)}`);
13
+ }
14
+ return Math.round(Number(match[1]) * units[match[2]]);
15
+ }
@@ -0,0 +1,69 @@
1
+ import { type Litebackup } from "./client.js";
2
+ import { type Duration } from "./duration.js";
3
+ import { type FailoverInfo, type LitebackupEvent, type Role, type Writer } from "./types.js";
4
+ /** Options for failover. */
5
+ export interface FailoverOptions {
6
+ /** The database name; defaults to the normalized file name. */
7
+ name?: string;
8
+ /** Bound on the first download of a replica. */
9
+ timeout?: Duration;
10
+ /** Join token for the shared client; defaults to LITEBACKUP_TOKEN. Used only by the package-level failover(). */
11
+ token?: string;
12
+ /** Session for the shared client. Used only by the package-level failover(). */
13
+ session?: string;
14
+ }
15
+ /** The events a Failover reports, with their listener arguments. */
16
+ export interface FailoverEvents {
17
+ /** This machine became the origin. */
18
+ origin: [];
19
+ /** This machine became a replica. */
20
+ replica: [];
21
+ /** This machine lost the origin role while it had writes the new origin never saw; they were moved to this file. */
22
+ writesSetAside: [path: string];
23
+ /** Reading the daemon's events failed; watching retries. Only reported when a listener is registered. */
24
+ error: [error: Error];
25
+ }
26
+ /**
27
+ * A database run on several identical machines. Each replica asks for the
28
+ * write lock about once a second, so one takes over once the origin's lease
29
+ * runs out. `role` follows the daemon's role_changed events, and listeners
30
+ * hear about every change. While a Failover runs, its long-poll keeps the
31
+ * Node process alive; stop() or the client's close() ends it.
32
+ */
33
+ export declare class Failover {
34
+ readonly name: string;
35
+ /** The database file on this machine. */
36
+ readonly path: string;
37
+ /** This machine's role now. */
38
+ role: Role;
39
+ /** What the daemon answered when the failover started. */
40
+ readonly info: FailoverInfo;
41
+ private readonly client;
42
+ private readonly listeners;
43
+ private readonly controller;
44
+ private stopped;
45
+ /** Use failover(); it starts the failover. */
46
+ private constructor();
47
+ /** @internal */
48
+ static start(client: Litebackup, path: string, options: FailoverOptions): Promise<Failover>;
49
+ /** Whether this machine writes the database now. */
50
+ get isOrigin(): boolean;
51
+ /** Listens for role changes, writes set aside, and watch errors. */
52
+ on<Name extends keyof FailoverEvents>(event: Name, listener: (...args: FailoverEvents[Name]) => void): this;
53
+ /** Removes a listener. */
54
+ off<Name extends keyof FailoverEvents>(event: Name, listener: (...args: FailoverEvents[Name]) => void): this;
55
+ /** Which machine writes the database, when its lease runs out, and whether it ran out. */
56
+ writer(): Promise<Writer>;
57
+ /** Stops the failover and releases its write lock. The file stays. */
58
+ stop(): Promise<void>;
59
+ /** Stops following events; listeners hear nothing more. @internal */
60
+ end(): void;
61
+ /** @internal */
62
+ changeRole(role: Role | undefined): void;
63
+ /** @internal */
64
+ handle(event: LitebackupEvent): void;
65
+ /** Long-polls the daemon's events after cursor until stopped, handing this failover's events to it. */
66
+ private follow;
67
+ /** Calls every listener of an event, in the order they were added. */
68
+ private notify;
69
+ }
@@ -0,0 +1,161 @@
1
+ import { setTimeout as delay } from "node:timers/promises";
2
+ import { absolutePath } from "./client.js";
3
+ import { milliseconds } from "./duration.js";
4
+ import { LitebackupError } from "./types.js";
5
+ /** How long one events long-poll waits. */
6
+ const eventWaitMillis = 30_000;
7
+ /** How many events one page reads. */
8
+ const eventPage = 1000;
9
+ /**
10
+ * A database run on several identical machines. Each replica asks for the
11
+ * write lock about once a second, so one takes over once the origin's lease
12
+ * runs out. `role` follows the daemon's role_changed events, and listeners
13
+ * hear about every change. While a Failover runs, its long-poll keeps the
14
+ * Node process alive; stop() or the client's close() ends it.
15
+ */
16
+ export class Failover {
17
+ name;
18
+ /** The database file on this machine. */
19
+ path;
20
+ /** This machine's role now. */
21
+ role;
22
+ /** What the daemon answered when the failover started. */
23
+ info;
24
+ client;
25
+ listeners = new Map();
26
+ controller = new AbortController();
27
+ stopped = false;
28
+ /** Use failover(); it starts the failover. */
29
+ constructor(client, info) {
30
+ this.client = client;
31
+ this.info = info;
32
+ this.name = info.name;
33
+ this.path = info.path;
34
+ this.role = info.role;
35
+ }
36
+ /** @internal */
37
+ static async start(client, path, options) {
38
+ if (!path) {
39
+ throw new LitebackupError("invalid_argument", "failover needs a path", 0);
40
+ }
41
+ const body = { path: absolutePath(path) };
42
+ if (options.name) {
43
+ body.name = options.name;
44
+ }
45
+ if (options.timeout !== undefined) {
46
+ body.timeout_millis = milliseconds(options.timeout);
47
+ }
48
+ if (client.closed) {
49
+ throw new LitebackupError("closed", "the client is closed", 0);
50
+ }
51
+ // Events after the log's end as of now are this failover's, including
52
+ // those the start request itself records.
53
+ const end = await client.eventPage({ after: -1 });
54
+ const info = (await client.call("POST", "/v1/failovers/start", body));
55
+ const failover = new Failover(client, info);
56
+ if (client.closed) {
57
+ failover.end();
58
+ throw new LitebackupError("closed", "the client is closed", 0);
59
+ }
60
+ client.failovers.add(failover);
61
+ void failover.follow(end.next);
62
+ return failover;
63
+ }
64
+ /** Whether this machine writes the database now. */
65
+ get isOrigin() {
66
+ return this.role === "origin";
67
+ }
68
+ /** Listens for role changes, writes set aside, and watch errors. */
69
+ on(event, listener) {
70
+ let registered = this.listeners.get(event);
71
+ if (!registered) {
72
+ registered = new Set();
73
+ this.listeners.set(event, registered);
74
+ }
75
+ registered.add(listener);
76
+ return this;
77
+ }
78
+ /** Removes a listener. */
79
+ off(event, listener) {
80
+ this.listeners.get(event)?.delete(listener);
81
+ return this;
82
+ }
83
+ /** Which machine writes the database, when its lease runs out, and whether it ran out. */
84
+ writer() {
85
+ return this.client.writer(this.name);
86
+ }
87
+ /** Stops the failover and releases its write lock. The file stays. */
88
+ async stop() {
89
+ try {
90
+ await this.client.backups.stop({ name: this.name });
91
+ }
92
+ finally {
93
+ this.end();
94
+ this.client.failovers.delete(this);
95
+ }
96
+ }
97
+ /** Stops following events; listeners hear nothing more. @internal */
98
+ end() {
99
+ this.stopped = true;
100
+ this.controller.abort();
101
+ }
102
+ /** @internal */
103
+ changeRole(role) {
104
+ if (!role || role === this.role || this.stopped) {
105
+ return;
106
+ }
107
+ this.role = role;
108
+ this.notify(role);
109
+ }
110
+ /** @internal */
111
+ handle(event) {
112
+ if (event.type === "role_changed") {
113
+ this.changeRole((event.role ?? event.message));
114
+ }
115
+ else if (event.type === "writes_set_aside" && !this.stopped) {
116
+ this.notify("writesSetAside", event.path || event.message);
117
+ }
118
+ }
119
+ /** Long-polls the daemon's events after cursor until stopped, handing this failover's events to it. */
120
+ async follow(cursor) {
121
+ const signal = this.controller.signal;
122
+ let retry = 250;
123
+ while (!signal.aborted) {
124
+ try {
125
+ const page = await this.client.eventPage({ after: cursor, waitMillis: eventWaitMillis, limit: eventPage, signal });
126
+ retry = 250;
127
+ for (const event of page.events) {
128
+ cursor = Math.max(cursor, event.id);
129
+ if (event.name === this.name && !signal.aborted) {
130
+ this.handle(event);
131
+ }
132
+ }
133
+ cursor = Math.max(cursor, page.next);
134
+ }
135
+ catch (error) {
136
+ if (signal.aborted) {
137
+ return;
138
+ }
139
+ if ((this.listeners.get("error")?.size ?? 0) > 0) {
140
+ this.notify("error", error instanceof Error ? error : new Error(String(error)));
141
+ }
142
+ if (error instanceof LitebackupError && error.code === "sdk_unsupported") {
143
+ return;
144
+ }
145
+ try {
146
+ await delay(retry, undefined, { signal });
147
+ }
148
+ catch {
149
+ return;
150
+ }
151
+ retry = Math.min(retry * 2, 10_000);
152
+ }
153
+ }
154
+ }
155
+ /** Calls every listener of an event, in the order they were added. */
156
+ notify(event, ...args) {
157
+ for (const listener of [...(this.listeners.get(event) ?? [])]) {
158
+ listener(...args);
159
+ }
160
+ }
161
+ }