Repository navigation
Expand file tree
/
Copy pathindex.ts
More file actions
168 lines (155 loc) · 6.54 KB
/
Copy pathindex.ts
File metadata and controls
168 lines (155 loc) · 6.54 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
/**
* SQLite storage backend for the storage hub: one database file hosts every
* routed unit, document-per-row (`key TEXT` / `value TEXT` JSON). Registers
* as backend `sqlite`; the disposer unregisters first, then closes the medium.
* @module @deepseek-ai/dsh-storage-sqlite
*/
import type { Context } from '@deepseek-ai/cordis'
import z from '@deepseek-ai/schemastery'
import type { DatabaseSync } from 'node:sqlite'
import { StorageError, UNIT_NAME_RE, storageBackendServiceKey } from '@deepseek-ai/dsh-storage'
import type { KvFacet, KvUnit, KvUnitDescriptor, StorageBackend } from '@deepseek-ai/dsh-storage'
import { openDatabase, recordTableName, type JournalMode } from './schema.ts'
import { SqliteKvUnit } from './unit.ts'
export { STORAGE_SQLITE_SCHEMA_VERSION, type JournalMode } from './schema.ts'
/** Cordis plugin name. */
export const name = 'storage-sqlite'
/** The backend registers on the storage hub. */
export const inject = ['storage']
/** Plugin configuration. */
export interface Config {
/**
* Filesystem path to the SQLite database file. The special value `:memory:`
* opens an in-process database (tests). On filesystems with POSIX modes,
* missing directories and databases are created owner-only; existing path
* modes are preserved. Filesystem setup errors other than an existing
* database fail the open. The backend does not protect confidentiality or
* integrity when another principal can replace the database entry in its
* parent directory.
*/
path: string
/**
* SQLite `journal_mode` pragma. `wal` (the default) suits local disks; pick
* a rollback-journal mode (`delete`/`truncate`/`persist`) on filesystems
* where WAL's shared-memory files do not work (network mounts). See
* {@link JournalMode}.
*/
journalMode?: JournalMode
}
/** Schemastery validator for {@link Config}. */
export const Config: z<Config> = z.object({
path: z.string().required(),
journalMode: z.union(['wal', 'delete', 'truncate', 'persist'] as const).default('wal'),
})
/**
* The SQLite {@link StorageBackend}. Owns one `DatabaseSync` connection and
* the open-unit table; `kv.open` validates names, enforces the per-unit
* version stamp in `units`, and ensures the unit's record tables.
*/
export class SqliteStorageBackend implements StorageBackend {
/** The key-value facet; the only shape this backend serves. */
readonly kv: KvFacet = { open: descriptor => this.openUnit(descriptor) }
private readonly ready: Promise<DatabaseSync>
/** Open (or still-opening) units by name; presence is the double-open guard. */
private readonly units = new Map<string, Promise<SqliteKvUnit>>()
private closing: Promise<void> | undefined
/**
* @param config - Validated plugin configuration.
*/
constructor(config: Config) {
this.ready = openDatabase(config.path, (config as Required<Config>).journalMode)
// Mark the rejection handled: every primitive re-awaits `ready`, so an
// open failure still surfaces to each caller; this guard only prevents an
// unhandled-rejection crash when the failure precedes the first use.
this.ready.catch(() => {})
}
private openUnit(descriptor: KvUnitDescriptor): Promise<KvUnit> {
if (this.closing !== undefined) {
return Promise.reject(new StorageError('closed', 'sqlite storage backend is closed'))
}
if (!UNIT_NAME_RE.test(descriptor.name)) {
return Promise.reject(new Error(`kv unit name '${descriptor.name}' violates ${UNIT_NAME_RE}`))
}
for (const table of descriptor.tables) {
if (!UNIT_NAME_RE.test(table)) {
return Promise.reject(new Error(`kv table name '${table}' in unit '${descriptor.name}' violates ${UNIT_NAME_RE}`))
}
}
if (this.units.has(descriptor.name)) {
return Promise.reject(new Error(`kv unit '${descriptor.name}' is already open (double-open is a caller bug)`))
}
// Reserve the name synchronously so a concurrent second open of the same
// name rejects instead of racing past the guard during the awaits below.
const pending = this.materializeUnit(descriptor)
this.units.set(descriptor.name, pending)
pending.catch(() => this.units.delete(descriptor.name))
return pending
}
private async materializeUnit(descriptor: KvUnitDescriptor): Promise<SqliteKvUnit> {
const db = await this.ready
const row = db.prepare('SELECT version FROM units WHERE name = ?').get(descriptor.name) as
| { version: number }
| undefined
if (row === undefined) {
db.prepare('INSERT INTO units (name, version) VALUES (?, ?)').run(descriptor.name, descriptor.version)
} else if (row.version !== descriptor.version) {
throw new StorageError(
'version-mismatch',
`kv unit '${descriptor.name}' is stamped version ${row.version} on the medium, incompatible with descriptor version ${descriptor.version}`,
)
}
for (const table of descriptor.tables) {
// Both segments passed UNIT_NAME_RE, so the identifier is safe in DDL.
db.exec(`
CREATE TABLE IF NOT EXISTS "${recordTableName(descriptor.name, table)}" (
key TEXT PRIMARY KEY,
value TEXT NOT NULL
) STRICT
`)
}
return new SqliteKvUnit(db, descriptor, () => {
this.units.delete(descriptor.name)
})
}
/**
* Close every open unit and release the database. Idempotent; concurrent
* and repeated calls resolve once teardown finishes.
* @returns resolution after the medium is released.
*/
close(): Promise<void> {
this.closing ??= this.doClose()
return this.closing
}
private async doClose(): Promise<void> {
let db: DatabaseSync
try {
db = await this.ready
} catch {
// The medium never opened; that failure already rejected the opener and
// every unit call, so there is nothing left to release here.
return
}
for (const pending of [...this.units.values()]) {
const unit = await pending.catch(() => undefined)
await unit?.close()
}
db.close()
}
}
/**
* Register the SQLite backend as `sqlite` on the storage hub. The disposer
* unregisters the name first, then closes the backend.
* @param ctx - Plugin context (must inject `storage`).
* @param config - Validated plugin configuration.
*/
export function apply(ctx: Context, config: Config) {
const backend = new SqliteStorageBackend(config)
ctx.effect(() => {
const dispose = ctx.storage.backend.register('sqlite', backend)
return async () => {
dispose()
await backend.close()
}
}, 'storage-sqlite.registerBackend')
ctx.provide(storageBackendServiceKey('sqlite'), backend)
}