Repository navigation
Expand file tree
/
Copy pathdurable-resource.ts
More file actions
106 lines (97 loc) · 3.65 KB
/
Copy pathdurable-resource.ts
File metadata and controls
106 lines (97 loc) · 3.65 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
import type { JsonObject } from './json.ts';
export type CleanupPendingReason =
| 'ownership-fence-lost'
| 'owner-unavailable'
| 'transport-failed'
| 'cleanup-unconfirmed'
| 'manual-recovery-required';
export type CleanupOutcome =
| Readonly<{ status: 'cleaned' }>
| Readonly<{ status: 'already-missing' }>
| Readonly<{
status: 'cleanup-pending';
reason: CleanupPendingReason;
message?: string;
}>;
export type FinishOutcome<Result> =
| Readonly<{ status: 'completed'; result: Result; alreadyCompleted?: boolean }>
| Readonly<{
status: 'cleanup-pending';
reason: CleanupPendingReason;
message?: string;
}>;
/**
* The durable half of a stop that has not committed yet. A resource kind with mid-stop facts to keep
* (screen recording, ADR 0024 2.3) hands its handle this so the stop can persist what just became
* durable — a collected copy, a finished export — into its own manifest while the fence it already
* holds is held. `learned` is the manifest's metadata as an earlier attempt left it, which is what
* lets a retry resume instead of repeating work that would change the artifact. The facts are the
* manifest's own JSON: the mechanics merge them and never interpret them.
*/
export type DurableCaptureProgress = Readonly<{
record(fact: JsonObject): void;
readonly learned: JsonObject | undefined;
}>;
/** Common lifecycle shape implemented by a facet-specific live handle contract. */
export type LiveResourceHandle<Result> = AsyncDisposable &
Readonly<{
finish(progress?: DurableCaptureProgress): Promise<FinishOutcome<Result>>;
forceCleanup(): Promise<CleanupOutcome>;
}>;
export type ResourceUnreattachableReason =
| 'descriptor-invalid'
| 'descriptor-version-unsupported'
| 'owner-unavailable'
| 'transport-not-reattachable'
| 'ownership-fence-lost';
export type ReattachOutcome<Handle extends AsyncDisposable, Result> =
| Readonly<{ status: 'active'; handle: Handle }>
| Readonly<{ status: 'completed'; result: Result }>
| Readonly<{ status: 'missing' }>
| Readonly<{
status: 'unreattachable';
reason: ResourceUnreattachableReason;
message?: string;
}>;
export function isConfirmedCleanup(
outcome: CleanupOutcome,
): outcome is Extract<CleanupOutcome, { status: 'cleaned' | 'already-missing' }> {
return outcome.status === 'cleaned' || outcome.status === 'already-missing';
}
/** Shares in-flight cleanup and retains only confirmed release across cleanup and disposal. */
export function createRetryableCleanup(
clean: () => Promise<CleanupOutcome>,
assertConfirmed: (outcome: CleanupOutcome, cause?: unknown) => void,
) {
let cleanup: Promise<CleanupOutcome> | undefined;
const forceCleanup = (): Promise<CleanupOutcome> =>
(cleanup ??= clean().then(
(outcome) => {
if (!isConfirmedCleanup(outcome)) cleanup = undefined;
return outcome;
},
(error) => {
cleanup = undefined;
throw error;
},
));
return {
forceCleanup,
[Symbol.asyncDispose]: async () => {
// A rejected cleanup confirms nothing, so disposal reports it as cleanup-pending.
const { outcome, cause } = await forceCleanup().then(
(confirmed) => ({ outcome: confirmed, cause: undefined }),
(error: unknown) => ({
outcome: {
status: 'cleanup-pending',
reason: 'cleanup-unconfirmed',
// Non-Error rejections keep the facet's default message; `cause` keeps the raw value.
message: error instanceof Error ? error.message : undefined,
} as const,
cause: error,
}),
);
assertConfirmed(outcome, cause);
},
};
}