|
| 1 | +/** |
| 2 | + * `<TempDir>` — an isolated temporary directory (specs/executable-mdx-spec.md §6.11). |
| 3 | + * |
| 4 | + * Written with content it is a working directory: everything expanded inside |
| 5 | + * observes it as the contextual `Env.cwd`, and it is removed when the content |
| 6 | + * finishes, fails, or is cancelled. Written self-closing it is an allocation: |
| 7 | + * the directory is retained at the invocation site so a later sibling can use |
| 8 | + * the path it renders, and removed with that scope. |
| 9 | + */ |
| 10 | + |
| 11 | +import { ensure, resource, until } from "effection"; |
| 12 | +import type { Operation } from "effection"; |
| 13 | +import { rm } from "@effectionx/fs"; |
| 14 | +import { API } from "@executablemd/runtime"; |
| 15 | +import { ReplayGuard, StaleInputError } from "@executablemd/durable-streams"; |
| 16 | +import { mkdtemp, realpath } from "node:fs/promises"; |
| 17 | +import { tmpdir } from "node:os"; |
| 18 | +import { join } from "node:path"; |
| 19 | +import { retain } from "../component-api.ts"; |
| 20 | +import { hasContent, useContent } from "../content-context.ts"; |
| 21 | + |
| 22 | +export const props = { |
| 23 | + type: "object", |
| 24 | + properties: {}, |
| 25 | + additionalProperties: false, |
| 26 | +}; |
| 27 | + |
| 28 | +/** |
| 29 | + * A directory this call created, named by its canonical path. |
| 30 | + * |
| 31 | + * `mkdtemp` creates and names in one step, so the directory cannot already |
| 32 | + * exist and cannot be claimed between the two — which generating a name and |
| 33 | + * then creating it does not rule out. |
| 34 | + * |
| 35 | + * The path is then canonicalized: on macOS `tmpdir()` is a symlink |
| 36 | + * (`/var/folders/…`) while a child process resolves it (`/private/var/…`). |
| 37 | + * Canonicalizing is what makes the rendered path, `Env.cwd`, and a |
| 38 | + * subprocess's own `cwd` the same string, so a document can compare them. |
| 39 | + * |
| 40 | + * `@effectionx/fs` has neither operation, so both come from Node. |
| 41 | + */ |
| 42 | +function useTemporaryDirectory(): Operation<string> { |
| 43 | + return resource(function* (provide) { |
| 44 | + const created = yield* until(mkdtemp(join(tmpdir(), "xmd-tempdir-"))); |
| 45 | + yield* ensure(() => rm(created, { recursive: true, force: true })); |
| 46 | + yield* provide(yield* until(realpath(created))); |
| 47 | + }); |
| 48 | +} |
| 49 | + |
| 50 | +/** |
| 51 | + * Refuse to replay a recorded effect inside this directory. |
| 52 | + * |
| 53 | + * Every run creates a *new* directory, but a journaled effect is matched by |
| 54 | + * description alone. Replaying one recorded under an earlier run would hand |
| 55 | + * the document output naming a directory that no longer exists, and the |
| 56 | + * filesystem work the effect stands for would never happen in the directory |
| 57 | + * this run created. Neither is detectable downstream, so the effect is refused |
| 58 | + * where it is recognised. |
| 59 | + * |
| 60 | + * Re-executing recorded effects inside a freshly established environment is a |
| 61 | + * durability design of its own (#218); until then a document that resumes from |
| 62 | + * a partial journal stops here rather than continuing on stale results. |
| 63 | + */ |
| 64 | +function refuseReplayInside(directory: string): Operation<void> { |
| 65 | + return ReplayGuard.around({ |
| 66 | + decide([event], _next) { |
| 67 | + return { |
| 68 | + outcome: "error", |
| 69 | + // A StaleInputError, so expansion propagates it instead of rendering |
| 70 | + // it: the ambient error policy must not be able to downgrade a |
| 71 | + // durability failure to a comment and let later siblings run. |
| 72 | + error: new StaleInputError( |
| 73 | + `<TempDir> cannot replay the recorded ${event.description.type} effect ` + |
| 74 | + `"${event.description.name}": this run created ${directory}, and the recorded ` + |
| 75 | + "result belongs to a directory an earlier run created and removed. Re-run the " + |
| 76 | + "document from the start rather than resuming from a partial journal.", |
| 77 | + { coroutineId: event.coroutineId, description: event.description }, |
| 78 | + ), |
| 79 | + }; |
| 80 | + }, |
| 81 | + }); |
| 82 | +} |
| 83 | + |
| 84 | +export default function* (): Operation<string> { |
| 85 | + if (yield* hasContent()) { |
| 86 | + const directory = yield* useTemporaryDirectory(); |
| 87 | + yield* API.Env.around( |
| 88 | + { |
| 89 | + // deno-lint-ignore require-yield |
| 90 | + *cwd() { |
| 91 | + return directory; |
| 92 | + }, |
| 93 | + }, |
| 94 | + { at: "min" }, |
| 95 | + ); |
| 96 | + yield* refuseReplayInside(directory); |
| 97 | + return yield* useContent(); |
| 98 | + } |
| 99 | + return yield* retain(useTemporaryDirectory); |
| 100 | +} |
0 commit comments