@bevel-software/platform-shared 0.10.0 → 0.11.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.
|
@@ -103,10 +103,18 @@ export interface IWorkflowService {
|
|
|
103
103
|
* rare case where a group of files must land together or not at all (e.g. a
|
|
104
104
|
* role rename rewriting `roles.yaml` + every reference). Does NOT write
|
|
105
105
|
* content: the caller writes the files first (e.g. via the lock-aware
|
|
106
|
-
* filesystem) and is responsible for any validation. Returns null on a
|
|
107
|
-
*
|
|
106
|
+
* filesystem) and is responsible for any validation. Returns null on a
|
|
107
|
+
* no-op — nothing to commit WITHIN SCOPE: with `onlyPaths` given, none of
|
|
108
|
+
* those paths is dirty (other paths may well be); without it, the whole
|
|
109
|
+
* tree is clean.
|
|
110
|
+
*
|
|
111
|
+
* `onlyPaths` (workspace-relative) scopes the commit to the caller's own
|
|
112
|
+
* files: on a shared per-branch workspace other paths may be dirty from a
|
|
113
|
+
* concurrent save whose commit is still queued, and an unscoped commit
|
|
114
|
+
* would sweep them in under this caller's author/summary. Omitted → the
|
|
115
|
+
* whole dirty set (legacy behavior for flows that own the workspace).
|
|
108
116
|
*/
|
|
109
|
-
commitChanges(workspaceId: string, user: AuthUser, summary: string): Promise<Change | null>;
|
|
117
|
+
commitChanges(workspaceId: string, user: AuthUser, summary: string, onlyPaths?: string[]): Promise<Change | null>;
|
|
110
118
|
/** Per-file history. Newest first; clamps to ≤ 100 entries. */
|
|
111
119
|
listChangesForFile(workspaceId: string, path: string, limit?: number): Promise<Change[]>;
|
|
112
120
|
/**
|
|
@@ -140,8 +148,23 @@ export interface IWorkflowService {
|
|
|
140
148
|
*
|
|
141
149
|
* Pessimistic per the spec. Auto-released when the lock expires past TTL
|
|
142
150
|
* without a heartbeat — stale locks must not block forever.
|
|
151
|
+
*
|
|
152
|
+
* `opts.coordination` acquires the lock as a PURE MUTEX: the implementation
|
|
153
|
+
* skips its write-permission gate for the path, because the caller only
|
|
154
|
+
* wants to serialize against the path's writer (e.g. hold a machine-owned
|
|
155
|
+
* file steady across a read → check → decide flow) and will never write the
|
|
156
|
+
* path itself. A coordination hold grants NO write authority — the mode is
|
|
157
|
+
* persisted on the lock row, and every path that would treat "you hold the
|
|
158
|
+
* lock" as write possession (`commitFileWhileLocked`, `releaseLock`'s
|
|
159
|
+
* commit enqueue) refuses a coordination hold. Contention, TTL, and
|
|
160
|
+
* heartbeat behave identically. Release ONLY via `releaseLockNoCommit` (or
|
|
161
|
+
* `releaseLockUntouched`) — `releaseLock` rejects rather than ever enqueue
|
|
162
|
+
* a commit for a hold that was never allowed to write. Internal callers
|
|
163
|
+
* only; never plumbed from a route.
|
|
143
164
|
*/
|
|
144
|
-
acquireLock(workspaceId: string, branch: string, path: string, user: AuthUser
|
|
165
|
+
acquireLock(workspaceId: string, branch: string, path: string, user: AuthUser, opts?: {
|
|
166
|
+
coordination?: boolean;
|
|
167
|
+
}): Promise<AcquireLockResult>;
|
|
145
168
|
/** Heartbeat to keep an acquired lock alive past its current TTL. */
|
|
146
169
|
heartbeatLock(workspaceId: string, branch: string, path: string, user: AuthUser): Promise<FileLock>;
|
|
147
170
|
/**
|
|
@@ -177,10 +200,44 @@ export interface IWorkflowService {
|
|
|
177
200
|
* lock-aware write — when the underlying op threw, we don't want the
|
|
178
201
|
* normal `releaseLock` to commit + push whatever partial state happens
|
|
179
202
|
* to be on disk. The lock row goes away (so the next caller can edit
|
|
180
|
-
* the file)
|
|
181
|
-
*
|
|
203
|
+
* the file) and the path's working-tree changes are discarded back to
|
|
204
|
+
* HEAD on a BEST-EFFORT basis: the implementation logs and continues
|
|
205
|
+
* when the discard itself fails (releasing beats stranding the lock),
|
|
206
|
+
* so a caller must not treat a completed release as proof the tree is
|
|
207
|
+
* clean — worst case the path stays dirty until the next save on it.
|
|
208
|
+
* Idempotent like `releaseLock`: a no-op when the caller doesn't hold
|
|
209
|
+
* the lock.
|
|
182
210
|
*/
|
|
183
211
|
releaseLockNoCommit(workspaceId: string, branch: string, path: string, user: AuthUser): Promise<void>;
|
|
212
|
+
/**
|
|
213
|
+
* Drop the lock for a path the caller held but **never touched** — the
|
|
214
|
+
* third release shape, between `releaseLock` and `releaseLockNoCommit`.
|
|
215
|
+
* Neither enqueues a commit (on a shared workspace the path may carry a
|
|
216
|
+
* PRIOR save's dirty bytes whose queued commit an enqueue would re-attribute
|
|
217
|
+
* to this caller and whose retry ladder it would reset) nor discards (a
|
|
218
|
+
* discard back to HEAD would destroy those same still-queued bytes). Used
|
|
219
|
+
* by batch flows for paths that were merely locked — a creator seed that
|
|
220
|
+
* no-op'd, a path never reached before the batch failed. Idempotent like
|
|
221
|
+
* the other releases: a no-op when the caller doesn't hold the lock.
|
|
222
|
+
*/
|
|
223
|
+
releaseLockUntouched(workspaceId: string, branch: string, path: string, user: AuthUser): Promise<void>;
|
|
224
|
+
/**
|
|
225
|
+
* Whether the background commit queue holds a LIVE row (one the worker
|
|
226
|
+
* will still drive — pending or running, not a terminally-escalated one)
|
|
227
|
+
* for `(branch, path)`. Lets a caller that landed a commit but hit a push
|
|
228
|
+
* failure PROVE the retry vehicle exists instead of inferring it from
|
|
229
|
+
* lock state (a release that failed before its enqueue and a release that
|
|
230
|
+
* enqueued-then-dropped both leave the lock gone — only the queue itself
|
|
231
|
+
* can tell them apart).
|
|
232
|
+
*/
|
|
233
|
+
hasQueuedCommit(workspaceId: string, branch: string, path: string): Promise<boolean>;
|
|
234
|
+
/**
|
|
235
|
+
* Whether the workspace's local branch is ahead of (or has no) upstream —
|
|
236
|
+
* i.e. holds commits not yet published. The complement of `hasQueuedCommit`
|
|
237
|
+
* for push-retry proofs: no live queued row AND nothing unpushed means the
|
|
238
|
+
* worker already drained the row and published it.
|
|
239
|
+
*/
|
|
240
|
+
hasUnpushedCommits(workspaceId: string): Promise<boolean>;
|
|
184
241
|
/** Current lock holder for `(branch, path)`, or null when nobody holds it. */
|
|
185
242
|
getLock(workspaceId: string, branch: string, path: string): Promise<FileLock | null>;
|
|
186
243
|
listChangeRequests(opts?: {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/workflow/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EACV,iBAAiB,EACjB,MAAM,EACN,qBAAqB,EACrB,yBAAyB,EACzB,MAAM,EACN,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,yBAAyB,EACzB,sBAAsB,EACtB,6BAA6B,EAC9B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAG/B,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtF;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpF;;;;;;;;;OASG;IACH,YAAY,CACV,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GAClC,OAAO,CAAC,IAAI,CAAC,CAAC;IAQjB,gGAAgG;IAChG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAGlE;;;;OAIG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5F,4DAA4D;IAC5D,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;;OAKG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7E;;;;OAIG;IACH,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAQ/D;;;;;;OAMG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvF
|
|
1
|
+
{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/workflow/interface.ts"],"names":[],"mappings":"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"}
|
package/dist/workflow/types.d.ts
CHANGED
|
@@ -58,6 +58,15 @@ export interface FileLock {
|
|
|
58
58
|
path: string;
|
|
59
59
|
holderUserId: string;
|
|
60
60
|
holderName: string;
|
|
61
|
+
/**
|
|
62
|
+
* How the lock was acquired. `'edit'` (the default when absent) is a normal
|
|
63
|
+
* write hold — the holder is editing and the release publishes their bytes.
|
|
64
|
+
* `'coordination'` is a pure-mutex hold (see `IWorkflowService.acquireLock`)
|
|
65
|
+
* that grants NO write authority: the write/checkpoint/commit-enqueue paths
|
|
66
|
+
* must refuse to treat it as write possession, even though its contention,
|
|
67
|
+
* TTL, and heartbeat surface is identical.
|
|
68
|
+
*/
|
|
69
|
+
mode?: 'edit' | 'coordination';
|
|
61
70
|
/** ISO timestamp when the lock was first acquired. */
|
|
62
71
|
acquiredAt: string;
|
|
63
72
|
/** ISO timestamp of the most recent heartbeat — the autosave/keepalive ping. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAI5B,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAItD;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,iBAAiB,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAI9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAIxC;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAC/C,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AACpD,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC;AAE1C,MAAM,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAC7C,MAAM,MAAM,wBAAwB,GAAG,aAAa,CAAC;AACrD,MAAM,MAAM,yBAAyB,GAAG,cAAc,CAAC;AACvD,MAAM,MAAM,oBAAoB,GAAG,eAAe,CAAC;AACnD,MAAM,MAAM,6BAA6B,GAAG,kBAAkB,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC"}
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAI5B,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAItD;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,iBAAiB,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAI9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC;IAC/B,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAIxC;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAC/C,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AACpD,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC;AAE1C,MAAM,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAC7C,MAAM,MAAM,wBAAwB,GAAG,aAAa,CAAC;AACrD,MAAM,MAAM,yBAAyB,GAAG,cAAc,CAAC;AACvD,MAAM,MAAM,oBAAoB,GAAG,eAAe,CAAC;AACnD,MAAM,MAAM,6BAA6B,GAAG,kBAAkB,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bevel-software/platform-shared",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Shared types and pure domain utilities of the Bevel core platform (auth, workspace, git/workflow contracts, branch registry).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -141,13 +141,22 @@ export interface IWorkflowService {
|
|
|
141
141
|
* rare case where a group of files must land together or not at all (e.g. a
|
|
142
142
|
* role rename rewriting `roles.yaml` + every reference). Does NOT write
|
|
143
143
|
* content: the caller writes the files first (e.g. via the lock-aware
|
|
144
|
-
* filesystem) and is responsible for any validation. Returns null on a
|
|
145
|
-
*
|
|
144
|
+
* filesystem) and is responsible for any validation. Returns null on a
|
|
145
|
+
* no-op — nothing to commit WITHIN SCOPE: with `onlyPaths` given, none of
|
|
146
|
+
* those paths is dirty (other paths may well be); without it, the whole
|
|
147
|
+
* tree is clean.
|
|
148
|
+
*
|
|
149
|
+
* `onlyPaths` (workspace-relative) scopes the commit to the caller's own
|
|
150
|
+
* files: on a shared per-branch workspace other paths may be dirty from a
|
|
151
|
+
* concurrent save whose commit is still queued, and an unscoped commit
|
|
152
|
+
* would sweep them in under this caller's author/summary. Omitted → the
|
|
153
|
+
* whole dirty set (legacy behavior for flows that own the workspace).
|
|
146
154
|
*/
|
|
147
155
|
commitChanges(
|
|
148
156
|
workspaceId: string,
|
|
149
157
|
user: AuthUser,
|
|
150
158
|
summary: string,
|
|
159
|
+
onlyPaths?: string[],
|
|
151
160
|
): Promise<Change | null>;
|
|
152
161
|
/** Per-file history. Newest first; clamps to ≤ 100 entries. */
|
|
153
162
|
listChangesForFile(workspaceId: string, path: string, limit?: number): Promise<Change[]>;
|
|
@@ -191,12 +200,26 @@ export interface IWorkflowService {
|
|
|
191
200
|
*
|
|
192
201
|
* Pessimistic per the spec. Auto-released when the lock expires past TTL
|
|
193
202
|
* without a heartbeat — stale locks must not block forever.
|
|
203
|
+
*
|
|
204
|
+
* `opts.coordination` acquires the lock as a PURE MUTEX: the implementation
|
|
205
|
+
* skips its write-permission gate for the path, because the caller only
|
|
206
|
+
* wants to serialize against the path's writer (e.g. hold a machine-owned
|
|
207
|
+
* file steady across a read → check → decide flow) and will never write the
|
|
208
|
+
* path itself. A coordination hold grants NO write authority — the mode is
|
|
209
|
+
* persisted on the lock row, and every path that would treat "you hold the
|
|
210
|
+
* lock" as write possession (`commitFileWhileLocked`, `releaseLock`'s
|
|
211
|
+
* commit enqueue) refuses a coordination hold. Contention, TTL, and
|
|
212
|
+
* heartbeat behave identically. Release ONLY via `releaseLockNoCommit` (or
|
|
213
|
+
* `releaseLockUntouched`) — `releaseLock` rejects rather than ever enqueue
|
|
214
|
+
* a commit for a hold that was never allowed to write. Internal callers
|
|
215
|
+
* only; never plumbed from a route.
|
|
194
216
|
*/
|
|
195
217
|
acquireLock(
|
|
196
218
|
workspaceId: string,
|
|
197
219
|
branch: string,
|
|
198
220
|
path: string,
|
|
199
221
|
user: AuthUser,
|
|
222
|
+
opts?: { coordination?: boolean },
|
|
200
223
|
): Promise<AcquireLockResult>;
|
|
201
224
|
/** Heartbeat to keep an acquired lock alive past its current TTL. */
|
|
202
225
|
heartbeatLock(workspaceId: string, branch: string, path: string, user: AuthUser): Promise<FileLock>;
|
|
@@ -245,8 +268,13 @@ export interface IWorkflowService {
|
|
|
245
268
|
* lock-aware write — when the underlying op threw, we don't want the
|
|
246
269
|
* normal `releaseLock` to commit + push whatever partial state happens
|
|
247
270
|
* to be on disk. The lock row goes away (so the next caller can edit
|
|
248
|
-
* the file)
|
|
249
|
-
*
|
|
271
|
+
* the file) and the path's working-tree changes are discarded back to
|
|
272
|
+
* HEAD on a BEST-EFFORT basis: the implementation logs and continues
|
|
273
|
+
* when the discard itself fails (releasing beats stranding the lock),
|
|
274
|
+
* so a caller must not treat a completed release as proof the tree is
|
|
275
|
+
* clean — worst case the path stays dirty until the next save on it.
|
|
276
|
+
* Idempotent like `releaseLock`: a no-op when the caller doesn't hold
|
|
277
|
+
* the lock.
|
|
250
278
|
*/
|
|
251
279
|
releaseLockNoCommit(
|
|
252
280
|
workspaceId: string,
|
|
@@ -254,6 +282,40 @@ export interface IWorkflowService {
|
|
|
254
282
|
path: string,
|
|
255
283
|
user: AuthUser,
|
|
256
284
|
): Promise<void>;
|
|
285
|
+
/**
|
|
286
|
+
* Drop the lock for a path the caller held but **never touched** — the
|
|
287
|
+
* third release shape, between `releaseLock` and `releaseLockNoCommit`.
|
|
288
|
+
* Neither enqueues a commit (on a shared workspace the path may carry a
|
|
289
|
+
* PRIOR save's dirty bytes whose queued commit an enqueue would re-attribute
|
|
290
|
+
* to this caller and whose retry ladder it would reset) nor discards (a
|
|
291
|
+
* discard back to HEAD would destroy those same still-queued bytes). Used
|
|
292
|
+
* by batch flows for paths that were merely locked — a creator seed that
|
|
293
|
+
* no-op'd, a path never reached before the batch failed. Idempotent like
|
|
294
|
+
* the other releases: a no-op when the caller doesn't hold the lock.
|
|
295
|
+
*/
|
|
296
|
+
releaseLockUntouched(
|
|
297
|
+
workspaceId: string,
|
|
298
|
+
branch: string,
|
|
299
|
+
path: string,
|
|
300
|
+
user: AuthUser,
|
|
301
|
+
): Promise<void>;
|
|
302
|
+
/**
|
|
303
|
+
* Whether the background commit queue holds a LIVE row (one the worker
|
|
304
|
+
* will still drive — pending or running, not a terminally-escalated one)
|
|
305
|
+
* for `(branch, path)`. Lets a caller that landed a commit but hit a push
|
|
306
|
+
* failure PROVE the retry vehicle exists instead of inferring it from
|
|
307
|
+
* lock state (a release that failed before its enqueue and a release that
|
|
308
|
+
* enqueued-then-dropped both leave the lock gone — only the queue itself
|
|
309
|
+
* can tell them apart).
|
|
310
|
+
*/
|
|
311
|
+
hasQueuedCommit(workspaceId: string, branch: string, path: string): Promise<boolean>;
|
|
312
|
+
/**
|
|
313
|
+
* Whether the workspace's local branch is ahead of (or has no) upstream —
|
|
314
|
+
* i.e. holds commits not yet published. The complement of `hasQueuedCommit`
|
|
315
|
+
* for push-retry proofs: no live queued row AND nothing unpushed means the
|
|
316
|
+
* worker already drained the row and published it.
|
|
317
|
+
*/
|
|
318
|
+
hasUnpushedCommits(workspaceId: string): Promise<boolean>;
|
|
257
319
|
/** Current lock holder for `(branch, path)`, or null when nobody holds it. */
|
|
258
320
|
getLock(workspaceId: string, branch: string, path: string): Promise<FileLock | null>;
|
|
259
321
|
|
package/src/workflow/types.ts
CHANGED
|
@@ -85,6 +85,15 @@ export interface FileLock {
|
|
|
85
85
|
path: string;
|
|
86
86
|
holderUserId: string;
|
|
87
87
|
holderName: string;
|
|
88
|
+
/**
|
|
89
|
+
* How the lock was acquired. `'edit'` (the default when absent) is a normal
|
|
90
|
+
* write hold — the holder is editing and the release publishes their bytes.
|
|
91
|
+
* `'coordination'` is a pure-mutex hold (see `IWorkflowService.acquireLock`)
|
|
92
|
+
* that grants NO write authority: the write/checkpoint/commit-enqueue paths
|
|
93
|
+
* must refuse to treat it as write possession, even though its contention,
|
|
94
|
+
* TTL, and heartbeat surface is identical.
|
|
95
|
+
*/
|
|
96
|
+
mode?: 'edit' | 'coordination';
|
|
88
97
|
/** ISO timestamp when the lock was first acquired. */
|
|
89
98
|
acquiredAt: string;
|
|
90
99
|
/** ISO timestamp of the most recent heartbeat — the autosave/keepalive ping. */
|