IF Commons GitHub

AnyFS SSH helper

0002Active

0002-anyfs-ssh-helper · owner if · domain commons

Requirements

FR-001checkpassing

The helper of the posix dialect MUST be the script src/helper/posix.sh, and the module src/helper/posix.ts that carries its text and its SHA-256 MUST be made from it by bun tools/helper.ts; the hash in the module MUST be the SHA-256 of the script, and verify MUST fail where the module is not what the script makes.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/helper.test.ts: the module is made from the script and the hash is the hash of the script

Proved by: anyfs-ssh/suite/helper.test.ts

Written in: anyfs-ssh/src/helper/mod.ts, anyfs-ssh/src/helper/posix.ts, anyfs-ssh/tools/helper.ts

Tests: passed: suite/helper.test.ts the module is made from the script and the hash is the hash of the script

FR-002checkpassing

The dialect of a host MUST be a closed union (HostDialect, posix today) and helperOf MUST state every case, so that a dialect added later is a compile error wherever a case is missing.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/protocol.test.ts: the posix helper; tsc: the exhaustive match of helperOf

Proved by: anyfs-ssh/suite/protocol.test.ts

Written in: anyfs-ssh/src/dialect.ts

Tests: passed: suite/protocol.test.ts the posix dialect has its helper, its shell and its hash, and the match on a dialect state

FR-003checkpassing

A call of the helper MUST be one argument vector: the kept script, the command, the folder and the arguments, or the carried script as the argument of sh -c; no word of it MUST hold the bytes of an object, which go over standard input.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/protocol.test.ts: the vector of a call; suite/store.test.ts: no argument holds a body

Proved by: anyfs-ssh/suite/helper.test.ts, anyfs-ssh/suite/protocol.test.ts

Written in: anyfs-ssh/src/protocol.ts

Tests: passed: suite/helper.test.ts under bash: probe, write, read, stat, list, delete and rename answer as the protocol says; passed: suite/helper.test.ts under dash: probe, write, read, stat, list, delete and rename answer as the protocol says; passed: suite/protocol.test.ts a call is one vector: the kept script and the command, or the carried script as the argume

FR-004checkpassing

The helper MUST answer by its exit status and its output: 0 done, 10 missing, 11 conflict with found absent or found sha256:HEX (and at to for the target of a rename), 12 refused with the reason, 13 locked, 14 too large, 21 no tool for SHA-256, 22 no such folder, 30 a hash that is not the one asked for, and any other status a failure; the library MUST read each as one case of a closed union, and 255 or a signal as a lost connection.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/protocol.test.ts: each exit status is one answer; suite/helper.test.ts: the commands answer as the protocol says

Proved by: anyfs-ssh/suite/helper.test.ts, anyfs-ssh/suite/protocol.test.ts

Written in: anyfs-ssh/src/protocol.ts

Tests: passed: suite/helper.test.ts under bash: probe, write, read, stat, list, delete and rename answer as the protocol says; passed: suite/helper.test.ts under dash: probe, write, read, stat, list, delete and rename answer as the protocol says; passed: suite/protocol.test.ts each exit status of the helper is one answer of a closed union; passed: suite/protocol.test.ts the lines of the helper are read back, and a line that is not one is a sentence

FR-005checkpassing

A write, a delete and a rename MUST take an expectation (any, absent or rev:HEX) and MUST leave the object as it was, naming what was found, where it does not hold; an expectation of no object MUST be an exclusive link, and one of a revision MUST be held under the lock of the path.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/helper.test.ts: an expectation that does not hold is a conflict that says what was found

Proved by: anyfs-ssh/suite/helper.test.ts

Tests: passed: suite/helper.test.ts under bash: an expectation that does not hold is a conflict that says what was found, and ; passed: suite/helper.test.ts under dash: an expectation that does not hold is a conflict that says what was found, and

FR-006checkpassing

