@starci/seed 0.0.0-stage → 0.2.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/CHANGELOG.md +16 -0
- package/LICENSE +21 -0
- package/README.md +55 -2
- package/dist/copies.d.ts +83 -0
- package/dist/copies.js +146 -0
- package/dist/driver.d.ts +145 -0
- package/dist/driver.js +21 -0
- package/dist/git/driver.d.ts +53 -0
- package/dist/git/driver.js +309 -0
- package/dist/git/files.d.ts +48 -0
- package/dist/git/files.js +78 -0
- package/dist/git/index.d.ts +6 -0
- package/dist/git/index.js +3 -0
- package/dist/git/standard.d.ts +60 -0
- package/dist/git/standard.js +105 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +6 -0
- package/dist/manifest.d.ts +108 -0
- package/dist/manifest.js +131 -0
- package/dist/postgres/index.d.ts +2 -0
- package/dist/postgres/index.js +1 -0
- package/dist/postgres/pipe.d.ts +11 -0
- package/dist/postgres/pipe.js +60 -0
- package/dist/postgres/sql.d.ts +42 -0
- package/dist/postgres/sql.js +54 -0
- package/dist/postgres/store.d.ts +33 -0
- package/dist/postgres/store.js +231 -0
- package/dist/protocol.d.ts +52 -0
- package/dist/protocol.js +101 -0
- package/dist/store.d.ts +97 -0
- package/dist/store.js +6 -0
- package/dist/testing/contract.d.ts +26 -0
- package/dist/testing/contract.js +219 -0
- package/dist/testing/index.d.ts +5 -0
- package/dist/testing/index.js +3 -0
- package/dist/testing/memory.d.ts +53 -0
- package/dist/testing/memory.js +0 -0
- package/dist/words.d.ts +33 -0
- package/dist/words.js +16 -0
- package/package.json +85 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.2.0 - 2026-11-17
|
|
4
|
+
|
|
5
|
+
- Added (`@starci/seed/git`): the adapter of a seed-standard that keeps its authored material in `raw/` (PROJECT-STACKS-13, R434). `renderStandard(content, outDir)` writes `{format, project, entries}` through `createGitDriver` into a scratch working copy (plaintext, purpose seed-standard) and replaces `manifest.json`, `data/`, `blobs/` and `index/` of `outDir`, leaving every other file; `takenAt` is `STANDARD_TAKEN_AT` (1970-01-01T00:00:00.000Z) and `source.environment` is `STANDARD_ENVIRONMENT` (standard), so the same content renders the same bytes in any entry order; a format that is no `<name>-seed-standard@<major>` is refused `DATA_FORM_REFUSED`. `runStandardAdapter(convert, argv)` is the body of an adapter's `main.ts`: `--raw` (default raw) and `--out` (default the repository root), exit 0, usage 2, a failed convert or render 1 with its code or error on one line. Types `StandardContent`, `StandardConvert`, `RenderOptions`, `AdapterIo`; constants `STANDARD_OUTPUTS`, `STANDARD_RAW`.
|
|
6
|
+
|
|
7
|
+
## 0.1.0 - 2026-11-14
|
|
8
|
+
|
|
9
|
+
The ports of the data standard (PROJECT-STACKS-13, PROJECT-STACKS-14) in one package: what must be kept, where a copy is kept, and one export written to several copies. It was first written under `@starci/common/data` and moves here before any release, so `@starci/common` stays at 1.0.1.
|
|
10
|
+
|
|
11
|
+
- `exportOnce` names a failing store and its cause in the refusal: `DATA_STORE_FAILED` params `{store, cause}`, the cause read by shape (a coded error of any `@starci/common` copy by its code, a driver error by its class, SQLSTATE and table), never by message; `causeLabel` is exported; an empty store is a valid export.
|
|
12
|
+
- Added: `@starci/seed`: the closed vocabulary (`StoreKind` database | storage, `DriverKind` git | s3, `DataPurpose` seed-standard | seed-backup, `StoreLevel`, `EntryForm`, the git copy cap `GIT_CAP_BYTES` 500 MiB (the whole snapshot, history not counted) with `GIT_WARN_BYTES` 400 MiB and `GIT_SHARD_BYTES` 4 MiB); `DataEntry`, `DataManifest` (`starci/data-manifest@1`), `ManifestBuilder`, `canonicalJson`, `recordEntry`, `blobEntry`, `setDigest`, `exportDigestOf`, `manifestProblems`; the `StoreAdapter` and `DriverAdapter` ports with `ImportReport`, `Holding`, `CopyRef`, `CopyReceipt`, `CopyVerdict` and the coded `DataRefusal` (retry class configuration | transient), a `DomainError` of `@starci/common`; `StoreAdapter.import` is an upsert by natural key that keeps each row's identity (`identityOf`; never delete-and-recreate; a key not named is left alone); the copy contract `exportOnce`, `unchangedSince`, `writeEverywhere` (each driver an isolated leg, outcome complete | partial | failed), `compareCopies`, `chooseCopy`, `restoreFrom`; the line protocol `starci/data-entries@1` (`serveStore` for an app's store command, `commandStore` for the harness side).
|
|
13
|
+
- Added: `@starci/seed/git`: `createGitDriver`, the `git` driver over a local working copy (cloned, pulled and pushed when a remote is given): `manifest.json` + record shards `data/<store>/<set>/<shard>.json` (hash-prefix shards, the width only grows) + blob chunks `blobs/<store>/<set>/<aa>/<id>[.<n>].bin` + `index/`; files at most 4 MiB; sealing follows the purpose (a `seed-standard` is plaintext, a `seed-backup` is sealed with sops in binary mode to its environment's age recipients, `*.sops.json`); a file whose plaintext did not change is never rewritten and an unchanged export commits nothing; a snapshot past the cap is refused `DATA_GIT_CAP_EXCEEDED` (configuration: needs s3), past 400 MiB warned `DATA_GIT_CAP_NEAR`; `verify` checks manifest, sealing policy, stray, missing and unsealed files, envelopes, the cap and, with an identity (or for a plaintext copy), every digest; `.gitattributes` `* -text` keeps line endings from touching a file.
|
|
14
|
+
- Added: `pinRepository` (a copy repository at one pinned commit: bare mirror in a cache, `readText`, `openSealed` in memory with an identity) and `openReviewTree` (writes and sops sealing into a working tree a person reviews), for a kind a project defines on top of the standard.
|
|
15
|
+
- Added: `@starci/seed/postgres`: `postgresStore({id, run, schemas?, exclude?, pageRows?})`, the `database` store (level `physical`, purpose `seed-backup`) that copies the whole relational database behind `StoreAdapter` as a per-table row export through SQL this package owns (not a pg_dump archive: its bytes change on every run and it is one blob; not the app's entity layer: it covers only modelled entities under the app role). One set per ordinary or partitioned-parent table `<schema>.<table>`, rows keyed by primary key, every column read as text in a REPEATABLE READ snapshot under fixed session settings so an unchanged database exports the same bytes (the git driver commits nothing); entries come in byte order from SQL (`ORDER BY convert_to(key, 'UTF8')`, keyset pages). Import is one READ COMMITTED transaction with `session_replication_role = replica` (owner role), an upsert by primary key with exact created/updated/unchanged counts, `mirror` deletes, sequences set to the column maximum, a dry run that rolls back. Excluded and keyless tables are listed in `describe().cannot` with reasons; a SQL failure is `DATA_STORE_FAILED` with the SQLSTATE only. The app hands a `PostgresRunner` (`query`, `transaction`) and no SQL. `storeContract` takes an optional `{change}` for a store whose rows are typed.
|
|
16
|
+
- Added: `@starci/seed/testing`: `memoryStore`, `memoryDriver` (with failure and corruption switches), `memorySpool`, and the contract suites `storeContract` and `driverContract` every real adapter runs against its fakes.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 starci183
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,56 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @starci/seed
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The data standard of a StarCi project: what an app or a harness job needs to keep a project's data in more than one place, with no knowledge of any database or S3 client. ESM only; its one dependency is `@starci/common` (`DomainError`, pinned exactly).
|
|
4
|
+
|
|
5
|
+
## Why the name
|
|
6
|
+
|
|
7
|
+
In the owner's standard everything this package does is one of the two kinds of seed: `seed-standard` (loaded once by the bring-up) and `seed-backup` (written by the scheduled job, brought back by a sync); sync is only one verb of the backup kind.
|
|
8
|
+
|
|
9
|
+
The law is [contexts/project/stacks.md](../../contexts/project/stacks.md), PROJECT-STACKS-13 (what a copy holds, the two purposes, sealing, the size limits) and PROJECT-STACKS-14 (every store has an adapter, every copy goes through a driver).
|
|
10
|
+
|
|
11
|
+
## Entries
|
|
12
|
+
|
|
13
|
+
| entry | holds |
|
|
14
|
+
|---|---|
|
|
15
|
+
| `@starci/seed` | the ports and the copy contract: `StoreAdapter` (a thing that must be kept: a database or a storage bucket; describes its sets, exports entries in (set, key) byte order, imports them by natural key keeping each row's identity, `merge` or `mirror`, dry run, `identityOf`), `DriverAdapter` (where a copy is kept: git now, s3 later; plans, writes, lists, reads, verifies, refuses with the coded `DataRefusal`), `DataManifest` with `ManifestBuilder`, `exportOnce`, `writeEverywhere` (each driver an isolated leg), `compareCopies`, `chooseCopy`, `restoreFrom`, and the line protocol `starci/data-entries@1` (`serveStore`, `commandStore`) that carries a store through an app's own command |
|
|
16
|
+
| `@starci/seed/testing` | `memoryStore`, `memoryDriver` (with failure and corruption switches), `memorySpool`, and the contract suites `storeContract` and `driverContract`: a real adapter runs them against its fakes (each case throws when a promise is broken, in any test runner) |
|
|
17
|
+
| `@starci/seed/postgres` | `postgresStore` (the whole relational database as deterministic per-table rows behind `StoreAdapter`; the app hands a `PostgresRunner` and no SQL), see below |
|
|
18
|
+
| `@starci/seed/git` | `createGitDriver` (the `git` driver over a local working copy), `pinRepository` (a copy repository at one pinned commit, read in place) and `openReviewTree` (writes and seals into a tree a person reviews), for a kind a project defines on top of the standard; `renderStandard` and `runStandardAdapter`, the adapter of a standard that keeps its authored material in `raw/` (below) |
|
|
19
|
+
|
|
20
|
+
## The git driver's layout
|
|
21
|
+
|
|
22
|
+
`manifest.json` (schema `starci/data-manifest@1`: the sets with counts and digests, the file index, the shard widths, the sealing and its public recipients; no value), record shards `data/<store>/<set>/<shard>.json` (hash-prefix shards, the width only grows), object chunks `blobs/<store>/<set>/<aa>/<id>[.<n>].bin` and `index/<store>/<set>.json`. `.gitattributes` holds `* -text` so line endings never touch a file. A file whose plaintext did not change is never rewritten, and an unchanged export commits nothing.
|
|
23
|
+
|
|
24
|
+
## The adapter of a standard
|
|
25
|
+
|
|
26
|
+
A standard whose content is awkward as JSON records keeps what people author in `raw/` and an `adapter/` (PROJECT-STACKS-13, R434). `adapter/convert.ts` exports `convert(rawDir)`, answering `{format, project, entries}` (each entry `{store, entry}` from `recordEntry` or `blobEntry`); `adapter/main.ts` is `process.exitCode = await runStandardAdapter(convert, process.argv.slice(2))`. `renderStandard` writes the entries through `createGitDriver` into a scratch working copy and replaces `manifest.json`, `data/`, `blobs/` and `index/` of the output folder, nothing else. Its output is deterministic: sets and keys sorted, canonical JSON, `takenAt` fixed at `STANDARD_TAKEN_AT` and `source.environment` at `STANDARD_ENVIRONMENT`; the adapter brings no clock or random id. The copy repository's hook and CI re-run it and refuse a committed output that differs (`HFS_DATA_ADAPTER_DRIFT`); `starci data standard init --adapter` scaffolds it.
|
|
27
|
+
|
|
28
|
+
## Sealing by purpose
|
|
29
|
+
|
|
30
|
+
The purpose decides: a `seed-standard` is plaintext (readable for review), a `seed-backup` is sealed with sops in binary mode to the age recipients of its environment, every file as `*.sops.json`. `verify` checks the manifest, the sealing policy, stray, missing and unsealed files, envelopes, the cap and, with an identity (or for a plaintext copy), every digest.
|
|
31
|
+
|
|
32
|
+
## Size limits
|
|
33
|
+
|
|
34
|
+
No file exceeds 4 MiB (`GIT_SHARD_BYTES`). The whole snapshot (the data files of the working tree, history not counted) is at most 500 MiB (`GIT_CAP_BYTES`) and warned past 400 MiB (`GIT_WARN_BYTES`): past the cap the driver refuses `DATA_GIT_CAP_EXCEEDED`, a configuration refusal that means the set needs the `s3` driver.
|
|
35
|
+
|
|
36
|
+
## The postgres store
|
|
37
|
+
|
|
38
|
+
`postgresStore({ id, run, schemas?, exclude?, pageRows? })` (`@starci/seed/postgres`, kind `database`, level `physical`, purpose `seed-backup` only) copies the whole relational database behind the same `StoreAdapter` port. The app hands one thing, a `PostgresRunner` (`query` with positional parameters, `transaction` with an isolation level); it writes no SQL. The schema comes from the app's migrations: the copy holds DATA only.
|
|
39
|
+
|
|
40
|
+
**The decision, and why.** A per-table row export through SQL owned by THIS package, not an opaque `pg_dump` archive (a dump file changes bytes on every run and is one blob, so an unchanged database would still be a changed copy and nothing could be skipped, sharded or compared per table), and not the app's entity layer (it covers only the entities the app models and runs under the app role, which row level security and grants restrict, so it would silently miss data). The SQL is built from the catalog with quoted identifiers only; a value never enters a statement's text.
|
|
41
|
+
|
|
42
|
+
- **Sets.** One per ordinary or partitioned-parent table (`relkind r|p`, never a partition), named `<schema>.<table>`, schema id `postgres/<schema>.<table>@1`, form record. A row is the JSON object of its non-generated columns, every value as text or null, the entry key the primary key (one column: its text; several: a JSON array text).
|
|
43
|
+
- **Deterministic.** The export is one REPEATABLE READ transaction (one snapshot of every table) under fixed session settings (UTC, ISO dates and intervals, hex bytea, shortest floats), keyset-paged. Order is the UTF-8 byte order of the key **in SQL** (`ORDER BY convert_to(<key>, 'UTF8')`), not the database collation, so memory stays flat (one page plus one prefetched); a page is re-sorted in the store too. The price: a page cannot use the primary key index, so the cost is rows x pages, fine at the size a git copy may hold. An unchanged database yields the same entries, the same digests, and so the git driver commits nothing.
|
|
44
|
+
- **Values.** Every column is cast to text on the way out and back to its own type (`format_type`) on the way in, so a number never passes through a JS number and a timestamp never depends on a session zone. Proven against PostgreSQL 17 in the real spec: numeric(40,10), bigint extremes, double precision (NaN, 1e300), date and timestamptz (also infinity), interval, bytea, json (its spacing kept), jsonb (exact text), arrays with quotes and NULL, enums, text with quotes, backslashes and newlines, composite primary keys, partitioned tables, identity and serial columns, generated columns (not held, recomputed). Not proven: `money` (its text follows `lc_monetary`, set to C for the transaction), user-defined base types, `char(n)` (its trailing blanks are not kept by the text cast, equal under comparison).
|
|
45
|
+
- **Import.** One READ COMMITTED transaction for the whole import with `SET LOCAL session_replication_role = replica` (foreign keys and triggers stay quiet so the copy is consistent as a whole, which **needs the owner role**: a role without it fails `DATA_STORE_FAILED` with SQLSTATE 42501 and nothing is written). Each entry is an upsert by primary key (`INSERT ... SELECT ... FROM json_to_record(...) ON CONFLICT (pk) DO UPDATE`); the stored row is compared first, so `unchanged` writes nothing and an update keeps the row. `mirror` deletes the keys of the sets the entries name that the entries lack (a table with no entry at all is not touched: restore into a freshly migrated database). Sequences owned by a column of an imported table are set to the column maximum (left alone for an empty table). A dry run does every write, counts it, and rolls back (so it moves no sequence: `setval` is not transactional and is skipped). A row whose columns are not exactly the table's non-generated columns (a migration since the copy) is a refused key `DATA_ROW_INVALID`; a set of an excluded or unknown table is `DATA_TABLE_NOT_HELD`; neither throws. `identityOf(set, key)` is the key itself when the row exists (the primary key is the identity).
|
|
46
|
+
- **Cannot.** `describe().cannot` lists every excluded table with its reason and every table without a primary key (it cannot keep identity, so it is neither exported nor imported), and a table whose primary key holds a generated column or whose name a set name cannot carry. A GENERATED ALWAYS identity column that is not the primary key cannot be updated in place: PostgreSQL refuses and the refusal surfaces as `DATA_STORE_FAILED`.
|
|
47
|
+
- **Exclusions are the app's declaration.** Queues, caches, vectors, finished checkpoints and raw data past retention are rebuildable: the app lists each in `exclude: [{ table: "<schema>.<table>", reason }]` with its reason, which `describe().cannot` shows.
|
|
48
|
+
- **Failures.** Every SQL failure is `DataRefusal("DATA_STORE_FAILED", "configuration", { store, table, cause })`, the cause the SQLSTATE or the error class, never the message (it may quote a value).
|
|
49
|
+
|
|
50
|
+
## Tools
|
|
51
|
+
|
|
52
|
+
The postgres store needs no tool; its real spec needs a PostgreSQL (`STARCI_SEED_PG_URL` of a throwaway server, else Docker with the harness-pinned `postgres` image, else it skips with the reason) and the dev-only `pg` client. The git driver runs `git`, `sops` and `age` (`age-keygen` in the specs); all three must be on `PATH`, for the driver and for the package's real-tool specs, which generate a throwaway age key inside the test and never read a real secret.
|
|
53
|
+
|
|
54
|
+
## Tests
|
|
55
|
+
|
|
56
|
+
`npm test` typechecks, lints and runs `src/**/*.spec.ts` with Node's runner, and fails under 100% line, branch and function coverage.
|
package/dist/copies.d.ts
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { CopyReceipt, CopyRef, CopyVerdict, DriverAdapter, ExportSource, WriteContext } from "./driver.js";
|
|
2
|
+
import type { DataEntry, DataManifest, ManifestHeader, Selection } from "./manifest.js";
|
|
3
|
+
import type { ImportOptions, ImportReport, StoreAdapter } from "./store.js";
|
|
4
|
+
/** An entry with the store it was read from. */
|
|
5
|
+
export interface StoredEntry {
|
|
6
|
+
/** The store id. */
|
|
7
|
+
readonly store: string;
|
|
8
|
+
/** The entry. */
|
|
9
|
+
readonly entry: DataEntry;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Where one export is held so every driver writes the same bytes: plaintext, outside every repository, removed after
|
|
13
|
+
* the run. The harness spools to a private scratch directory; tests spool in memory.
|
|
14
|
+
*/
|
|
15
|
+
export interface Spool {
|
|
16
|
+
/** Keeps one entry. */
|
|
17
|
+
append(item: StoredEntry): Promise<void>;
|
|
18
|
+
/** Every kept entry, in the order appended. */
|
|
19
|
+
replay(): AsyncIterable<StoredEntry>;
|
|
20
|
+
/** Removes everything kept. */
|
|
21
|
+
dispose(): Promise<void>;
|
|
22
|
+
}
|
|
23
|
+
/** One destination's part of a run. */
|
|
24
|
+
export interface CopyLeg {
|
|
25
|
+
/** The driver id. */
|
|
26
|
+
readonly driver: string;
|
|
27
|
+
/** `written`, `unchanged` (it already held the export) or `failed`. */
|
|
28
|
+
readonly outcome: "written" | "unchanged" | "failed";
|
|
29
|
+
/** The driver's receipt, when it wrote or already held the export. */
|
|
30
|
+
readonly receipt: CopyReceipt | null;
|
|
31
|
+
/** The failure, by code and retry class; never a value. */
|
|
32
|
+
readonly failure: {
|
|
33
|
+
readonly code: string;
|
|
34
|
+
readonly retry: "configuration" | "transient";
|
|
35
|
+
} | null;
|
|
36
|
+
}
|
|
37
|
+
/** One run: one manifest, one leg per destination. `partial` is one item for a person (the dead-letter frame of the jobs). */
|
|
38
|
+
export interface CopyRun {
|
|
39
|
+
/** The export every leg wrote. */
|
|
40
|
+
readonly manifest: DataManifest;
|
|
41
|
+
/** One per driver, in the declared order. */
|
|
42
|
+
readonly legs: readonly CopyLeg[];
|
|
43
|
+
/** `complete` when every leg holds the export, `partial` when some do, `failed` when none. */
|
|
44
|
+
readonly outcome: "complete" | "partial" | "failed";
|
|
45
|
+
}
|
|
46
|
+
/** An export source over a spool and its manifest. */
|
|
47
|
+
export declare function spooledSource(manifest: DataManifest, spool: Spool): ExportSource;
|
|
48
|
+
/**
|
|
49
|
+
* Reads every store once, in the order given, into the spool and computes the manifest. A store must yield its entries
|
|
50
|
+
* in (set, key) byte order; an entry out of order, a repeated key or a hash that does not match its body is refused.
|
|
51
|
+
*/
|
|
52
|
+
export declare function exportOnce(stores: readonly StoreAdapter[], selection: Selection, spool: Spool, header: ManifestHeader): Promise<ExportSource>;
|
|
53
|
+
/**
|
|
54
|
+
* What a store's failure was, safe to log: the coded error's code (a DomainError of any copy of @starci/common, so read by shape,
|
|
55
|
+
* never by `instanceof`), a driver's `code` (a PostgreSQL SQLSTATE, a Node errno) with the error's class, or the class alone. Never the
|
|
56
|
+
* message, which may quote a value.
|
|
57
|
+
*/
|
|
58
|
+
export declare function causeLabel(cause: unknown): string;
|
|
59
|
+
/** True when the export equals the one the last receipt recorded: a scheduled backup then writes nothing. */
|
|
60
|
+
export declare function unchangedSince(manifest: DataManifest, lastExportDigest: string | null): boolean;
|
|
61
|
+
/** Writes the one export to every driver; each leg is isolated, so a failing driver never stops another. */
|
|
62
|
+
export declare function writeEverywhere(source: ExportSource, drivers: readonly DriverAdapter[], context: WriteContext): Promise<CopyRun>;
|
|
63
|
+
/** One set whose copies differ, with each copy's digest by driver. */
|
|
64
|
+
export interface CopyDifference {
|
|
65
|
+
/** `<store>/<set>`. */
|
|
66
|
+
readonly set: string;
|
|
67
|
+
/** Digest per driver; a copy that does not hold the set is absent. */
|
|
68
|
+
readonly digests: Readonly<Record<string, string>>;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Copies are equal when every set two or more copies hold has one digest. A subset copy is compared on the sets it holds;
|
|
72
|
+
* an unhealthy copy (or one without a manifest) is left out and makes the comparison unequal.
|
|
73
|
+
*/
|
|
74
|
+
export declare function compareCopies(verdicts: readonly CopyVerdict[]): {
|
|
75
|
+
readonly equal: boolean;
|
|
76
|
+
readonly differing: readonly CopyDifference[];
|
|
77
|
+
};
|
|
78
|
+
/** The newest healthy copy that holds every selected set, the drivers tried in `preference` order on a tie; null when none. */
|
|
79
|
+
export declare function chooseCopy(verdicts: readonly CopyVerdict[], selection: Selection, preference: readonly string[]): CopyRef | null;
|
|
80
|
+
/** Imports one copy into the stores it names, in the order given; a store the copy does not hold is skipped. */
|
|
81
|
+
export declare function restoreFrom(source: ExportSource, stores: readonly StoreAdapter[], options: ImportOptions, selection?: Selection): Promise<readonly ImportReport[]>;
|
|
82
|
+
/** A spool held in memory, for tests and small exports. */
|
|
83
|
+
export declare function memorySpool(): Spool;
|
package/dist/copies.js
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import { DataRefusal } from "./driver.js";
|
|
2
|
+
import { ManifestBuilder, byteOrder } from "./manifest.js";
|
|
3
|
+
function selects(selection, set) {
|
|
4
|
+
return selection?.sets === undefined || selection.sets.includes(set);
|
|
5
|
+
}
|
|
6
|
+
/** An export source over a spool and its manifest. */
|
|
7
|
+
export function spooledSource(manifest, spool) {
|
|
8
|
+
return {
|
|
9
|
+
manifest,
|
|
10
|
+
async *entries(selection) {
|
|
11
|
+
for await (const item of spool.replay())
|
|
12
|
+
if (selects(selection, item.entry.set))
|
|
13
|
+
yield item;
|
|
14
|
+
},
|
|
15
|
+
};
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Reads every store once, in the order given, into the spool and computes the manifest. A store must yield its entries
|
|
19
|
+
* in (set, key) byte order; an entry out of order, a repeated key or a hash that does not match its body is refused.
|
|
20
|
+
*/
|
|
21
|
+
export async function exportOnce(stores, selection, spool, header) {
|
|
22
|
+
const builder = new ManifestBuilder();
|
|
23
|
+
for (const store of stores) {
|
|
24
|
+
let last = null;
|
|
25
|
+
try {
|
|
26
|
+
for await (const entry of store.export(selection)) {
|
|
27
|
+
if (last !== null && (byteOrder(last.set, entry.set) || byteOrder(last.key, entry.key)) > 0)
|
|
28
|
+
throw new TypeError(`${store.id}: ${entry.set}/${entry.key} comes after ${last.set}/${last.key}`);
|
|
29
|
+
builder.add(store.id, entry);
|
|
30
|
+
await spool.append({ store: store.id, entry });
|
|
31
|
+
last = { set: entry.set, key: entry.key };
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
catch (cause) {
|
|
35
|
+
if (cause instanceof DataRefusal)
|
|
36
|
+
throw cause;
|
|
37
|
+
throw new DataRefusal("DATA_STORE_FAILED", "configuration", { store: store.id, cause: causeLabel(cause) }, cause);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
return spooledSource(builder.build(header), spool);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* What a store's failure was, safe to log: the coded error's code (a DomainError of any copy of @starci/common, so read by shape,
|
|
44
|
+
* never by `instanceof`), a driver's `code` (a PostgreSQL SQLSTATE, a Node errno) with the error's class, or the class alone. Never the
|
|
45
|
+
* message, which may quote a value.
|
|
46
|
+
*/
|
|
47
|
+
export function causeLabel(cause) {
|
|
48
|
+
if (typeof cause !== "object" || cause === null)
|
|
49
|
+
return typeof cause;
|
|
50
|
+
const shaped = cause;
|
|
51
|
+
const name = typeof shaped.name === "string" ? shaped.name : "Error";
|
|
52
|
+
const code = typeof shaped.code === "string" || typeof shaped.code === "number" ? String(shaped.code) : null;
|
|
53
|
+
const table = typeof shaped.table === "string" ? ` on ${shaped.table}` : "";
|
|
54
|
+
return code === null ? name : `${name} ${code}${table}`;
|
|
55
|
+
}
|
|
56
|
+
/** True when the export equals the one the last receipt recorded: a scheduled backup then writes nothing. */
|
|
57
|
+
export function unchangedSince(manifest, lastExportDigest) {
|
|
58
|
+
return lastExportDigest !== null && manifest.exportDigest === lastExportDigest;
|
|
59
|
+
}
|
|
60
|
+
/** Writes the one export to every driver; each leg is isolated, so a failing driver never stops another. */
|
|
61
|
+
export async function writeEverywhere(source, drivers, context) {
|
|
62
|
+
const legs = [];
|
|
63
|
+
for (const driver of drivers) {
|
|
64
|
+
try {
|
|
65
|
+
const receipt = await driver.write(source, context);
|
|
66
|
+
legs.push({ driver: driver.id, outcome: receipt.changed === 0 ? "unchanged" : "written", receipt, failure: null });
|
|
67
|
+
}
|
|
68
|
+
catch (cause) {
|
|
69
|
+
const failure = cause instanceof DataRefusal
|
|
70
|
+
? { code: cause.code, retry: cause.retry }
|
|
71
|
+
: { code: "DATA_DRIVER_UNAVAILABLE", retry: "transient" };
|
|
72
|
+
legs.push({ driver: driver.id, outcome: "failed", receipt: null, failure });
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
const held = legs.filter((leg) => leg.outcome !== "failed").length;
|
|
76
|
+
const outcome = held === legs.length ? "complete" : held === 0 ? "failed" : "partial";
|
|
77
|
+
return { manifest: source.manifest, legs, outcome };
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Copies are equal when every set two or more copies hold has one digest. A subset copy is compared on the sets it holds;
|
|
81
|
+
* an unhealthy copy (or one without a manifest) is left out and makes the comparison unequal.
|
|
82
|
+
*/
|
|
83
|
+
export function compareCopies(verdicts) {
|
|
84
|
+
const bySet = new Map();
|
|
85
|
+
for (const verdict of verdicts) {
|
|
86
|
+
if (!verdict.healthy || verdict.manifest === null)
|
|
87
|
+
continue;
|
|
88
|
+
for (const set of verdict.manifest.sets) {
|
|
89
|
+
const id = `${set.store}/${set.set}`;
|
|
90
|
+
bySet.set(id, { ...bySet.get(id), [verdict.ref.driver]: set.digest });
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
const differing = [...bySet.entries()]
|
|
94
|
+
.filter(([, digests]) => new Set(Object.values(digests)).size > 1)
|
|
95
|
+
.map(([set, digests]) => ({ set, digests }));
|
|
96
|
+
const unhealthy = verdicts.some((verdict) => !verdict.healthy || verdict.manifest === null);
|
|
97
|
+
return { equal: differing.length === 0 && !unhealthy, differing };
|
|
98
|
+
}
|
|
99
|
+
/** The newest healthy copy that holds every selected set, the drivers tried in `preference` order on a tie; null when none. */
|
|
100
|
+
export function chooseCopy(verdicts, selection, preference) {
|
|
101
|
+
const rank = (driver) => {
|
|
102
|
+
const at = preference.indexOf(driver);
|
|
103
|
+
return at < 0 ? preference.length : at;
|
|
104
|
+
};
|
|
105
|
+
const usable = verdicts.filter((verdict) => {
|
|
106
|
+
if (!verdict.healthy || verdict.manifest === null)
|
|
107
|
+
return false;
|
|
108
|
+
const held = new Set(verdict.manifest.sets.map((set) => set.set));
|
|
109
|
+
return (selection.sets ?? []).every((set) => held.has(set));
|
|
110
|
+
});
|
|
111
|
+
usable.sort((left, right) => byteOrder(right.ref.takenAt, left.ref.takenAt) || rank(left.ref.driver) - rank(right.ref.driver));
|
|
112
|
+
return usable[0]?.ref ?? null;
|
|
113
|
+
}
|
|
114
|
+
async function* entriesOf(source, store, selection) {
|
|
115
|
+
for await (const item of source.entries(selection))
|
|
116
|
+
if (item.store === store)
|
|
117
|
+
yield item.entry;
|
|
118
|
+
}
|
|
119
|
+
/** Imports one copy into the stores it names, in the order given; a store the copy does not hold is skipped. */
|
|
120
|
+
export async function restoreFrom(source, stores, options, selection) {
|
|
121
|
+
const reports = [];
|
|
122
|
+
for (const store of stores) {
|
|
123
|
+
if (!source.manifest.sets.some((set) => set.store === store.id && selects(selection, set.set)))
|
|
124
|
+
continue;
|
|
125
|
+
reports.push(await store.import(entriesOf(source, store.id, selection), options));
|
|
126
|
+
}
|
|
127
|
+
return reports;
|
|
128
|
+
}
|
|
129
|
+
/** A spool held in memory, for tests and small exports. */
|
|
130
|
+
export function memorySpool() {
|
|
131
|
+
let items = [];
|
|
132
|
+
return {
|
|
133
|
+
append: (item) => {
|
|
134
|
+
items.push(item);
|
|
135
|
+
return Promise.resolve();
|
|
136
|
+
},
|
|
137
|
+
async *replay() {
|
|
138
|
+
await Promise.resolve();
|
|
139
|
+
yield* items;
|
|
140
|
+
},
|
|
141
|
+
dispose: () => {
|
|
142
|
+
items = [];
|
|
143
|
+
return Promise.resolve();
|
|
144
|
+
},
|
|
145
|
+
};
|
|
146
|
+
}
|
package/dist/driver.d.ts
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { DomainError } from "@starci/common";
|
|
2
|
+
import type { ErrorParams } from "@starci/common";
|
|
3
|
+
import type { DataEntry, DataManifest, DataSetSummary, Selection } from "./manifest.js";
|
|
4
|
+
import type { DriverKind, EntryForm } from "./words.js";
|
|
5
|
+
/** What a driver can hold, measured on the SEALED bytes it writes. */
|
|
6
|
+
export interface DriverLimits {
|
|
7
|
+
/** The entry forms it holds. */
|
|
8
|
+
readonly forms: readonly EntryForm[];
|
|
9
|
+
/** The largest file or object it writes, or null for no limit. */
|
|
10
|
+
readonly maxFileBytes: number | null;
|
|
11
|
+
/** The largest whole copy it keeps, or null (git: 500 MiB of the snapshot, history not counted). */
|
|
12
|
+
readonly maxCopyBytes: number | null;
|
|
13
|
+
/** The size at which a write warns that the copy nears `maxCopyBytes`, or null. */
|
|
14
|
+
readonly warnCopyBytes: number | null;
|
|
15
|
+
}
|
|
16
|
+
/** A set a driver leaves out of a copy, and why. */
|
|
17
|
+
export interface OmittedSet {
|
|
18
|
+
/** The store. */
|
|
19
|
+
readonly store: string;
|
|
20
|
+
/** The set. */
|
|
21
|
+
readonly set: string;
|
|
22
|
+
/** Why it is left out. */
|
|
23
|
+
readonly reason: string;
|
|
24
|
+
}
|
|
25
|
+
/** What a driver holds of an export. A subset names every set it leaves out and why; never silent. */
|
|
26
|
+
export interface Holding {
|
|
27
|
+
/** The export it is a copy of. */
|
|
28
|
+
readonly exportDigest: string;
|
|
29
|
+
/** `all`, or `subset` when `omitted` is not empty. */
|
|
30
|
+
readonly holds: "all" | "subset";
|
|
31
|
+
/** The sets it holds. */
|
|
32
|
+
readonly sets: readonly DataSetSummary[];
|
|
33
|
+
/** The sets it leaves out. */
|
|
34
|
+
readonly omitted: readonly OmittedSet[];
|
|
35
|
+
}
|
|
36
|
+
/** Where one copy is: a commit of a git copy, an object version prefix of s3. */
|
|
37
|
+
export interface CopyRef {
|
|
38
|
+
/** The driver id the stack manifest declares. */
|
|
39
|
+
readonly driver: string;
|
|
40
|
+
/** Its kind. */
|
|
41
|
+
readonly kind: DriverKind;
|
|
42
|
+
/** The commit, or the object prefix and version. */
|
|
43
|
+
readonly locator: string;
|
|
44
|
+
/** The export it holds. */
|
|
45
|
+
readonly exportDigest: string;
|
|
46
|
+
/** When the export was taken. */
|
|
47
|
+
readonly takenAt: string;
|
|
48
|
+
}
|
|
49
|
+
/** The public age recipients a write seals to: the target environment's rule of `.sops.yaml` (PROJECT-STACKS-5). */
|
|
50
|
+
export interface WriteContext {
|
|
51
|
+
/** Public age recipients, never an identity. */
|
|
52
|
+
readonly recipients: readonly string[];
|
|
53
|
+
/** Plan and measure, write nothing. */
|
|
54
|
+
readonly dryRun: boolean;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The identity a read or a full verify opens copies with, as a handle the harness resolved through its one lookup
|
|
58
|
+
* (PROJECT-STACKS-5). The key itself never travels through a port: the driver passes the handle to the sealing tool.
|
|
59
|
+
*/
|
|
60
|
+
export interface OpenContext {
|
|
61
|
+
/** An opaque handle; a driver that opens nothing ignores it. */
|
|
62
|
+
readonly identity: {
|
|
63
|
+
readonly kind: "age-identity";
|
|
64
|
+
readonly env: Readonly<Record<string, string>>;
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
/** One export, readable more than once: what every driver writes from, and what a read gives back. */
|
|
68
|
+
export interface ExportSource {
|
|
69
|
+
/** Its manifest. */
|
|
70
|
+
readonly manifest: DataManifest;
|
|
71
|
+
/** Its entries in (store, set, key) order, narrowed by `selection`; each comes with the store it was read from. */
|
|
72
|
+
entries(selection?: Selection): AsyncIterable<{
|
|
73
|
+
readonly store: string;
|
|
74
|
+
readonly entry: DataEntry;
|
|
75
|
+
}>;
|
|
76
|
+
}
|
|
77
|
+
/** A driver's receipt of one write. */
|
|
78
|
+
export interface CopyReceipt {
|
|
79
|
+
/** The schema of this record. */
|
|
80
|
+
readonly schema: "starci/data-copy@1";
|
|
81
|
+
/** Where the copy is. */
|
|
82
|
+
readonly ref: CopyRef;
|
|
83
|
+
/** What it holds. */
|
|
84
|
+
readonly holding: Holding;
|
|
85
|
+
/** The sealed bytes of the whole copy after the write. */
|
|
86
|
+
readonly bytes: number;
|
|
87
|
+
/** Files or objects the write changed; 0 when the export was already held. */
|
|
88
|
+
readonly changed: number;
|
|
89
|
+
/** Warnings the write raised (a copy near its cap), by code. */
|
|
90
|
+
readonly warnings: readonly string[];
|
|
91
|
+
/** When it was written. */
|
|
92
|
+
readonly at: string;
|
|
93
|
+
}
|
|
94
|
+
/** One named check of a verify. */
|
|
95
|
+
export interface VerifyCheck {
|
|
96
|
+
/** e.g. `sealed`, `manifest`, `counts`, `digests`, `cap`. */
|
|
97
|
+
readonly name: string;
|
|
98
|
+
/** Whether it passed. */
|
|
99
|
+
readonly ok: boolean;
|
|
100
|
+
/** What it found; never a value. */
|
|
101
|
+
readonly detail: string;
|
|
102
|
+
}
|
|
103
|
+
/** A driver's verdict on one copy. */
|
|
104
|
+
export interface CopyVerdict {
|
|
105
|
+
/** The copy. */
|
|
106
|
+
readonly ref: CopyRef;
|
|
107
|
+
/** True when every check passed. */
|
|
108
|
+
readonly healthy: boolean;
|
|
109
|
+
/** The checks, in the order they ran. */
|
|
110
|
+
readonly checks: readonly VerifyCheck[];
|
|
111
|
+
/** The manifest the copy carries, when it could be read. */
|
|
112
|
+
readonly manifest: DataManifest | null;
|
|
113
|
+
}
|
|
114
|
+
/** The codes a data copy is refused with. */
|
|
115
|
+
export type DataRefusalCode = "DATA_GIT_CAP_EXCEEDED" | "DATA_FORM_REFUSED" | "DATA_COPY_MISSING" | "DATA_COPY_CORRUPT" | "DATA_SEAL_FAILED" | "DATA_DRIVER_UNAVAILABLE" | "DATA_STORE_FAILED";
|
|
116
|
+
/**
|
|
117
|
+
* A refusal with a retry class: `configuration` is never retried (one item for a person: e.g. a copy that outgrew git
|
|
118
|
+
* and needs s3), `transient` is retried on the job's ladder (a network or remote failure).
|
|
119
|
+
*/
|
|
120
|
+
export declare class DataRefusal extends DomainError<DataRefusalCode> {
|
|
121
|
+
/** Whether a retry can help. */
|
|
122
|
+
readonly retry: "configuration" | "transient";
|
|
123
|
+
constructor(code: DataRefusalCode, retry: "configuration" | "transient", params?: ErrorParams, cause?: unknown);
|
|
124
|
+
}
|
|
125
|
+
/** Where a copy is kept: one per declared driver of `application-stacks.yaml` `data.drivers`. */
|
|
126
|
+
export interface DriverAdapter {
|
|
127
|
+
/** The driver id the stack manifest declares. */
|
|
128
|
+
readonly id: string;
|
|
129
|
+
/** Its kind, from the closed list. */
|
|
130
|
+
readonly kind: DriverKind;
|
|
131
|
+
/** What it can hold. */
|
|
132
|
+
limits(): DriverLimits;
|
|
133
|
+
/** Pure: what this driver will hold of the export. */
|
|
134
|
+
plan(manifest: DataManifest): Holding;
|
|
135
|
+
/** Writes the export; an export already held changes nothing. Refuses with a DataRefusal. */
|
|
136
|
+
write(source: ExportSource, context: WriteContext): Promise<CopyReceipt>;
|
|
137
|
+
/** Every copy it keeps, newest first. */
|
|
138
|
+
list(): Promise<readonly CopyRef[]>;
|
|
139
|
+
/** Opens one copy. */
|
|
140
|
+
read(ref: CopyRef, context: OpenContext): Promise<ExportSource>;
|
|
141
|
+
/** Without an identity: structure, sealing, counts and cap only (what a commit hook proves); with one, every digest too. */
|
|
142
|
+
verify(ref: CopyRef, context: OpenContext | null): Promise<CopyVerdict>;
|
|
143
|
+
}
|
|
144
|
+
/** The holding of `manifest` by a driver that holds only `forms`: every set of another form is named as omitted. */
|
|
145
|
+
export declare function holdingFor(manifest: DataManifest, forms: readonly EntryForm[]): Holding;
|
package/dist/driver.js
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { DomainError } from "@starci/common";
|
|
2
|
+
/**
|
|
3
|
+
* A refusal with a retry class: `configuration` is never retried (one item for a person: e.g. a copy that outgrew git
|
|
4
|
+
* and needs s3), `transient` is retried on the job's ladder (a network or remote failure).
|
|
5
|
+
*/
|
|
6
|
+
export class DataRefusal extends DomainError {
|
|
7
|
+
/** Whether a retry can help. */
|
|
8
|
+
retry;
|
|
9
|
+
constructor(code, retry, params, cause) {
|
|
10
|
+
super({ code, params, cause });
|
|
11
|
+
this.retry = retry;
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
/** The holding of `manifest` by a driver that holds only `forms`: every set of another form is named as omitted. */
|
|
15
|
+
export function holdingFor(manifest, forms) {
|
|
16
|
+
const sets = manifest.sets.filter((set) => forms.includes(set.form));
|
|
17
|
+
const omitted = manifest.sets
|
|
18
|
+
.filter((set) => !forms.includes(set.form))
|
|
19
|
+
.map((set) => ({ store: set.store, set: set.set, reason: `the driver holds no ${set.form} entries` }));
|
|
20
|
+
return { exportDigest: manifest.exportDigest, holds: omitted.length === 0 ? "all" : "subset", sets, omitted };
|
|
21
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import type { DriverAdapter } from "../driver.js";
|
|
2
|
+
/**
|
|
3
|
+
* The `git` driver: one copy repository holds one data set's snapshot, one commit per changed snapshot.
|
|
4
|
+
*
|
|
5
|
+
* manifest.json the DataManifest + the file index (path -> plaintext sha256, bytes) + the shard widths
|
|
6
|
+
* data/<store>/<set>/<shard>.json records: canonical JSON, one line per key; `<shard>` = `all` or a hash prefix of the key
|
|
7
|
+
* blobs/<store>/<set>/<aa>/<id>[.<n>].bin blobs: `<id>` = sha256 of set and key, chunked at 4 MiB
|
|
8
|
+
* index/<store>/<set>.json per blob set: key -> media, sha256, chunks
|
|
9
|
+
*
|
|
10
|
+
* Sealing follows the purpose, never a choice: a `seed-standard` is plaintext (readable, diffable; it holds no secret);
|
|
11
|
+
* a `seed-backup` seals every file under data/, blobs/ and index/ with sops (binary mode, age recipients of its one
|
|
12
|
+
* environment), the file then named `<name>.sops.json`. The manifest stays plaintext and holds no value.
|
|
13
|
+
*
|
|
14
|
+
* The cap is the whole snapshot: the bytes of every file under data/, blobs/ and index/ in the working tree, history
|
|
15
|
+
* not counted, at most 500 MiB (warning past 400 MiB); a write past it is refused DATA_GIT_CAP_EXCEEDED: the data set
|
|
16
|
+
* has outgrown git and needs the s3 driver. A file whose plaintext did not change is never rewritten, so an unchanged
|
|
17
|
+
* entry keeps an unchanged file and an unchanged export commits nothing.
|
|
18
|
+
*/
|
|
19
|
+
export interface GitDriverOptions {
|
|
20
|
+
/** The driver id the stack manifest declares (e.g. `nivo-lite-seed-backup-prod`). */
|
|
21
|
+
readonly id: string;
|
|
22
|
+
/** The local working copy of the repository (outside every code repository). Created by `git init` or cloned when missing. */
|
|
23
|
+
readonly checkout: string;
|
|
24
|
+
/** The remote URL; when set the driver clones, pulls before a write and pushes after it. Never a URL holding a credential. */
|
|
25
|
+
readonly remote?: string;
|
|
26
|
+
/** The branch; `main` by default. */
|
|
27
|
+
readonly branch?: string;
|
|
28
|
+
/** The cap of the whole snapshot; GIT_CAP_BYTES by default (a smaller one only in tests). */
|
|
29
|
+
readonly capBytes?: number;
|
|
30
|
+
/** The warning threshold; GIT_WARN_BYTES by default. */
|
|
31
|
+
readonly warnBytes?: number;
|
|
32
|
+
/** Runs a program; spawnSync by default (tests substitute nothing: they use real git and sops with a throwaway key). */
|
|
33
|
+
readonly run?: Runner;
|
|
34
|
+
/** Extra environment for git and sops (PATH, HOME); never an identity: an identity comes with an OpenContext. */
|
|
35
|
+
readonly env?: Readonly<Record<string, string>>;
|
|
36
|
+
}
|
|
37
|
+
/** The result of one program run. */
|
|
38
|
+
export interface RunResult {
|
|
39
|
+
/** The exit status, null when it did not start. */
|
|
40
|
+
readonly status: number | null;
|
|
41
|
+
/** stdout bytes. */
|
|
42
|
+
readonly stdout: Buffer;
|
|
43
|
+
/** stderr bytes; never printed by the driver (sops prints no value there, but the driver keeps only a class). */
|
|
44
|
+
readonly stderr: Buffer;
|
|
45
|
+
}
|
|
46
|
+
/** Runs a program in a directory with optional stdin and environment. */
|
|
47
|
+
export type Runner = (program: string, args: readonly string[], options: {
|
|
48
|
+
readonly cwd: string;
|
|
49
|
+
readonly input?: Buffer;
|
|
50
|
+
readonly env?: Readonly<Record<string, string>>;
|
|
51
|
+
}) => RunResult;
|
|
52
|
+
/** Builds the git driver over a local working copy. */
|
|
53
|
+
export declare function createGitDriver(options: GitDriverOptions): DriverAdapter;
|