IF Commons GitHub

AnyFS SSH store

0003Active

0003-anyfs-ssh-store · owner if · domain commons

Requirements

FR-001checkpassing

The store MUST pass every case of the conformance suite of AnyFS that its capabilities hold it to, under each shell of the host and with the helper kept on the host and carried in each call.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: the store passes every case of the conformance suite

Proved by: anyfs-ssh/suite/sshd.test.ts, anyfs-ssh/suite/store.test.ts

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

Tests: passed: suite/sshd.test.ts against a real ssh server, named by the environment or made for the run, the store passes ; passed: suite/store.test.ts under bash, with the helper carried in each call: the store passes every case of the confo; passed: suite/store.test.ts under dash, with the helper kept on the host: the store passes every case of the conforman

FR-002checkpassing

The store MUST have the capabilities read, write, list, stat, delete, cas and rename and no other, MUST be strong, MUST have the place ssh of the host and the folder, and a list MUST be paged by name with a cursor.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: the capabilities, the place and the pages of a list

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

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

Tests: passed: suite/store.test.ts under bash, with the helper carried in each call: the store passes every case of the confo; passed: suite/store.test.ts under dash, with the helper kept on the host: the store passes every case of the conforman; passed: suite/store.test.ts a list is paged by name with a cursor and a rename moves an object and says what stood in ; passed: suite/store.test.ts the store has the capabilities it keeps and no others, strong consistency and the place of

FR-003checkpassing

The revision of an object MUST be sha256: and the digest of its bytes, the same as the store in memory gives for the same bytes, computed by this library for what it reads and writes and by the host for stat and list.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: the revision is the digest of the bytes, the same as in memory

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

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

Tests: passed: suite/store.test.ts the revision of an object is sha256: and the digest of its bytes, the same as in memory

FR-004checkpassing

The bytes of an object MUST go over standard input and standard output, never in an argument, and every call MUST be one argument vector of the program sh that the executor quotes, so that a name with a quote, a dollar sign or a leading dash is one word.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: no argument holds a body and a name is one word

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

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

Tests: passed: suite/store.test.ts the bytes of an object go over standard input, never in an argument, and every call is one

FR-005checkpassing

A path that leaves the folder, by a link or otherwise, MUST be refused as outside-scope, the helper's own names and the names another file system could not hold MUST be refused as unportable-path, and a file outside the folder MUST never be touched.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: a path that leaves the folder by a link is refused

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

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

Tests: passed: suite/store.test.ts a path that leaves the folder by a link or is the helper's own name is refused, and a file

FR-006checkpassing

The helper MUST be kept on the host under a name that carries its hash and used from there; where it cannot be kept it MUST be carried in each call with no capability lost; and a host whose helper is not the pinned one MUST be refused, with nothing run from it.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: the helper is kept under its hash, carried where it cannot be kept, and a helper that is not the pinned one is refused

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

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

Tests: passed: suite/store.test.ts a host whose helper is not the pinned one is refused and nothing is run from it; passed: suite/store.test.ts the helper is kept on the host under its hash and used from there; where it cannot be kept

FR-007checkpassing

A lost connection and a call stopped by a signal or a time MUST be unavailable and retryable, a call the host answers as a failure MUST be unavailable and not retryable, and a lock that is held too long MUST be unavailable and retryable.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: a lost connection is retryable and a failure is not

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

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

Tests: passed: suite/store.test.ts a lost connection is unavailable and may be tried again; a call that the host answers as a

FR-008checkpassing

Bytes that the host did not keep as sent, or a revision it answers that is not the revision of the bytes sent, MUST be tampered, never a success.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: bytes that the host did not keep as sent are tampered

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

Tests: passed: suite/store.test.ts bytes that the host did not keep as sent are tampered, not a success

FR-009checkpassing

An object of more than maxBytes (32 MiB where it is not said) MUST be refused as too-large when written, before it is sent, and when read, before it is taken, and the trait maxObject of the store MUST say the limit.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: an object of more than the most is refused

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

Tests: passed: suite/store.test.ts an object of more than the most the store takes is refused when written and when read

FR-010checkpassing

A host with no tool for SHA-256, a folder that is not there (and was not asked to be made), a folder that is not an absolute path and a helper of another protocol or dialect MUST not be taken, each with its sentence, and the folder MUST be made where create says so.

Enforced (check): .github: cd commons/anyfs-ssh && bun run verify — suite/store.test.ts: a host with no tool for SHA-256, no such folder or a helper of another protocol is not taken

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

Tests: passed: suite/store.test.ts a host with no tool for SHA-256, no such folder or a helper of another protocol is not tak

Acceptance scenarios

  1. Given a host with a folder of the fleet, When two machines write the same asset expecting the same revision, Then one write is done and the other is a conflict that names the revision found, per FR-003.
  2. Given a connection that is lost, When a read is asked, Then the answer is unavailable and retryable, per FR-007.

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 host that has only openssl for SHA-256: it is used, per FR-010.
  • A write whose bytes the network changed: tampered, per FR-008.

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.