A path MUST be refused as shape where it is empty, absolute, has an empty, . or .. segment or a line end, as hidden where a segment begins with .anyfs-, and as outside where it, or a link on the way to it, leaves the folder of the store; a link MUST never be an object and a file outside the folder MUST never be read, written or removed.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/helper.test.ts: a name that is not a path of the store, a path outside the folder and a link are refused

Proved by: anyfs-ssh/suite/helper.test.ts

Tests: passed: suite/helper.test.ts a store at the root of the host's file system reads what is below it and keeps its locks i; passed: suite/helper.test.ts under bash: a name that is not a path of the store, a path outside the folder and a link a; passed: suite/helper.test.ts under dash: a name that is not a path of the store, a path outside the folder and a link a

FR-007checkpassing

A name with a space, a quote, a dollar sign, a backquote, a leading dash, a glob character or a letter that is not ASCII MUST be kept exactly as it is, and no name MUST be run by the shell.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/helper.test.ts: names with spaces, quotes and dollar signs are kept as they are

Proved by: anyfs-ssh/suite/helper.test.ts

Tests: passed: suite/helper.test.ts under bash: names with spaces, quotes, dollar signs, a leading dash and non-ASCII letters ; passed: suite/helper.test.ts under dash: names with spaces, quotes, dollar signs, a leading dash and non-ASCII letters

FR-008checkpassing

Of many writers that expect the same revision exactly one MUST win; a lock MUST be a folder made by mkdir, a lock of a process that is gone MUST be taken over under a second lock that is looked at again once held, and one of a process that is alive MUST be waited for, to a limit, after which the answer is locked.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/helper.test.ts: exactly one of many writers wins; a lock of a process that is gone is taken over

Proved by: anyfs-ssh/suite/helper.test.ts

Tests: passed: suite/helper.test.ts a lock that belongs to a process that is gone is taken over, and one that is alive is wait; passed: suite/helper.test.ts under bash: of many writers that expect the same revision exactly one wins; passed: suite/helper.test.ts under dash: of many writers that expect the same revision exactly one wins

FR-009checkpassing

A write MUST go whole through a temporary file in the folder of the object and a rename, and a read or a write of more than the most it is told MUST be refused as too large with nothing kept.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/helper.test.ts: more than the most is refused; no temporary file is left

Proved by: anyfs-ssh/suite/helper.test.ts

Tests: passed: suite/helper.test.ts a read of more than the most it is told is refused, and a write of more is refused with no

FR-010checkpassing

install MUST keep the script, given on standard input, under a name that carries its hash in a folder of the account, once, not writable, and MUST refuse a script whose hash is not the one asked for and keep nothing.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/helper.test.ts: the helper is kept under its hash, once, and a script that does not have the hash is refused

Proved by: anyfs-ssh/suite/helper.test.ts

Tests: passed: suite/helper.test.ts the helper is kept on a host under a name that carries its hash, once, and a script that d

Acceptance scenarios

  1. Given two writers that expect the revision an object has, When both write at once, Then one is told it is done and the other that the object is at the new revision, per FR-008.
  2. Given a link in the folder that points outside it, When a path through it is read or written, Then the answer is outside and the file outside is unchanged, per FR-006.

Out of scope

  • A dialect for hosts that have PowerShell, batch, history, ranges and streams, and the fleet store itself: their own specifications.

Edge cases

  • A lock left by a process killed in the moment between making the folder and writing its pid: it is waited for to the limit, then locked, per FR-008.
  • A host that has no stat that gives a time: the time of an object is left out, per FR-004.

Assumptions

  • The host has a POSIX shell and the utilities of POSIX, and a tool for SHA-256.

Open questions

  • None.

Key entities

  • The helper - the script that runs on the host.
  • The store - the store of AnyFS over a folder of the host.

Success criteria

SC-001success criterion

The tests of the specification pass under dash and bash.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Titles, headings, exports, tables, columns and requirements. Esc closes.