feat(lite): 0.26.0 (#10501)

* fix(backups): prevent failed CR to accumulate replicas

.eslintrc.js

@@ -85,6 +85,21 @@ module.exports = {
         XO_LITE_GIT_HEAD: true,
       },
       rules: {
+        'import/extensions': [
+          'error',
+          'ignorePackages',
+          {
+            pattern: { ts: 'always', vue: 'always' },
+            checkTypeImports: true,
+            // '@core/*' and '@/*' look like scoped packages to the plugin, which 'ignorePackages' would skip
+            pathGroupOverrides: [
+              { pattern: '@core/packages/*', action: 'ignore' }, // barrel files
+              { pattern: '@core/icons', action: 'ignore' },
+              { pattern: '@core/**', action: 'enforce' },
+              { pattern: '@/**', action: 'enforce' },
+            ],
+          },
+        ],
         'import/order': [
           'error',
           {
@@ -254,6 +269,8 @@ module.exports = {
               'zh-Hans',
               'sk',
               'pt',
+              'ar',
+              'tr',
             ],
           },
         ],

.github/workflows/changelog-check.yml

@@ -0,0 +1,36 @@
+name: Changelog
+
+# only pull requests targeting `master`: the check compares the branch to
+# `origin/master`, it would report unrelated packages on a PR based on another
+# branch
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  changed-packages:
+    # the release PR bumps every listed package and empties the list
+    if: github.head_ref != 'release'
+    runs-on: ubuntu-latest
+    steps:
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v4
+        with:
+          # the whole history is required to compute the merge base with `master`
+          fetch-depth: 0
+
+          # the check only needs commits and trees: `git diff --name-only
+          # --no-renames` compares tree entries and never reads file contents,
+          # skipping the historical blobs halves the fetch (~112 MiB → ~53 MiB)
+          filter: blob:none
+
+      # https://github.com/actions/setup-node
+      - name: Setup Node environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: '>=22.12'
+
+      # the script only uses Node builtins, no `yarn install` necessary
+      - name: Ensure changed packages are listed in CHANGELOG.unreleased.md
+        run: ./scripts/check-changed-pkgs.js

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
       - name: Install packages
         run: |
           sudo apt-get update
-          sudo apt-get install -y curl qemu-utils python3-vmdkstream git libxml2-utils libfuse2 nbdkit
+          sudo apt-get install -y curl qemu-utils python3-vmdkstream git libxml2-utils libfuse2 nbdkit open-iscsi
 
       # https://turbo.build/repo/docs/guides/ci-vendors/github-actions#caching-with-github-actionscache
       - name: Cache Turbo

.github/workflows/vectura.yml

@@ -0,0 +1,57 @@
+name: Vectura
+
+# only when vectura changes: the rest of the repository does not build it
+on:
+  push:
+    paths:
+      - '@xen-orchestra/vmware-explorer/vectura/**'
+      - .github/workflows/vectura.yml
+
+defaults:
+  run:
+    working-directory: '@xen-orchestra/vmware-explorer/vectura'
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v4
+
+      # rustup, on the runner image, installs the toolchain rust-toolchain.toml
+      # names on the first cargo command
+      - run: cargo fmt --all --check
+      - run: cargo clippy --all-targets --locked -- -D warnings
+      - run: cargo test --locked
+
+      # https://github.com/taiki-e/install-action
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-deny@0.20.2,cargo-llvm-cov@0.8.5
+
+      - run: cargo deny --locked check
+      - run: cargo llvm-cov --locked --json --summary-only --output-path target/coverage.json
+      - name: Hold the coverage floor
+        run: cargo test --locked --test coverage -- --ignored
+
+  # builds the binary as a release does, then checks it and the one in git,
+  # which xo-server runs
+  binary:
+    runs-on: ubuntu-latest
+    steps:
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v4
+
+      # https://github.com/mlugg/setup-zig
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+
+      # https://github.com/taiki-e/install-action
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-zigbuild@0.23.4
+
+      - run: scripts/build.sh "$RUNNER_TEMP/build"
+      - run: scripts/check-binary.sh "$RUNNER_TEMP/build/vectura"
+      - run: scripts/check-binary.sh vectura

.gitignore

@@ -5,6 +5,7 @@
 
 /@vates/*/dist/
 /@vates/*/node_modules/
+/@vates/node-vsphere-soap/test/config-test.mjs
 /@xen-orchestra/*/dist/
 /@xen-orchestra/*/node_modules/
 /@xen-orchestra/rest-api/open-api/spec/swagger.json

.prettierignore

@@ -5,3 +5,7 @@
 # Generated files
 /@xen-orchestra/web/src/route-map.d.ts
 /@xen-orchestra/lite/src/route-map.d.ts
+
+# Docusaurus MDX content: prettier's markdown parser corrupts JSX
+# comments ({/* … */} becomes {/_ … _/}) and other MDX constructs
+/docs/docs/**/*.md

@vates/disposable/package.json

@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@vates/multi-key-map": "^0.2.0",
-    "@xen-orchestra/async-map": "^0.1.3",
+    "@xen-orchestra/async-map": "^0.1.5",
     "@xen-orchestra/log": "^0.7.2",
     "ensure-array": "^1.0.0"
   },

@vates/fuse-vhd/package.json

@@ -19,12 +19,12 @@
   },
   "main": "./index.mjs",
   "dependencies": {
-    "@xen-orchestra/fs": "^4.9.3",
+    "@xen-orchestra/fs": "^4.9.5",
     "@xen-orchestra/log": "^0.7.2",
     "fuse-native": "^2.2.6",
     "lru-cache": "^7.14.0",
     "promise-toolbox": "^0.21.0",
-    "vhd-lib": "^4.16.1"
+    "vhd-lib": "^4.16.2"
   },
   "bin": {
     "xo-fuse-vhd": "./cli.mjs"

@vates/iscsi/.USAGE.md

@@ -0,0 +1,246 @@
+A small, dependency-light iSCSI **target** (server) written in TypeScript. It
+exposes exactly one read/write LUN backed by a pluggable byte-range
+`BlockDevice`, and interoperates with the standard Linux **open-iscsi**
+initiator (the same one XCP-ng/XAPI uses to attach an `lvmoiscsi` SR).
+
+### Scope
+
+The target drives login negotiation onto a single, fixed code path:
+
+- single initiator, **`MaxConnections=1`**, **`ErrorRecoveryLevel=0`**
+- no header/data digests (`HeaderDigest=None`, `DataDigest=None`)
+- all writes are R2T-solicited (`InitialR2T=Yes`, `ImmediateData=No`)
+- one LUN (LUN 0)
+
+It implements SendTargets discovery, login (`AuthMethod=None` or one-way
+**CHAP** — see [Authentication](#authentication-chap)), the ~10 SCSI
+commands a Linux initiator issues to attach and use a block device
+(`INQUIRY` + VPD `0x00`/`0x80`/`0x83`, `REPORT LUNS`, `READ CAPACITY 10/16`,
+`READ`/`WRITE 10/16`, `TEST UNIT READY`, `REQUEST SENSE`, `MODE SENSE`,
+`SYNCHRONIZE CACHE`), the full R2T / Data-Out write path, NOP keepalive replies,
+and Logout. Commands may be outstanding concurrently (Data-Out PDUs are routed
+by Initiator Task Tag), so it does not stall under real guest I/O.
+
+The package also ships a userspace **initiator** (`IscsiInitiator`) and an
+`IscsiDisk` adapter that exposes a remote LUN as an `@xen-orchestra/disk-transform`
+`RandomAccessDisk` — see [Initiator](#initiator).
+
+Not implemented (yet): mutual (two-way) CHAP, Task Management (abort/reset),
+target-initiated NOP keepalives, multiple connections/LUNs.
+
+### CLI
+
+The package ships a `vates-iscsi` binary that serves a file as a LUN:
+
+```sh
+> vates-iscsi /srv/lun.img
+> vates-iscsi /srv/lun.img --serial MYSERIAL01 --port 3260
+> vates-iscsi /srv/new.img --size 10G          # create/grow the backing file first
+```
+
+```
+Usage: vates-iscsi <file> [options]
+
+Options:
+  --serial <serial>       LUN serial number (default: derived from the IQN).
+  --size <bytes>          Create/grow the backing file (suffixes K, M, G, T).
+  --iqn <iqn>             Target IQN (default: iqn.2024-01.tech.vates:<file>).
+  --host <host>           Listen address (default: 0.0.0.0).
+  --port <port>           Listen port (default: 3260).
+  --block-size <bytes>    Logical block size (default: 512).
+  -h, --help              Show this help.
+```
+
+### Library
+
+```js
+import { IscsiTarget, FileBlockDevice } from '@vates/iscsi'
+
+// The backing file must already exist and be sized to the LUN capacity,
+// e.g. `fs.truncate('/srv/lun.img', 10 * 1024 ** 3)`.
+const target = new IscsiTarget({
+  iqn: 'iqn.2024-01.tech.vates:lun0',
+  host: '0.0.0.0',
+  port: 3260,
+  lun: new FileBlockDevice({ path: '/srv/lun.img', blockSize: 512 }),
+})
+
+await target.listen()
+// ... target is now discoverable and attachable by open-iscsi ...
+await target.close()
+```
+
+#### Adding a target backend
+
+A "backend" is whatever stores the LUN's bytes. The protocol layer translates
+SCSI `READ`/`WRITE` CDBs (LBA + block count) into byte offsets/lengths against a
+single small interface, so a backend only has to provide flat random access — it
+never sees a PDU. `FileBlockDevice` (a sparse file) is the built-in one; implement
+`BlockDevice` to expose anything else (a raw device, an object store, an
+`@xen-orchestra/disk-transform` `RandomAccessDisk`, …):
+
+```ts
+interface BlockDevice {
+  open?(): Promise<void> // optional, awaited once before serving I/O
+  getSize(): number // total capacity in bytes; MUST be a multiple of getBlockSize()
+  getBlockSize(): number // logical block size, typically 512
+  read(offset: number, length: number): Promise<Buffer> // exactly `length` bytes at byte `offset`
+  write(offset: number, data: Buffer): Promise<void> // write `data.length` bytes at byte `offset`
+  flush(): Promise<void> // SYNCHRONIZE CACHE — persist any buffering
+  close(): Promise<void> // release resources
+}
+```
+
+Contract to respect:
+
+- **`getSize()` must be a multiple of `getBlockSize()`** and stable for the life of
+  the device. `open()` is the place to compute it (e.g. `stat` the file).
+- **`read` must return exactly `length` bytes** — never short. Zero-fill a sparse
+  or past-EOF tail rather than returning fewer bytes; the SCSI layer already
+  bounds `offset + length` to the capacity.
+- `offset` and `length` are always block-aligned (multiples of `getBlockSize()`).
+- `read`/`write` may be **called concurrently** (commands are interleaved), so the
+  backend must be safe under overlapping calls; honour back-pressure and don't
+  buffer unboundedly.
+- Throwing from `read`/`write`/`flush` tears the connection down; fail fast and
+  attach context to the error.
+
+Minimal example — expose a read-only `RandomAccessDisk` (VHD / qcow2 / raw / a
+remote NBD or iSCSI LUN) as a target LUN by mapping byte reads onto block reads:
+
+```js
+import { IscsiTarget } from '@vates/iscsi'
+
+class RandomAccessDiskLun {
+  // `disk` is an initialized @xen-orchestra/disk-transform RandomAccessDisk.
+  constructor(disk) {
+    this.disk = disk
+    this.blockSize = disk.getBlockSize()
+  }
+  getSize() {
+    return this.disk.getVirtualSize()
+  }
+  getBlockSize() {
+    return this.blockSize
+  }
+  async read(offset, length) {
+    const out = Buffer.alloc(length) // pre-zeroed: sparse/holes read as zeros
+    const first = Math.floor(offset / this.blockSize)
+    const last = Math.floor((offset + length - 1) / this.blockSize)
+    for (let index = first; index <= last; index++) {
+      if (!this.disk.hasBlock(index)) {
+        continue // unallocated: leave zeros
+      }
+      const { data } = await this.disk.readBlock(index)
+      const blockStart = index * this.blockSize
+      const from = Math.max(0, offset - blockStart)
+      const to = Math.min(this.blockSize, offset + length - blockStart)
+      data.copy(out, blockStart + from - offset, from, to)
+    }
+    return out
+  }
+  write() {
+    throw new Error('read-only LUN')
+  }
+  async flush() {}
+  async close() {
+    await this.disk.close()
+  }
+}
+
+const target = new IscsiTarget({ iqn: 'iqn.2024-01.tech.vates:disk0', lun: new RandomAccessDiskLun(disk) })
+await target.listen()
+```
+
+For a writable backend, implement `write(offset, data)` symmetrically and make
+`flush()` durable (e.g. `fsync`), as `FileBlockDevice` does.
+
+### Initiator
+
+`IscsiInitiator` is a minimal userspace iSCSI **client**: it connects to one
+target portal, logs in, and reads the LUN. `IscsiDisk` wraps it as an
+`@xen-orchestra/disk-transform` `RandomAccessDisk`, so a remote LUN drops straight
+into the backup/transform pipeline (the iSCSI counterpart of `@vates/nbd-client`'s
+`NbdDisk`). It is **read-only**, single-connection, digests off.
+
+```js
+import { IscsiInitiator, IscsiDisk } from '@vates/iscsi'
+
+// Low-level byte reads:
+const initiator = new IscsiInitiator({
+  host: '10.0.0.10',
+  port: 3260,
+  targetIqn: 'iqn.2024-01.tech.vates:lun0',
+  chap: { user: 'alice', secret: 's3cr3t' }, // optional, see Authentication
+})
+await initiator.connect()
+console.log(initiator.getSize(), initiator.getBlockSize())
+const bytes = await initiator.read(/* offset */ 0, /* length */ 1024 * 1024)
+await initiator.close()
+
+// …or as a RandomAccessDisk (blockSize must be a multiple of the LUN block size):
+const disk = new IscsiDisk(
+  { host: '10.0.0.10', targetIqn: 'iqn.2024-01.tech.vates:lun0' },
+  { blockSize: 2 * 1024 * 1024 }
+)
+await disk.init()
+// disk.getVirtualSize(), disk.getBlockIndexes(), await disk.readBlock(i), …
+await disk.close()
+```
+
+First-cut `IscsiDisk` treats the LUN as fully allocated (every block reported as
+present, like `RawDisk`); a changed-block map (e.g. a Pure "Volume Difference")
+can narrow it later.
+
+### Authentication (CHAP)
+
+The target and initiator support **one-way CHAP** (MD5) in opposite roles; mutual
+(two-way) CHAP is not yet implemented.
+
+**Target as authenticator.** Pass `chap` to require each _data_ session to prove a
+credential; the target challenges the initiator and rejects the login (Login
+Response status-class _Initiator Error_ / _authentication failure_) on a mismatch:
+
+```js
+const target = new IscsiTarget({
+  iqn: 'iqn.2024-01.tech.vates:lun0',
+  lun,
+  chap: { user: 'alice', secret: 's3cr3t' },
+})
+```
+
+This interoperates with the Linux **open-iscsi** initiator (the one XCP-ng uses);
+configure its node record's incoming credential:
+
+```sh
+iscsiadm -m node -T <iqn> -p <portal> -o update -n node.session.auth.authmethod -v CHAP
+iscsiadm -m node -T <iqn> -p <portal> -o update -n node.session.auth.username   -v alice
+iscsiadm -m node -T <iqn> -p <portal> -o update -n node.session.auth.password   -v s3cr3t
+```
+
+CHAP is enforced only on **Normal (data) sessions**; **Discovery** sessions (which
+can only run SendTargets and never reach the LUN) stay unauthenticated, so plain
+`iscsiadm -m discovery` keeps working. open-iscsi requires the secret to be 12–16
+characters.
+
+**Initiator as responder.** Pass `chap` to `IscsiInitiator`/`IscsiDisk` to answer a
+target's challenge (e.g. a Pure array acting as authenticator). If the target
+_requires_ mutual CHAP the login is cleanly rejected (we never challenge back).
+
+### Security
+
+iSCSI has no data-path encryption of its own. CHAP authenticates the login only;
+with no digests, **CDBs and data remain cleartext**. Anyone who can reach an
+unauthenticated port can read/write the LUN, and a CHAP-protected one is still
+exposed to eavesdropping and tampering on the wire. Expose targets only on a
+trusted, isolated storage network, and use **IPsec** (the RFC-specified mechanism)
+or equivalent if confidentiality is required.
+
+### Testing
+
+- `yarn test` — fast unit tests (PDU framing, SCSI encoders/decoders, login
+  negotiation, sequence-number arithmetic).
+- `yarn test-integration` — a self-contained loopback test (an in-process
+  minimal initiator drives discovery, identity, write/read-back, and command
+  interleaving), plus an open-iscsi interop test that **requires root and
+  `iscsiadm`** and skips gracefully otherwise.

@vates/iscsi/.npmignore

@@ -0,0 +1 @@
+../../scripts/npmignore

@vates/iscsi/PROTOCOL.md

@@ -0,0 +1,124 @@
+# Protocol coverage
+
+`@vates/iscsi` implements a deliberately narrow subset of iSCSI (RFC 7143, formerly RFC 3720) and the SCSI
+command set it carries (SPC-3 primary commands, SBC-3 block commands) — enough to serve or consume exactly one
+read/write LUN over a single connection, not a general-purpose iSCSI stack. This is the detailed companion to
+the README's "Scope" section, verified directly against the source (`constants.mts`, `login.mts`,
+`connection.mts`, `types.mts`, `initiator.mts`, `chap.mts`) rather than inferred.
+
+The package has two independent roles with very different maturity:
+
+- **Target** (`IscsiTarget`) — the primary, production-used role (backs `@xen-orchestra/mixins/live-mount`).
+  Handles real-world Linux/XCP-ng initiators robustly: concurrent commands, real write ordering, keepalives,
+  connection recovery.
+- **Initiator** (`IscsiInitiator`) — a minimal, read-only client used to read from a third-party array as a
+  disk source. Built against `IscsiTarget` and standard-tooling targets (`tgt`); interop testing this session
+  found it does **not** complete login against a LIO kernel target (see below) — a real, previously-unknown
+  gap, not yet fixed.
+
+## Session and connection
+
+| Aspect                          | Target                                                                                                                                                                                                                                                                                           | Initiator                    |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
+| Connections per session         | `MaxConnections=1`, enforced                                                                                                                                                                                                                                                                     | opens exactly one            |
+| Session reinstatement           | **no** — no ISID tracking; a new connection always tears down and replaces whatever connection currently exists, rather than RFC 7143's ISID-matched reinstatement (see `index.mts`'s class doc for the reasoning: safe here because the target is ephemeral, single-consumer, and CHAP-guarded) | n/a (single connection)      |
+| Multiple LUNs                   | **no** — exactly one LUN, always LUN 0                                                                                                                                                                                                                                                           | reads are hardcoded to LUN 0 |
+| `ErrorRecoveryLevel`            | `0` only                                                                                                                                                                                                                                                                                         | requests `0`                 |
+| Header/data digests             | `HeaderDigest=None`, `DataDigest=None` — no CRC32C on the wire                                                                                                                                                                                                                                   | same                         |
+| Markers (`IFMarker`/`OFMarker`) | not offered (RFC-deprecated)                                                                                                                                                                                                                                                                     | not offered                  |
+
+## Login / text negotiation
+
+**Target** (`login.mts`) reactively answers whatever the initiator proposes, fixed to:
+`HeaderDigest=None`, `DataDigest=None`, `MaxConnections=1`, `InitialR2T=Yes`, `ImmediateData=No`,
+`ErrorRecoveryLevel=0`, `DataPDUInOrder=Yes`, `DataSequenceInOrder=Yes`, `DefaultTime2Wait=2`,
+`DefaultTime2Retain=0`, `MaxOutstandingR2T=1` — `MaxBurstLength`/`FirstBurstLength` are the only two keys
+actually negotiated down from the initiator's offer (capped at an internal maximum). Both `Normal` and
+`Discovery` session types are supported (`SessionType`), with CHAP skipped for `Discovery` per RFC — text-mode
+negotiation beyond that is limited to `SendTargets` discovery (`#handleText`), not general text negotiation.
+
+**Initiator** (`initiator.mts#operationalLogin`) sends exactly **one** operational-stage login PDU proposing
+its own fixed key set (`HeaderDigest=None`, `DataDigest=None`, `InitialR2T=Yes`, `ImmediateData=No`,
+`ErrorRecoveryLevel=0`, `MaxRecvDataSegmentLength`) with the transit bit (`T=1`) set immediately, and only
+checks whether the reply also has `T=1` — there is no second round to answer a target's own counter-proposed
+keys if it declines transit on the first exchange.
+
+- Works against `tgt` and against this package's own `IscsiTarget` — both transit on the first round.
+- **Does not complete against a LIO kernel target** (`targetcli-fb`): LIO counter-proposes its own operational
+  keys (`MaxBurstLength`, `DefaultTime2Wait`, `DefaultTime2Retain`, `MaxOutstandingR2T`) in the same response
+  and withholds transit until they're answered — confirmed directly via `dmesg`:
+  ```
+  No response for proposed key "MaxBurstLength".
+  iSCSI Login negotiation failed.
+  ```
+  This is a real, previously-unexercised limitation of the initiator's login state machine (single
+  operational round-trip only), not a bug on LIO's side. Worth weighing given the initiator's real intended
+  use — reading from unknown-strictness third-party array software, not `tgt`/this package's own target.
+
+## Authentication (CHAP)
+
+- One-way only (RFC 1994, algorithm MD5 — the only one RFC 7143 defines, so this isn't a partial
+  implementation of a wider set).
+- **Target as authenticator**: when `chap` is configured, every login must present the right `CHAP_N`/`CHAP_R`
+  or the login is rejected (`INITIATOR_ERROR`/`AUTHENTICATION_FAILURE`). Interop-tested against the real
+  `open-iscsi` kernel initiator (both correct-secret and wrong-secret paths).
+- **Initiator as responder**: when `chap` is configured, answers a target's challenge with the same MD5
+  scheme. Never issues its own challenge.
+- **Not supported**: mutual (two-way) CHAP in either role — a target that _requires_ mutual auth will reject
+  the initiator's login, surfaced as a normal login failure rather than attempted.
+
+## SCSI commands
+
+Decoded explicitly (`types.mts#decodeCdb`); anything else maps to `unsupported` → `CHECK CONDITION` /
+`ILLEGAL_REQUEST` / `INVALID COMMAND OPERATION CODE`:
+
+| Command             | Variants                                                         |
+| ------------------- | ---------------------------------------------------------------- |
+| `INQUIRY`           | standard + EVPD (vendor/product/revision/serial from `identity`) |
+| `REPORT LUNS`       |                                                                  |
+| `READ CAPACITY`     | `(10)` and `(16)`                                                |
+| `READ`              | `(10)` and `(16)`                                                |
+| `WRITE`             | `(10)` and `(16)`                                                |
+| `TEST UNIT READY`   |                                                                  |
+| `REQUEST SENSE`     |                                                                  |
+| `MODE SENSE`        | `(6)` and `(10)`                                                 |
+| `SYNCHRONIZE CACHE` | `(10)` and `(16)` — flushes the backing `BlockDevice`            |
+
+**Not implemented**: persistent reservations, VAAI/thin-provisioning primitives (`UNMAP`, `WRITE SAME`, `COMPARE
+AND WRITE`, ...), any vendor-specific commands — anything beyond the ~10 commands a Linux initiator actually
+issues to attach and use a plain block device.
+
+## Data transfer
+
+- **Read**: `Data-In`, concurrent commands dispatched up to `readConcurrency` (default 16) regardless of the
+  advertised command window — bounds how many `lun.read()` calls run at once against the real backend.
+  Residual under/overflow reported against the CDB's requested transfer length.
+- **Write**: always solicited (`InitialR2T=Yes`, `ImmediateData=No`) — every write goes through `R2T` →
+  `Data-Out`, one outstanding R2T at a time (`MaxOutstandingR2T=1`). `Data-Out` PDUs are routed by Initiator
+  Task Tag, so writes/reads for different commands can interleave; within one write, out-of-order or
+  overlapping `Data-Out` segments are rejected outright (`writePath.mts`) rather than silently accepted, to
+  avoid leaking uninitialized staging-buffer memory to the LUN (a real bug this was hardened against — see
+  `VALIDATION.md`).
+- **Not implemented**: unsolicited/immediate data, `MaxOutstandingR2T > 1`.
+
+## Task management, error recovery, keepalives
+
+- **SCSI Task Management** (`ABORT TASK`, `LUN RESET`, etc.) — not implemented; any `SCSI Task Mgmt Request`
+  is rejected (`COMMAND_NOT_SUPPORTED`).
+- **SNACK** (retransmission requests, part of `ErrorRecoveryLevel > 0`) — not implemented; rejected the same
+  way. Consistent with `ErrorRecoveryLevel=0` — nothing should ever need to SNACK.
+- **NOP / keepalives**:
+  - Target replies to an initiator-sent `NOP-Out` ping, but does **not** proactively send its own periodic
+    `NOP-In` probes (no `nop_interval` equivalent) — it relies entirely on the initiator (or TCP-level
+    connection loss) to notice a dead peer.
+  - Initiator answers a target-initiated `NOP-In` ping with `NOP-Out` and keeps its read loop draining for the
+    life of the connection specifically so it never misses one (this was a real, fixed bug — see
+    `VALIDATION.md`, item 5).
+
+## Summary: not implemented
+
+Mutual (two-way) CHAP · SCSI Task Management (abort/reset) · target-initiated NOP-In keepalives · multiple
+connections per session · multiple LUNs · session reinstatement (ISID) · header/data digests · unsolicited
+data / `MaxOutstandingR2T>1` · SNACK/error recovery beyond level 0 · persistent reservations and VAAI-style
+primitives · general text-mode negotiation beyond `SendTargets` · initiator-side multi-round operational login
+negotiation (works against this package's own target and `tgt`; does not against LIO — see above).

@vates/iscsi/README.md

@@ -0,0 +1,279 @@
+<!-- DO NOT EDIT MANUALLY, THIS FILE HAS BEEN GENERATED -->
+
+# @vates/iscsi
+
+[![Package Version](https://badgen.net/npm/v/@vates/iscsi)](https://npmjs.org/package/@vates/iscsi) ![License](https://badgen.net/npm/license/@vates/iscsi) [![PackagePhobia](https://badgen.net/bundlephobia/minzip/@vates/iscsi)](https://bundlephobia.com/result?p=@vates/iscsi) [![Node compatibility](https://badgen.net/npm/node/@vates/iscsi)](https://npmjs.org/package/@vates/iscsi)
+
+> Minimal iSCSI target and initiator: expose or read a single LUN, with one-way CHAP
+
+## Install
+
+Installation of the [npm package](https://npmjs.org/package/@vates/iscsi):
+
+```sh
+npm install --save @vates/iscsi
+```
+
+## Usage
+
+A small, dependency-light iSCSI **target** (server) written in TypeScript. It
+exposes exactly one read/write LUN backed by a pluggable byte-range
+`BlockDevice`, and interoperates with the standard Linux **open-iscsi**
+initiator (the same one XCP-ng/XAPI uses to attach an `lvmoiscsi` SR).
+
+### Scope
+
+The target drives login negotiation onto a single, fixed code path:
+
+- single initiator, **`MaxConnections=1`**, **`ErrorRecoveryLevel=0`**
+- no header/data digests (`HeaderDigest=None`, `DataDigest=None`)
+- all writes are R2T-solicited (`InitialR2T=Yes`, `ImmediateData=No`)
+- one LUN (LUN 0)
+
+It implements SendTargets discovery, login (`AuthMethod=None` or one-way
+**CHAP** — see [Authentication](#authentication-chap)), the ~10 SCSI
+commands a Linux initiator issues to attach and use a block device
+(`INQUIRY` + VPD `0x00`/`0x80`/`0x83`, `REPORT LUNS`, `READ CAPACITY 10/16`,
+`READ`/`WRITE 10/16`, `TEST UNIT READY`, `REQUEST SENSE`, `MODE SENSE`,
+`SYNCHRONIZE CACHE`), the full R2T / Data-Out write path, NOP keepalive replies,
+and Logout. Commands may be outstanding concurrently (Data-Out PDUs are routed
+by Initiator Task Tag), so it does not stall under real guest I/O.
+
+The package also ships a userspace **initiator** (`IscsiInitiator`) and an
+`IscsiDisk` adapter that exposes a remote LUN as an `@xen-orchestra/disk-transform`
+`RandomAccessDisk` — see [Initiator](#initiator).
+
+Not implemented (yet): mutual (two-way) CHAP, Task Management (abort/reset),
+target-initiated NOP keepalives, multiple connections/LUNs.
+
+### CLI
+
+The package ships a `vates-iscsi` binary that serves a file as a LUN:
+
+```sh
+> vates-iscsi /srv/lun.img
+> vates-iscsi /srv/lun.img --serial MYSERIAL01 --port 3260
+> vates-iscsi /srv/new.img --size 10G          # create/grow the backing file first
+```
+
+```
+Usage: vates-iscsi <file> [options]
+
+Options:
+  --serial <serial>       LUN serial number (default: derived from the IQN).
+  --size <bytes>          Create/grow the backing file (suffixes K, M, G, T).
+  --iqn <iqn>             Target IQN (default: iqn.2024-01.tech.vates:<file>).
+  --host <host>           Listen address (default: 0.0.0.0).
+  --port <port>           Listen port (default: 3260).
+  --block-size <bytes>    Logical block size (default: 512).
+  -h, --help              Show this help.
+```
+
+### Library
+
+```js
+import { IscsiTarget, FileBlockDevice } from '@vates/iscsi'
+
+// The backing file must already exist and be sized to the LUN capacity,
+// e.g. `fs.truncate('/srv/lun.img', 10 * 1024 ** 3)`.
+const target = new IscsiTarget({
+  iqn: 'iqn.2024-01.tech.vates:lun0',
+  host: '0.0.0.0',
+  port: 3260,
+  lun: new FileBlockDevice({ path: '/srv/lun.img', blockSize: 512 }),
+})
+
+await target.listen()
+// ... target is now discoverable and attachable by open-iscsi ...
+await target.close()
+```
+
+#### Adding a target backend
+
+A "backend" is whatever stores the LUN's bytes. The protocol layer translates
+SCSI `READ`/`WRITE` CDBs (LBA + block count) into byte offsets/lengths against a
+single small interface, so a backend only has to provide flat random access — it
+never sees a PDU. `FileBlockDevice` (a sparse file) is the built-in one; implement
+`BlockDevice` to expose anything else (a raw device, an object store, an
+`@xen-orchestra/disk-transform` `RandomAccessDisk`, …):
+
+```ts
+interface BlockDevice {
+  open?(): Promise<void> // optional, awaited once before serving I/O
+  getSize(): number // total capacity in bytes; MUST be a multiple of getBlockSize()
+  getBlockSize(): number // logical block size, typically 512
+  read(offset: number, length: number): Promise<Buffer> // exactly `length` bytes at byte `offset`
+  write(offset: number, data: Buffer): Promise<void> // write `data.length` bytes at byte `offset`
+  flush(): Promise<void> // SYNCHRONIZE CACHE — persist any buffering
+  close(): Promise<void> // release resources
+}
+```
+
+Contract to respect:
+
+- **`getSize()` must be a multiple of `getBlockSize()`** and stable for the life of
+  the device. `open()` is the place to compute it (e.g. `stat` the file).
+- **`read` must return exactly `length` bytes** — never short. Zero-fill a sparse
+  or past-EOF tail rather than returning fewer bytes; the SCSI layer already
+  bounds `offset + length` to the capacity.
+- `offset` and `length` are always block-aligned (multiples of `getBlockSize()`).
+- `read`/`write` may be **called concurrently** (commands are interleaved), so the
+  backend must be safe under overlapping calls; honour back-pressure and don't
+  buffer unboundedly.
+- Throwing from `read`/`write`/`flush` tears the connection down; fail fast and
+  attach context to the error.
+
+Minimal example — expose a read-only `RandomAccessDisk` (VHD / qcow2 / raw / a
+remote NBD or iSCSI LUN) as a target LUN by mapping byte reads onto block reads:
+
+```js
+import { IscsiTarget } from '@vates/iscsi'
+
+class RandomAccessDiskLun {
+  // `disk` is an initialized @xen-orchestra/disk-transform RandomAccessDisk.
+  constructor(disk) {
+    this.disk = disk
+    this.blockSize = disk.getBlockSize()
+  }
+  getSize() {
+    return this.disk.getVirtualSize()
+  }
+  getBlockSize() {
+    return this.blockSize
+  }
+  async read(offset, length) {
+    const out = Buffer.alloc(length) // pre-zeroed: sparse/holes read as zeros
+    const first = Math.floor(offset / this.blockSize)
+    const last = Math.floor((offset + length - 1) / this.blockSize)
+    for (let index = first; index <= last; index++) {
+      if (!this.disk.hasBlock(index)) {
+        continue // unallocated: leave zeros
+      }
+      const { data } = await this.disk.readBlock(index)
+      const blockStart = index * this.blockSize
+      const from = Math.max(0, offset - blockStart)
+      const to = Math.min(this.blockSize, offset + length - blockStart)
+      data.copy(out, blockStart + from - offset, from, to)
+    }
+    return out
+  }
+  write() {
+    throw new Error('read-only LUN')
+  }
+  async flush() {}
+  async close() {
+    await this.disk.close()
+  }
+}
+
+const target = new IscsiTarget({ iqn: 'iqn.2024-01.tech.vates:disk0', lun: new RandomAccessDiskLun(disk) })
+await target.listen()
+```
+
+For a writable backend, implement `write(offset, data)` symmetrically and make
+`flush()` durable (e.g. `fsync`), as `FileBlockDevice` does.
+
+### Initiator
+
+`IscsiInitiator` is a minimal userspace iSCSI **client**: it connects to one
+target portal, logs in, and reads the LUN. `IscsiDisk` wraps it as an
+`@xen-orchestra/disk-transform` `RandomAccessDisk`, so a remote LUN drops straight
+into the backup/transform pipeline (the iSCSI counterpart of `@vates/nbd-client`'s
+`NbdDisk`). It is **read-only**, single-connection, digests off.
+
+```js
+import { IscsiInitiator, IscsiDisk } from '@vates/iscsi'
+
+// Low-level byte reads:
+const initiator = new IscsiInitiator({
+  host: '10.0.0.10',
+  port: 3260,
+  targetIqn: 'iqn.2024-01.tech.vates:lun0',
+  chap: { user: 'alice', secret: 's3cr3t' }, // optional, see Authentication
+})
+await initiator.connect()
+console.log(initiator.getSize(), initiator.getBlockSize())
+const bytes = await initiator.read(/* offset */ 0, /* length */ 1024 * 1024)
+await initiator.close()
+
+// …or as a RandomAccessDisk (blockSize must be a multiple of the LUN block size):
+const disk = new IscsiDisk(
+  { host: '10.0.0.10', targetIqn: 'iqn.2024-01.tech.vates:lun0' },
+  { blockSize: 2 * 1024 * 1024 }
+)
+await disk.init()
+// disk.getVirtualSize(), disk.getBlockIndexes(), await disk.readBlock(i), …
+await disk.close()
+```
+
+First-cut `IscsiDisk` treats the LUN as fully allocated (every block reported as
+present, like `RawDisk`); a changed-block map (e.g. a Pure "Volume Difference")
+can narrow it later.
+
+### Authentication (CHAP)
+
+The target and initiator support **one-way CHAP** (MD5) in opposite roles; mutual
+(two-way) CHAP is not yet implemented.
+
+**Target as authenticator.** Pass `chap` to require each _data_ session to prove a
+credential; the target challenges the initiator and rejects the login (Login
+Response status-class _Initiator Error_ / _authentication failure_) on a mismatch:
+
+```js
+const target = new IscsiTarget({
+  iqn: 'iqn.2024-01.tech.vates:lun0',
+  lun,
+  chap: { user: 'alice', secret: 's3cr3t' },
+})
+```
+
+This interoperates with the Linux **open-iscsi** initiator (the one XCP-ng uses);
+configure its node record's incoming credential:
+
+```sh
+iscsiadm -m node -T <iqn> -p <portal> -o update -n node.session.auth.authmethod -v CHAP
+iscsiadm -m node -T <iqn> -p <portal> -o update -n node.session.auth.username   -v alice
+iscsiadm -m node -T <iqn> -p <portal> -o update -n node.session.auth.password   -v s3cr3t
+```
+
+CHAP is enforced only on **Normal (data) sessions**; **Discovery** sessions (which
+can only run SendTargets and never reach the LUN) stay unauthenticated, so plain
+`iscsiadm -m discovery` keeps working. open-iscsi requires the secret to be 12–16
+characters.
+
+**Initiator as responder.** Pass `chap` to `IscsiInitiator`/`IscsiDisk` to answer a
+target's challenge (e.g. a Pure array acting as authenticator). If the target
+_requires_ mutual CHAP the login is cleanly rejected (we never challenge back).
+
+### Security
+
+iSCSI has no data-path encryption of its own. CHAP authenticates the login only;
+with no digests, **CDBs and data remain cleartext**. Anyone who can reach an
+unauthenticated port can read/write the LUN, and a CHAP-protected one is still
+exposed to eavesdropping and tampering on the wire. Expose targets only on a
+trusted, isolated storage network, and use **IPsec** (the RFC-specified mechanism)
+or equivalent if confidentiality is required.
+
+### Testing
+
+- `yarn test` — fast unit tests (PDU framing, SCSI encoders/decoders, login
+  negotiation, sequence-number arithmetic).
+- `yarn test-integration` — a self-contained loopback test (an in-process
+  minimal initiator drives discovery, identity, write/read-back, and command
+  interleaving), plus an open-iscsi interop test that **requires root and
+  `iscsiadm`** and skips gracefully otherwise.
+
+## Contributions
+
+Contributions are _very_ welcomed, either on the documentation or on
+the code.
+
+You may:
+
+- report any [issue](https://github.com/vatesfr/xen-orchestra/issues)
+  you've encountered;
+- fork and create a pull request.
+
+## License
+
+[ISC](https://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr)

@vates/iscsi/VALIDATION.md

@@ -0,0 +1,165 @@
+# Validation notes
+
+Extracted from a longer production-readiness pass covering both this package and the `LiveMount` mixin that
+consumes it; this file keeps only what's specific to `@vates/iscsi` itself — protocol-level correctness,
+concurrency, and interop with standard tooling. Local testing notes covering the LiveMount/XAPI integration,
+VM boot mechanics, and deployment specifics live elsewhere and aren't reproduced here.
+
+## Bugs found and fixed
+
+### In this validation pass
+
+1. **Read-path error isolation** (`scsi.mts`) — `lun.read()` failures were previously uncaught, killing the
+   whole connection for one bad block. Now wrapped in try/catch, reporting `CHECK_CONDITION`/`MEDIUM_ERROR` for
+   that command only, mirroring the write path's existing `#handleDataOut` error handling.
+   - Unit test: `scsi.test.mts` — "reports a failed lun.read() as CHECK CONDITION / MEDIUM ERROR, not an
+     uncaught throw".
+   - Regression test: `loopback.integ.mts`, `describe('READ error isolation', ...)` — a LUN whose `read()`
+     throws for one LBA still returns `CHECK_CONDITION` for that command; the connection stays alive and a
+     different, healthy LBA read afterward still succeeds.
+
+2. **Connection replacement instead of refusal** (`index.mts`) — found via a real end-to-end guest-boot test
+   against an S3-backed backup repository: `IscsiTarget#onConnection` used to permanently _refuse_ any new
+   connection while an existing one was tracked (`MaxConnections=1` enforcement), with no way to tell a
+   genuinely stale/abandoned connection (initiator gave up and reconnected without ever closing the old TCP
+   socket) from a healthy one still in use. Under a slow backend this wedges the mount forever: the host's
+   initiator times out and retries, gets refused, retries again, forever — reproduced live as an 8+ minute
+   guest boot stall, `WARN refusing concurrent connection (MaxConnections=1)` repeating in the log the whole
+   time. Now a new connection always tears down whatever connection currently exists and takes over, rather
+   than being refused. Deliberately not full RFC 7143 session reinstatement (no ISID matching) — chosen as the
+   simpler, sufficient fix for this target's single-consumer, ephemeral, CHAP-guarded design; see the class doc
+   comment in `index.mts` for the reasoning and the more rigorous alternative considered.
+   - Regression test: `loopback.integ.mts`, `describe('connection replacement', ...)` — a second connection is
+     accepted (not refused) while the first is still open, the first's socket gets torn down, and the new
+     connection is fully usable (read + logout succeed).
+   - Re-verified end-to-end after deploying the fix: same S3-backed boot scenario completed successfully
+     (~5 min total, vs ~20-25s for the equivalent local-storage boot — S3 itself is slow, but the mount no
+     longer wedges).
+
+### Independently landed, cross-referenced against this pass's coverage
+
+Five more fixes landed on this branch outside this validation effort. Read in full and checked against what
+had (and hadn't) actually been exercised black-box, since two are severe:
+
+1. **`CachedDiskBlockDevice.mts` — acknowledged writes silently and permanently reverted.** A write fully
+   covering a not-yet-cached block used to skip fetching the source (an "optimization" — the write supplies
+   all the bytes anyway). But if a _read_ to that same block had already triggered an in-flight fetch, that
+   fetch could land **after** the write and silently overwrite it with stale source data — guest gets `GOOD`,
+   data reverts moments later. Fixed by always joining any in-flight fetch before writing. Has a white-box
+   regression test (pauses a fake disk mid-fetch to force the race). This is exactly the class of bug this
+   whole effort was looking for, and its vulnerable path — read+write racing on the same never-touched block —
+   was never actually exercised by this pass's own earlier black-box testing (sequential `dd` and single-job
+   `fio` both avoid same-offset self-overlap by construction), so the "clean" results up to that point were
+   consistent with the bug being present, not proof of its absence. Closed that gap afterward (see below).
+
+2. **`connection.mts`/`writePath.mts` — uninitialized heap memory leaked to the LUN on a malformed Data-Out.**
+   Staging buffer is `Buffer.allocUnsafe`, never zeroed; the old completion check summed received bytes, but
+   `Buffer.copy` silently clamps on out-of-range/overlapping offsets — a malformed/out-of-order Data-Out
+   sequence could reach "totalLength received" with gaps of recycled heap memory that then get written to the
+   LUN and read back by any guest. Real info-disclosure bug, needs a misbehaving/malicious initiator to trigger
+   (a well-behaved one never sends malformed Data-Out). Fixed with strict contiguity validation; extensively
+   tested (`connection.test.mts` +586 lines, `writePath.test.mts` +168 lines, both white-box, covering the
+   malformed-input space directly — not something black-box testing with real tooling can easily reach at all).
+
+3. **`connection.mts` — CmdSN window corrupted by every Data-Out (i.e. every write).** Command-window tracking
+   read bytes 24-27 as CmdSN off every inbound PDU, but those bytes are reserved on Data-Out per RFC 7143
+   §11.7 — every write rewound the advertised window. Benign at normal scale (initiators discard the rewind as
+   stale via serial-number comparison until session CmdSN passes 2³¹) — none of this pass's testing came close
+   to that scale, so nothing here calls prior results into question. Fixed with an opcode allowlist; has its
+   own regression test.
+
+4. **`CachedDiskBlockDevice.hydrate()` — no longer throws/orphans on a concurrent unmount.** `hydrate()` now
+   accepts an `AbortSignal`, stopping at the next block boundary and rejecting cleanly once in-flight blocks
+   settle, rather than the caller having to serialize hydrate against unmount itself (the orchestration half of
+   this fix — not running hydrate inside the same long-lived task as the mount — lives in the LiveMount mixin,
+   outside this package). Tested at the `CachedDiskBlockDevice` level: aborting mid-hydrate keeps everything
+   already cached, rejects rather than silently returning partial success, and a fresh signal that's already
+   aborted refuses to start at all.
+
+5. **`initiator.mts` — went silent between commands, dropped by a target's ping timeout.** `IscsiInitiator`'s
+   read loop used to stop once nothing was outstanding, so during any idle period a target's NOP-In keepalive
+   sat unread — real targets (LIO's `nopin_response_timeout`, 30s by default) drop sessions with unanswered
+   pings, with no reconnect logic to recover. Fixed with a loop that keeps draining for the life of the
+   connection and replies to NOP-In pings (`#pump`/`#replyNop`); added `initiator.integ.mts` (white-box,
+   real loopback). Never exercised by this pass's own black-box testing at all — the whole effort was
+   LiveMount-focused, which only ever uses the _target_ role. Attempting to close that gap surfaced two
+   further, independent findings — see "Initiator interop findings" below.
+
+## Black-box protocol-level testing (standalone target, real tooling)
+
+- **Data integrity under concurrent load**: 30-minute `fio --rw=randrw --bs=4k --iodepth=64 --numjobs=1
+--verify=crc32c` soak against the standalone target over real `iscsiadm` loopback — 0 verify errors, ~16.4k
+  read + ~10.6k write IOPS sustained throughout. (An earlier `numjobs=4` run produced ~116 "bad header"
+  errors; bisected and reproduced identically against plain local file I/O with zero iSCSI involvement —
+  a known fio limitation where independent jobs pointed at the same file race each other's own bookkeeping,
+  not a target bug. `numjobs=1` at higher `iodepth` avoids the false positive while still exercising real
+  queue depth.)
+- **Filesystem round-trip across a full session teardown**: real corpus (2419 files, 53 MB) written, hashed,
+  then a full cold logout/login cycle plus a host-side page-cache drop before re-reading — all 2419 files
+  byte-identical.
+- **Kill the target process mid-write**: `kill -9`'d mid-transfer with a direct-I/O write in flight. The write
+  correctly blocked (not a fast, silent "success") until the session recovered, then completed with the exact
+  intended pattern across the full range — no silent data loss, no torn/partial write at the interruption point.
+- **Real cross-machine network partition** (two separate VMs, not loopback): a mid-transfer `iptables DROP`
+  held for 15s against the target's own port. Compared directly to `tgt` as a baseline over the identical
+  topology — both stalled through the outage and completed with 0 corrupted bytes once restored; no divergent
+  behavior from a mature reference implementation.
+- **Sequential throughput vs `tgt`** (same two-VM link, plain iSCSI, no XAPI/SM in the path): `@vates/iscsi`
+  reached ~70% (write) / ~76% (read) of `tgt`'s numbers — noticeably slower but the same order of magnitude,
+  not a large gap. (A separate, much larger ~10x slowdown measured through the full LiveMount/XAPI/SM stack
+  was isolated to the host's own `iscsi` SM/tapdisk driver by elimination — outside this package.)
+- **Targeted regression testing for bug 1 above**, using a single-job, high-`iodepth`, small-range `fio`
+  pattern (deliberately avoiding the `numjobs>1` false-positive from the first bullet) to force many concurrent
+  operations onto the same underlying cache block without needing multiple uncoordinated processes: clean
+  (0 verify errors) against local storage, against a slow S3-backed remote (a wider fetch-latency window gives
+  a racing write far more time to land mid-fetch — the exact scenario the bug was about), and against an
+  actively-running `hydrate()` sweep overlapping guest I/O on the same disk. All three passed.
+
+## Flagged, not fixed
+
+- **`FileBlockDevice.read()` zero-fills past a short/EOF read instead of throwing** — unlike `LocalBlockDevice`
+  (the actual production cache backend), which throws on the identical condition. Confirmed via grep: only the
+  standalone CLI tool and this package's own tests use `FileBlockDevice` today, so there's no reachable data-
+  loss path in production right now — but it's a public export, so a future feature backing a LUN directly
+  with a file would silently inherit the zero-fill-over-error behavior. This is a design-intent question (is
+  the CLI tool's "sparse tail" leniency deliberate?), not a clear bug — flagging for a decision rather than
+  silently changing it.
+
+## Initiator interop findings (this session)
+
+Bug 5's fix (above) had never been exercised against a real target under real conditions — only the white-box
+`initiator.integ.mts`. Attempting to close that gap with a live idle-period/NOP-In test against two different
+real target implementations surfaced two independent, real findings before the actual keepalive behavior could
+be exercised:
+
+- **`tgt` reserves LUN 0 as a built-in, zero-size "controller" device** on every target, and this is not
+  removable via `tgtadm` (`tgtadm: this logical unit number already exists` / `invalid request` on any attempt
+  to delete or replace it). `IscsiInitiator.connect()`/`read()` are hardcoded to LUN 0 (matching this package's
+  own single-LUN-at-0 target design), so `connect()` fails immediately with `CHECK_CONDITION` against `tgt`
+  regardless of where a real data LUN is added (tried LUN 1). Pure tooling mismatch — `tgt`'s own convention
+  doesn't fit a client that only ever speaks to LUN 0 — not a bug in either side.
+
+- **LIO (`targetcli-fb`/kernel target) does complete login differently, and `IscsiInitiator` can't get through
+  it.** With a real data LUN at LUN 0 (LIO doesn't reserve it), `connect()` still fails — `#operationalLogin`
+  (`initiator.mts`) sends exactly one operational-stage login PDU, requests immediate transit (`T=1`), and only
+  checks the transit bit on the reply; there's no second round to answer a target's own counter-proposal if it
+  declines transit on the first exchange. LIO's kernel target does exactly that: it counter-proposes several of
+  its own operational keys (`MaxBurstLength`, `DefaultTime2Wait`, `DefaultTime2Retain`, `MaxOutstandingR2T`) in
+  the same response and withholds transit until they're answered, confirmed directly in `dmesg`:
+  ```
+  No response for proposed key "MaxBurstLength".
+  No response for proposed key "DefaultTime2Wait".
+  No response for proposed key "DefaultTime2Retain".
+  No response for proposed key "MaxOutstandingR2T".
+  iSCSI Login negotiation failed.
+  ```
+  This works fine against `tgt` and against this package's own `IscsiTarget` (both transit on the first round),
+  so it's never been visible before — but it's a **real, previously-unknown limitation of `IscsiInitiator`'s
+  login state machine**: single operational round-trip only, no handling for a target that insists on its own
+  multi-round negotiation before agreeing to transit. Worth knowing given the initiator role's real intended
+  use (reading from a third-party storage array as an initiator) targets unknown-strictness third-party target
+  software, not `tgt` or this package's own target.
+
+Given both blockers are about _login/LUN setup_, not the keepalive mechanism itself, the actual idle-period/
+NOP-In behavior could not be exercised live this session. The white-box `initiator.integ.mts` coverage for
+bug 5 stands as the only current test of that specific fix.

@vates/iscsi/eslint.config.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+import eslint from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(eslint.configs.recommended, tseslint.configs.recommended)

@vates/iscsi/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@vates/iscsi",
+  "version": "0.2.0",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "bin": {
+    "vates-iscsi": "dist/cli.mjs"
+  },
+  "license": "ISC",
+  "private": false,
+  "type": "module",
+  "description": "Minimal iSCSI target and initiator: expose or read a single LUN, with one-way CHAP",
+  "keywords": [
+    "iscsi",
+    "target",
+    "initiator",
+    "chap",
+    "scsi",
+    "lun",
+    "block",
+    "storage"
+  ],
+  "dependencies": {
+    "@vates/async-each": "^1.0.3",
+    "@vates/read-chunk": "^1.2.1",
+    "@xen-orchestra/disk-transform": "^1.3.0",
+    "@xen-orchestra/log": "^0.7.2",
+    "promise-toolbox": "^0.21.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.19.0",
+    "@types/node": "^22.0",
+    "rimraf": "^6.0.1",
+    "typescript": "~5.6",
+    "typescript-eslint": "^8.61.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist/",
+    "dev": "tsc --watch",
+    "postversion": "npm publish --access public",
+    "prebuild": "rimraf dist/",
+    "predev": "yarn run prebuild",
+    "test": "tsc && node --test \"dist/**/*.test.mjs\"",
+    "test-integration": "tsc && node --test \"dist/**/*.integ.mjs\""
+  },
+  "homepage": "https://github.com/vatesfr/xen-orchestra/tree/master/@vates/iscsi",
+  "bugs": "https://github.com/vatesfr/xen-orchestra/issues",
+  "repository": {
+    "directory": "@vates/iscsi",
+    "type": "git",
+    "url": "https://github.com/vatesfr/xen-orchestra.git"
+  },
+  "author": {
+    "name": "Vates SAS",
+    "url": "https://vates.fr"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

@vates/iscsi/src/CachedDiskBlockDevice.mts

@@ -0,0 +1,321 @@
+import { asyncEach } from '@vates/async-each'
+import { createLogger, type Logger } from '@xen-orchestra/log'
+import type { ProgressHandler, RandomAccessDisk } from '@xen-orchestra/disk-transform'
+
+import type { BlockDevice } from './backend.mjs'
+
+const log: Logger = createLogger('vates:iscsi:cached-disk-block-device')
+
+const DEFAULT_BLOCK_SIZE = 512
+const DEFAULT_HYDRATE_CONCURRENCY = 8
+
+export interface CachedDiskBlockDeviceOptions {
+  /**
+   * Source disk, already `init()`ed by the caller. Only ever read from, one
+   * whole block at a time.
+   */
+  readonly disk: RandomAccessDisk
+  /**
+   * Writable store holding what has been read from {@link disk} so far, already
+   * `open()`ed and at least as large as the disk's virtual size.
+   */
+  readonly cache: BlockDevice
+  /**
+   * Logical block size advertised to initiators, in bytes. Defaults to 512.
+   * The disk's own block size must be a multiple of it.
+   */
+  readonly blockSize?: number
+  /**
+   * Notified with the materialized fraction (0..1) every time a new block is
+   * cached — on demand or through {@link hydrate} — and via `done()` once
+   * every block has been. Reused from the `disk-transform` export/import
+   * pipelines rather than inventing a new shape.
+   */
+  readonly progressHandler?: ProgressHandler
+  /**
+   * A previously-persisted bitmap to resume from, one byte per block (see
+   * {@link CachedDiskBlockDevice}'s class doc). Its length must match the
+   * block count computed from `disk`/`blockSize`; a mismatch (e.g. the disk
+   * was resized since it was saved) is treated as stale and discarded rather
+   * than rejected, so a corrupt/outdated resume file never blocks a mount.
+   */
+  readonly initialBitmap?: Buffer
+  /**
+   * Notified with a block's index the moment it is newly cached — narrower
+   * than `progressHandler`, which only carries an aggregate fraction and
+   * cannot say *which* block just landed. Meant for persisting the bitmap
+   * one byte at a time; best-effort like `progressHandler`, a failure here
+   * must never break block materialization.
+   */
+  readonly onBlockCached?: (index: number) => void
+}
+
+/**
+ * A read-write {@link BlockDevice} over a {@link RandomAccessDisk}, backed by
+ * a local writable store: each source block is materialized into the store
+ * the first time it's needed, tracked by a bitmap so repeat access never goes
+ * back to the source. Call {@link hydrate} to force the whole disk in upfront.
+ *
+ * The bitmap is one byte per block, not one bit: a caller that persists it
+ * incrementally (see `onBlockCached`) writes one block's byte at a time, and
+ * every block's offset must be independent of every other's for concurrent
+ * writes to be safe. A real bit-packed bitmap fails that: several blocks'
+ * bits sharing one byte would need a read-modify-write of that byte, which
+ * two blocks completing concurrently could race on and lose an update. One
+ * byte per block costs a little more memory (negligible in absolute terms —
+ * a few hundred KB even for a huge disk) and buys that independence for free.
+ *
+ * Blocks the source doesn't have are marked present without being written —
+ * relies on the store reading as zero where nothing was ever written.
+ *
+ * Writes land in the store only; the source is never written to, so the
+ * mount diverges from it as soon as anything writes.
+ */
+export class CachedDiskBlockDevice implements BlockDevice {
+  readonly #disk: RandomAccessDisk
+  readonly #cache: BlockDevice
+  readonly #blockSize: number
+  readonly #progressHandler?: ProgressHandler
+  readonly #onBlockCached?: (index: number) => void
+  readonly #initialBitmap?: Buffer
+
+  // one byte per source block, 0 or 1, set once the block is in the cache
+  #bitmap: Buffer = Buffer.alloc(0)
+  #blockCount = 0
+  #cachedCount = 0
+  // source blocks being materialized right now, so concurrent reads of
+  // overlapping ranges fetch each block once
+  readonly #inFlight: Map<number, Promise<void>> = new Map()
+  #diskBlockSize?: number
+  #size?: number
+
+  constructor({
+    disk,
+    cache,
+    blockSize = DEFAULT_BLOCK_SIZE,
+    progressHandler,
+    initialBitmap,
+    onBlockCached,
+  }: CachedDiskBlockDeviceOptions) {
+    if (!Number.isInteger(blockSize) || blockSize <= 0) {
+      throw new Error(`blockSize must be a positive integer, got ${blockSize}`)
+    }
+    this.#disk = disk
+    this.#cache = cache
+    this.#blockSize = blockSize
+    this.#progressHandler = progressHandler
+    this.#initialBitmap = initialBitmap
+    this.#onBlockCached = onBlockCached
+  }
+
+  /** Read the source geometry and allocate (or resume) the bitmap. */
+  async open(): Promise<void> {
+    const blockSize = this.#blockSize
+    const diskBlockSize = this.#disk.getBlockSize()
+    if (diskBlockSize % blockSize !== 0) {
+      throw new Error(`disk block size (${diskBlockSize}) is not a multiple of the LUN block size (${blockSize})`)
+    }
+    const size = this.#disk.getVirtualSize()
+    if (size <= 0 || size % blockSize !== 0) {
+      throw new Error(`disk virtual size (${size}) is not a positive multiple of the LUN block size (${blockSize})`)
+    }
+    if (this.#cache.getSize() < size) {
+      throw new Error(`cache (${this.#cache.getSize()} bytes) is smaller than the disk (${size} bytes)`)
+    }
+
+    this.#diskBlockSize = diskBlockSize
+    this.#size = size
+    this.#blockCount = Math.ceil(size / diskBlockSize)
+
+    const initialBitmap = this.#initialBitmap
+    if (initialBitmap !== undefined && initialBitmap.length === this.#blockCount) {
+      this.#bitmap = initialBitmap
+      let cachedCount = 0
+      for (const byte of initialBitmap) {
+        if (byte !== 0) {
+          cachedCount++
+        }
+      }
+      this.#cachedCount = cachedCount
+    } else {
+      if (initialBitmap !== undefined) {
+        log.warn('discarding stale initial bitmap (block count mismatch)', {
+          gotLength: initialBitmap.length,
+          expectedLength: this.#blockCount,
+        })
+      }
+      this.#bitmap = Buffer.alloc(this.#blockCount)
+    }
+    log.debug('opened', {
+      size,
+      blockSize,
+      diskBlockSize,
+      blockCount: this.#blockCount,
+      resumedBlocks: this.#cachedCount,
+    })
+  }
+
+  getSize(): number {
+    const size = this.#size
+    if (size === undefined) {
+      throw new Error('CachedDiskBlockDevice.open() must be called before I/O')
+    }
+    return size
+  }
+
+  getBlockSize(): number {
+    return this.#blockSize
+  }
+
+  /** How much of the source has been materialized into the cache. */
+  getMaterialized(): { blocks: number; total: number } {
+    return { blocks: this.#cachedCount, total: this.#blockCount }
+  }
+
+  /**
+   * Force every block into the cache — including holes, so `getMaterialized()`
+   * reaches `total` once done, matching what a full sequential read would
+   * naturally mark. Already-materialized blocks are skipped, so this resumes
+   * rather than redoes whatever on-demand reads (or a previous, interrupted
+   * hydration) already did.
+   *
+   * Hydrating a large disk takes hours, so it must be interruptible: `signal`
+   * stops it at the next block boundary, rejecting once the blocks already in
+   * flight settle. Nothing is rolled back — every block cached so far stays
+   * cached, and because this call resumes, aborting and calling again later
+   * picks up where it stopped rather than starting over.
+   */
+  async hydrate({
+    concurrency = DEFAULT_HYDRATE_CONCURRENCY,
+    signal,
+  }: { concurrency?: number; signal?: AbortSignal } = {}): Promise<void> {
+    signal?.throwIfAborted()
+    const blockCount = this.#blockCount
+    await asyncEach(
+      (function* allBlockIndexes() {
+        for (let index = 0; index < blockCount; index++) {
+          yield index
+        }
+      })(),
+      index => this.#ensureBlock(index),
+      { concurrency, signal }
+    )
+  }
+
+  #isCached(index: number): boolean {
+    return this.#bitmap[index] !== 0
+  }
+
+  #setCached(index: number): void {
+    if (!this.#isCached(index)) {
+      this.#bitmap[index] = 1
+      this.#cachedCount++
+      this.#reportProgress()
+      // best-effort, same contract as #reportProgress: a synchronous throw
+      // here must never break block materialization. Any async failure (e.g.
+      // the persisted-bitmap write itself) is the callback's own job to catch.
+      try {
+        this.#onBlockCached?.(index)
+      } catch (error) {
+        log.warn('onBlockCached failed', { error, index })
+      }
+    }
+  }
+
+  // best-effort: a failure here (sync or async) must never break block
+  // materialization. Wrapping the body in an `async` function, rather than a
+  // plain try/catch, is what makes a *synchronous* throw from the handler
+  // land in the same `.catch()` as an asynchronous rejection.
+  #reportProgress(): void {
+    const handler = this.#progressHandler
+    if (handler === undefined) {
+      return
+    }
+    const fraction = this.#cachedCount / this.#blockCount
+    ;(async () => {
+      await handler.setProgress(fraction)
+      // every block is in the cache: nothing more will ever be reported
+      if (fraction === 1) {
+        await handler.done()
+      }
+    })().catch(error => log.warn('progress handler failed', { error }))
+  }
+
+  /**
+   * Copy one source block into the cache, unless it is already there. Concurrent
+   * calls for the same block share a single fetch.
+   */
+  #ensureBlock(index: number): Promise<void> {
+    if (this.#isCached(index)) {
+      return Promise.resolve()
+    }
+    let pending = this.#inFlight.get(index)
+    if (pending === undefined) {
+      // the entry goes away whether the fetch succeeded or not, so a failed
+      // block is retried later instead of being remembered as broken
+      pending = this.#fetchBlock(index).finally(() => this.#inFlight.delete(index))
+      this.#inFlight.set(index, pending)
+    }
+    return pending
+  }
+
+  async #fetchBlock(index: number): Promise<void> {
+    const diskBlockSize = this.#diskBlockSize as number
+    if (this.#disk.hasBlock(index)) {
+      const offset = index * diskBlockSize
+      const { data } = await this.#disk.readBlock(index)
+      // a source block is always full-size: the last one may run past the end of
+      // the disk, and the cache must not be written beyond it
+      const length = Math.min(diskBlockSize, this.getSize() - offset)
+      await this.#cache.write(offset, length < data.length ? data.subarray(0, length) : data)
+    }
+    // a block the source does not have stays as the cache has it, which is
+    // zeroes as long as nothing has written there
+    this.#setCached(index)
+  }
+
+  #checkRange(offset: number, length: number): void {
+    const size = this.getSize()
+    if (offset < 0 || length < 0 || offset + length > size) {
+      throw new Error(`access of ${length} bytes at ${offset} is out of range (size ${size})`)
+    }
+  }
+
+  async read(offset: number, length: number): Promise<Buffer> {
+    this.#checkRange(offset, length)
+    if (length === 0) {
+      return Buffer.alloc(0)
+    }
+    const diskBlockSize = this.#diskBlockSize as number
+    const last = Math.floor((offset + length - 1) / diskBlockSize)
+    for (let index = Math.floor(offset / diskBlockSize); index <= last; index++) {
+      await this.#ensureBlock(index)
+    }
+    return this.#cache.read(offset, length)
+  }
+
+  async write(offset: number, data: Buffer): Promise<void> {
+    this.#checkRange(offset, data.length)
+    if (data.length === 0) {
+      return
+    }
+    // every covered block must be materialized first, even the ones this write
+    // covers entirely: skipping the fetch would let an already in-flight one
+    // land *after* the payload and overwrite it with the source's bytes.
+    // (optimization left out on purpose — it has to join the in-flight fetch)
+    await this.read(offset, data.length)
+    await this.#cache.write(offset, data)
+  }
+
+  async flush(): Promise<void> {
+    await this.#cache.flush()
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.#cache.close()
+    } finally {
+      await this.#disk.close()
+    }
+  }
+}

@vates/iscsi/src/CachedDiskBlockDevice.test.mts

@@ -0,0 +1,605 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { RandomAccessDisk, type DiskBlock, type ProgressHandler } from '@xen-orchestra/disk-transform'
+
+import { CachedDiskBlockDevice } from './CachedDiskBlockDevice.mjs'
+import type { BlockDevice } from './backend.mjs'
+
+const DISK_BLOCK_SIZE = 4096
+const BLOCK_COUNT = 4
+const DISK_SIZE = BLOCK_COUNT * DISK_BLOCK_SIZE
+
+const bytePattern = (i: number) => (i * 31 + 11) & 0xff
+
+/** Sparse source: only blocks 0 and 2 exist, like a differencing chain. */
+class StubDisk extends RandomAccessDisk {
+  readBlockCalls: Array<number> = []
+  closed = false
+  /** set to hold every fetch open until it resolves */
+  pause?: Promise<void>
+
+  constructor(readonly allocated: Set<number> = new Set([0, 2])) {
+    super()
+  }
+
+  getBlockSize(): number {
+    return DISK_BLOCK_SIZE
+  }
+  getVirtualSize(): number {
+    return DISK_SIZE
+  }
+  isDifferencing(): boolean {
+    return false
+  }
+  getBlockIndexes(): Array<number> {
+    return [...this.allocated]
+  }
+  hasBlock(index: number): boolean {
+    return this.allocated.has(index)
+  }
+  async init(): Promise<void> {}
+  async close(): Promise<void> {
+    this.closed = true
+  }
+  async readBlock(index: number): Promise<DiskBlock> {
+    if (!this.allocated.has(index)) {
+      throw new Error(`Block ${index} not found in chain`)
+    }
+    this.readBlockCalls.push(index)
+    if (this.pause !== undefined) {
+      await this.pause
+    }
+    const data = Buffer.alloc(DISK_BLOCK_SIZE)
+    for (let i = 0; i < data.length; i++) {
+      data[i] = bytePattern(index * DISK_BLOCK_SIZE + i)
+    }
+    return { index, data }
+  }
+}
+
+/** In-memory stand-in for the local VDI. */
+class StubCache implements BlockDevice {
+  readonly content: Buffer
+  writes: Array<{ offset: number; length: number }> = []
+  closed = false
+  flushed = 0
+  failNextWrite = false
+
+  constructor(size = DISK_SIZE) {
+    this.content = Buffer.alloc(size)
+  }
+
+  getSize(): number {
+    return this.content.length
+  }
+  getBlockSize(): number {
+    return 512
+  }
+  async read(offset: number, length: number): Promise<Buffer> {
+    return Buffer.from(this.content.subarray(offset, offset + length))
+  }
+  async write(offset: number, data: Buffer): Promise<void> {
+    if (this.failNextWrite) {
+      this.failNextWrite = false
+      throw new Error('cache write failed')
+    }
+    this.writes.push({ offset, length: data.length })
+    data.copy(this.content, offset)
+  }
+  async flush(): Promise<void> {
+    this.flushed++
+  }
+  async close(): Promise<void> {
+    this.closed = true
+  }
+}
+
+const expectedAt = (offset: number, length: number, allocated: Set<number>): Buffer => {
+  const expected = Buffer.alloc(length)
+  for (let i = 0; i < length; i++) {
+    const absolute = offset + i
+    if (allocated.has(Math.floor(absolute / DISK_BLOCK_SIZE))) {
+      expected[i] = bytePattern(absolute)
+    }
+  }
+  return expected
+}
+
+const make = async (allocated?: Set<number>, cacheSize?: number) => {
+  const disk = new StubDisk(allocated)
+  const cache = new StubCache(cacheSize)
+  const device = new CachedDiskBlockDevice({ disk, cache })
+  await device.open()
+  return { cache, device, disk }
+}
+
+describe('open', () => {
+  it('exposes the disk capacity and a fully cold bitmap', async () => {
+    const { device } = await make()
+    assert.equal(device.getSize(), DISK_SIZE)
+    assert.equal(device.getBlockSize(), 512)
+    assert.deepEqual(device.getMaterialized(), { blocks: 0, total: BLOCK_COUNT })
+  })
+
+  it('refuses a cache smaller than the disk', async () => {
+    const device = new CachedDiskBlockDevice({ disk: new StubDisk(), cache: new StubCache(DISK_SIZE - 512) })
+    await assert.rejects(device.open(), /smaller than the disk/)
+  })
+
+  it('resumes from an initial bitmap of the right length', async () => {
+    // all blocks allocated, so the not-yet-cached one below is a real fetch,
+    // not a hole (which would never call readBlock regardless of the bitmap)
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const initialBitmap = Buffer.alloc(BLOCK_COUNT)
+    initialBitmap[0] = 1
+    initialBitmap[2] = 1
+    const device = new CachedDiskBlockDevice({ disk, cache, initialBitmap })
+    await device.open()
+
+    assert.deepEqual(device.getMaterialized(), { blocks: 2, total: BLOCK_COUNT })
+    // already marked cached: served from the (empty) cache store, source untouched
+    assert.deepEqual(await device.read(0, 512), Buffer.alloc(512))
+    assert.deepEqual(disk.readBlockCalls, [])
+    // not marked cached: still fetched from the source as usual
+    assert.deepEqual(await device.read(DISK_BLOCK_SIZE, 512), expectedAt(DISK_BLOCK_SIZE, 512, disk.allocated))
+    assert.deepEqual(disk.readBlockCalls, [1])
+  })
+
+  it('discards an initial bitmap of the wrong length and starts cold', async () => {
+    const disk = new StubDisk()
+    const cache = new StubCache()
+    const device = new CachedDiskBlockDevice({ disk, cache, initialBitmap: Buffer.alloc(BLOCK_COUNT - 1, 1) })
+    await device.open()
+
+    assert.deepEqual(device.getMaterialized(), { blocks: 0, total: BLOCK_COUNT })
+    assert.deepEqual(await device.read(0, 512), expectedAt(0, 512, disk.allocated))
+    assert.deepEqual(disk.readBlockCalls, [0])
+  })
+})
+
+describe('read', () => {
+  it('materializes a block on first read and serves later ones from the cache', async () => {
+    const { device, disk, cache } = await make()
+
+    assert.deepEqual(await device.read(0, 512), expectedAt(0, 512, disk.allocated))
+    assert.deepEqual(disk.readBlockCalls, [0])
+    // the whole source block was written, not just the part that was read
+    assert.deepEqual(cache.writes, [{ offset: 0, length: DISK_BLOCK_SIZE }])
+    assert.deepEqual(device.getMaterialized(), { blocks: 1, total: BLOCK_COUNT })
+
+    // a second read of a different part of the same block does not go back
+    assert.deepEqual(await device.read(1024, 512), expectedAt(1024, 512, disk.allocated))
+    assert.deepEqual(disk.readBlockCalls, [0])
+    assert.equal(cache.writes.length, 1)
+  })
+
+  it('marks a hole as present without writing it', async () => {
+    const { device, disk, cache } = await make()
+
+    assert.deepEqual(await device.read(DISK_BLOCK_SIZE, 512), Buffer.alloc(512))
+    assert.deepEqual(disk.readBlockCalls, [])
+    assert.deepEqual(cache.writes, [])
+    assert.deepEqual(device.getMaterialized(), { blocks: 1, total: BLOCK_COUNT })
+  })
+
+  it('stitches a range spanning a present and a missing block', async () => {
+    const { device, disk } = await make()
+    const offset = DISK_BLOCK_SIZE - 512
+    const length = DISK_BLOCK_SIZE + 1024
+
+    assert.deepEqual(await device.read(offset, length), expectedAt(offset, length, disk.allocated))
+    assert.deepEqual(disk.readBlockCalls, [0, 2])
+  })
+
+  it('fetches a block once for concurrent overlapping reads', async () => {
+    const { device, disk } = await make()
+    // hold the fetch open until both reads are in flight
+    let release = () => {}
+    disk.pause = new Promise<void>(resolve => {
+      release = resolve
+    })
+
+    const first = device.read(0, 1024)
+    const second = device.read(512, 1024)
+    await new Promise(resolve => setImmediate(resolve))
+    release()
+
+    assert.deepEqual(await first, expectedAt(0, 1024, disk.allocated))
+    assert.deepEqual(await second, expectedAt(512, 1024, disk.allocated))
+    assert.deepEqual(disk.readBlockCalls, [0])
+  })
+
+  it('rejects a read past the end of the disk', async () => {
+    const { device } = await make()
+    await assert.rejects(device.read(DISK_SIZE - 256, 512), /out of range/)
+  })
+
+  it('clamps the tail block to the disk size', async () => {
+    // 3 blocks + half a block, so the last source block runs past the end
+    class ShortDisk extends StubDisk {
+      getVirtualSize(): number {
+        return 3 * DISK_BLOCK_SIZE + 2048
+      }
+    }
+    const disk = new ShortDisk(new Set([3]))
+    const cache = new StubCache(3 * DISK_BLOCK_SIZE + 2048)
+    const device = new CachedDiskBlockDevice({ disk, cache })
+    await device.open()
+
+    await device.read(3 * DISK_BLOCK_SIZE, 2048)
+    assert.deepEqual(cache.writes, [{ offset: 3 * DISK_BLOCK_SIZE, length: 2048 }])
+  })
+})
+
+describe('write', () => {
+  it('lands in the cache and is readable back, without touching the source', async () => {
+    const { device, cache, disk } = await make()
+    const payload = Buffer.alloc(512, 0xee)
+
+    await device.write(0, payload)
+
+    assert.deepEqual(await device.read(0, 512), payload)
+    // the block was materialized first, since the write covers only part of it
+    assert.deepEqual(disk.readBlockCalls, [0])
+    // ... and the bytes after the write are still the source's
+    assert.deepEqual(await device.read(512, 512), expectedAt(512, 512, disk.allocated))
+    assert.equal(cache.closed, false)
+  })
+
+  it('materializes the block even when the write covers it entirely', async () => {
+    const { device, disk } = await make()
+
+    await device.write(0, Buffer.alloc(DISK_BLOCK_SIZE, 0xee))
+
+    // the fetch cannot be skipped: see the race covered by the next test
+    assert.deepEqual(disk.readBlockCalls, [0])
+    assert.deepEqual(device.getMaterialized(), { blocks: 1, total: BLOCK_COUNT })
+  })
+
+  it('is not overwritten by a fetch already in flight when it lands', async () => {
+    const { device, disk } = await make()
+    // hold block 0's fetch open, so the write lands while it is in flight
+    let release = () => {}
+    disk.pause = new Promise<void>(resolve => {
+      release = resolve
+    })
+
+    const reading = device.read(0, 512)
+    await new Promise(resolve => setImmediate(resolve))
+
+    const payload = Buffer.alloc(DISK_BLOCK_SIZE, 0xee)
+    const writing = device.write(0, payload)
+    await new Promise(resolve => setImmediate(resolve))
+    release()
+
+    await reading
+    await writing
+
+    // the source block was fetched once, and its bytes did not come back on top
+    assert.deepEqual(disk.readBlockCalls, [0])
+    assert.deepEqual(await device.read(0, DISK_BLOCK_SIZE), payload)
+  })
+})
+
+describe('hydrate', () => {
+  it('materializes every block the source has, holes included', async () => {
+    const { device, disk, cache } = await make()
+
+    await device.hydrate()
+
+    assert.deepEqual(device.getMaterialized(), { blocks: BLOCK_COUNT, total: BLOCK_COUNT })
+    // only the allocated ones were actually fetched...
+    assert.deepEqual([...disk.readBlockCalls].sort(), [0, 2])
+    // ...and the whole disk now reads correctly straight from the cache
+    assert.deepEqual(await cache.read(0, DISK_SIZE), expectedAt(0, DISK_SIZE, disk.allocated))
+  })
+
+  it('skips blocks already materialized by an earlier read', async () => {
+    const { device, disk } = await make()
+    await device.read(0, 512)
+    assert.deepEqual(disk.readBlockCalls, [0])
+
+    await device.hydrate()
+
+    // block 0 was not fetched a second time
+    assert.deepEqual(disk.readBlockCalls, [0, 2])
+    assert.deepEqual(device.getMaterialized(), { blocks: BLOCK_COUNT, total: BLOCK_COUNT })
+  })
+
+  it('is a no-op once fully materialized', async () => {
+    const { device, disk } = await make()
+    await device.hydrate()
+    disk.readBlockCalls.length = 0
+
+    await device.hydrate()
+
+    assert.deepEqual(disk.readBlockCalls, [])
+  })
+
+  it('stops on an aborted signal, keeping what it already cached', async () => {
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const device = new CachedDiskBlockDevice({ disk, cache })
+    await device.open()
+
+    // every block but the first parks, so the hydration is still mid-flight
+    // when it is aborted
+    let release = () => {}
+    const parked = new Promise<void>(resolve => {
+      release = resolve
+    })
+    disk.readBlock = async index => {
+      if (index > 0) {
+        await parked
+      }
+      return { index, data: Buffer.alloc(DISK_BLOCK_SIZE, index) }
+    }
+    const controller = new AbortController()
+
+    const hydrating = device.hydrate({ concurrency: 1, signal: controller.signal })
+    for (let turn = 0; turn < 20 && device.getMaterialized().blocks === 0; turn++) {
+      await new Promise(resolve => setImmediate(resolve))
+    }
+    assert.deepEqual(device.getMaterialized(), { blocks: 1, total: BLOCK_COUNT })
+
+    controller.abort()
+
+    // aborting is a failure, not a silent partial success
+    await assert.rejects(hydrating)
+    // and the block already cached stays cached, so a later hydration resumes
+    assert.deepEqual(device.getMaterialized(), { blocks: 1, total: BLOCK_COUNT })
+    release() // let the parked fetch finish rather than leaving it dangling
+  })
+
+  it('refuses to start on an already-aborted signal', async () => {
+    const { device, disk } = await make()
+    const controller = new AbortController()
+    controller.abort()
+
+    await assert.rejects(device.hydrate({ signal: controller.signal }))
+
+    assert.deepEqual(disk.readBlockCalls, [])
+    assert.deepEqual(device.getMaterialized(), { blocks: 0, total: BLOCK_COUNT })
+  })
+
+  it('respects the concurrency limit', async () => {
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const device = new CachedDiskBlockDevice({ disk, cache })
+    await device.open()
+
+    let inFlight = 0
+    let maxInFlight = 0
+    const releases: Array<() => void> = []
+    disk.readBlock = async index => {
+      inFlight++
+      maxInFlight = Math.max(maxInFlight, inFlight)
+      await new Promise<void>(resolve => releases.push(resolve))
+      inFlight--
+      return { index, data: Buffer.alloc(DISK_BLOCK_SIZE) }
+    }
+
+    const hydrating = device.hydrate({ concurrency: 2 })
+    // let the first batch start
+    await new Promise(resolve => setImmediate(resolve))
+    assert.equal(maxInFlight, 2)
+    while (releases.length > 0) {
+      releases.shift()!()
+      await new Promise(resolve => setImmediate(resolve))
+    }
+    await hydrating
+
+    assert.equal(maxInFlight, 2)
+  })
+})
+
+describe('progress handler', () => {
+  class StubProgressHandler implements ProgressHandler {
+    calls: Array<number> = []
+    doneCalls = 0
+    throwSync = false
+    rejectAsync = false
+    async setProgress(fraction: number): Promise<void> {
+      this.calls.push(fraction)
+      if (this.throwSync) {
+        throw new Error('sync failure')
+      }
+      if (this.rejectAsync) {
+        throw new Error('async failure')
+      }
+    }
+    done(): void {
+      this.doneCalls++
+    }
+  }
+
+  it('reports the materialized fraction as blocks are read, once each', async () => {
+    const disk = new StubDisk()
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    await device.read(0, 512)
+    // let the fire-and-forget notification run
+    await new Promise(resolve => setImmediate(resolve))
+    assert.deepEqual(progressHandler.calls, [1 / BLOCK_COUNT])
+
+    // a hole is a materialization too, just with nothing to write
+    await device.read(DISK_BLOCK_SIZE, 512)
+    await new Promise(resolve => setImmediate(resolve))
+    assert.deepEqual(progressHandler.calls, [1 / BLOCK_COUNT, 2 / BLOCK_COUNT])
+
+    // re-reading an already materialized block reports nothing new
+    await device.read(0, 512)
+    await new Promise(resolve => setImmediate(resolve))
+    assert.deepEqual(progressHandler.calls, [1 / BLOCK_COUNT, 2 / BLOCK_COUNT])
+  })
+
+  it('reports a fully-covered write the same way as a read', async () => {
+    const disk = new StubDisk()
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    await device.write(0, Buffer.alloc(DISK_BLOCK_SIZE, 0xee))
+    await new Promise(resolve => setImmediate(resolve))
+
+    assert.deepEqual(progressHandler.calls, [1 / BLOCK_COUNT])
+  })
+
+  it('does not let a synchronously throwing handler break the read', async () => {
+    const disk = new StubDisk()
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    progressHandler.throwSync = true
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    assert.deepEqual(await device.read(0, 512), expectedAt(0, 512, disk.allocated))
+    assert.deepEqual(device.getMaterialized(), { blocks: 1, total: BLOCK_COUNT })
+  })
+
+  it('does not let a rejecting handler surface as an unhandled rejection', async () => {
+    const disk = new StubDisk()
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    progressHandler.rejectAsync = true
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    assert.deepEqual(await device.read(0, 512), expectedAt(0, 512, disk.allocated))
+    // give the rejected promise's `.catch` a turn to run before the test ends
+    await new Promise(resolve => setImmediate(resolve))
+  })
+
+  it('calls done() once every block is cached, via hydrate', async () => {
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    await device.hydrate()
+    await new Promise(resolve => setImmediate(resolve))
+
+    assert.deepEqual(progressHandler.calls, [0.25, 0.5, 0.75, 1])
+    assert.equal(progressHandler.doneCalls, 1)
+  })
+
+  it('calls done() once every block is cached, via on-demand reads alone', async () => {
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    await device.read(0, DISK_BLOCK_SIZE * BLOCK_COUNT)
+    await new Promise(resolve => setImmediate(resolve))
+
+    assert.equal(progressHandler.doneCalls, 1)
+  })
+
+  it('does not call done() before every block is cached', async () => {
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    await device.read(0, 512)
+    await new Promise(resolve => setImmediate(resolve))
+
+    assert.equal(progressHandler.doneCalls, 0)
+  })
+
+  it('does not let a throwing done() surface as an unhandled rejection', async () => {
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const progressHandler = new StubProgressHandler()
+    progressHandler.done = () => {
+      throw new Error('done failure')
+    }
+    const device = new CachedDiskBlockDevice({ disk, cache, progressHandler })
+    await device.open()
+
+    await device.hydrate()
+    await new Promise(resolve => setImmediate(resolve))
+  })
+})
+
+describe('onBlockCached', () => {
+  it('fires with the index of each newly cached block, once each', async () => {
+    const disk = new StubDisk(new Set([0, 1, 2, 3]))
+    const cache = new StubCache()
+    const cached: Array<number> = []
+    const device = new CachedDiskBlockDevice({ disk, cache, onBlockCached: index => cached.push(index) })
+    await device.open()
+
+    await device.read(0, 512)
+    assert.deepEqual(cached, [0])
+
+    // a hole is a materialization too
+    await device.read(DISK_BLOCK_SIZE, 512)
+    assert.deepEqual(cached, [0, 1])
+
+    // re-reading an already materialized block does not fire again
+    await device.read(0, 512)
+    assert.deepEqual(cached, [0, 1])
+  })
+
+  it('does not fire for a block resumed from the initial bitmap', async () => {
+    const disk = new StubDisk()
+    const cache = new StubCache()
+    const initialBitmap = Buffer.alloc(BLOCK_COUNT)
+    initialBitmap[0] = 1
+    const cached: Array<number> = []
+    const device = new CachedDiskBlockDevice({ disk, cache, initialBitmap, onBlockCached: index => cached.push(index) })
+    await device.open()
+
+    await device.read(0, 512)
+    assert.deepEqual(cached, [])
+  })
+
+  it('does not let a synchronously throwing callback break the read', async () => {
+    const disk = new StubDisk()
+    const cache = new StubCache()
+    const device = new CachedDiskBlockDevice({
+      disk,
+      cache,
+      onBlockCached: () => {
+        throw new Error('persistence failure')
+      },
+    })
+    await device.open()
+
+    assert.deepEqual(await device.read(0, 512), expectedAt(0, 512, disk.allocated))
+    assert.deepEqual(device.getMaterialized(), { blocks: 1, total: BLOCK_COUNT })
+  })
+})
+
+describe('flush and close', () => {
+  it('flushes the cache', async () => {
+    const { device, cache } = await make()
+    await device.flush()
+    assert.equal(cache.flushed, 1)
+  })
+
+  it('closes the cache and the disk', async () => {
+    const { device, cache, disk } = await make()
+    await device.close()
+    assert.equal(cache.closed, true)
+    assert.equal(disk.closed, true)
+  })
+
+  it('still closes the disk when closing the cache fails', async () => {
+    const { device, cache, disk } = await make()
+    cache.close = async () => {
+      throw new Error('nope')
+    }
+    await assert.rejects(device.close(), /nope/)
+    assert.equal(disk.closed, true)
+  })
+})

@vates/iscsi/src/DiskBlockDevice.mts

@@ -0,0 +1,120 @@
+import { createLogger, type Logger } from '@xen-orchestra/log'
+import type { RandomAccessDisk } from '@xen-orchestra/disk-transform'
+
+import type { BlockDevice } from './backend.mjs'
+
+const log: Logger = createLogger('vates:iscsi:disk-block-device')
+
+const DEFAULT_BLOCK_SIZE = 512
+
+export interface DiskBlockDeviceOptions {
+  /**
+   * Source disk, already `init()`ed by the caller (this adapter never calls
+   * `init()` — the disk may be part of a chain the caller assembled).
+   */
+  readonly disk: RandomAccessDisk
+  /**
+   * Logical block size advertised to initiators, in bytes. Defaults to 512.
+   * The disk's own block size must be a multiple of it.
+   */
+  readonly blockSize?: number
+}
+
+/**
+ * A read-only {@link BlockDevice} for a {@link RandomAccessDisk} (the inverse
+ * of {@link IscsiDisk}). Unallocated blocks read as zero; the source must
+ * never be asked for a block it doesn't have (e.g. `RemoteVhdDiskChain`
+ * throws).
+ *
+ * Nothing is cached — every read re-fetches a whole source block. Put a
+ * caching decorator in front of the source disk, not here.
+ */
+export class DiskBlockDevice implements BlockDevice {
+  readonly #disk: RandomAccessDisk
+  readonly #blockSize: number
+  #diskBlockSize?: number
+  #size?: number
+
+  constructor({ disk, blockSize = DEFAULT_BLOCK_SIZE }: DiskBlockDeviceOptions) {
+    if (!Number.isInteger(blockSize) || blockSize <= 0) {
+      throw new Error(`blockSize must be a positive integer, got ${blockSize}`)
+    }
+    this.#disk = disk
+    this.#blockSize = blockSize
+  }
+
+  /**
+   * Read the source disk's geometry and check it can be exposed as a LUN.
+   * Awaited by the target before it serves any I/O.
+   */
+  async open(): Promise<void> {
+    const blockSize = this.#blockSize
+    const diskBlockSize = this.#disk.getBlockSize()
+    if (diskBlockSize % blockSize !== 0) {
+      throw new Error(`disk block size (${diskBlockSize}) is not a multiple of the LUN block size (${blockSize})`)
+    }
+    const size = this.#disk.getVirtualSize()
+    if (size <= 0 || size % blockSize !== 0) {
+      throw new Error(`disk virtual size (${size}) is not a positive multiple of the LUN block size (${blockSize})`)
+    }
+    this.#diskBlockSize = diskBlockSize
+    this.#size = size
+    log.debug('opened', { size, blockSize, diskBlockSize })
+  }
+
+  getSize(): number {
+    const size = this.#size
+    if (size === undefined) {
+      throw new Error('DiskBlockDevice.open() must be called before I/O')
+    }
+    return size
+  }
+
+  getBlockSize(): number {
+    return this.#blockSize
+  }
+
+  async read(offset: number, length: number): Promise<Buffer> {
+    const size = this.getSize()
+    if (offset < 0 || length < 0 || offset + length > size) {
+      throw new Error(`read of ${length} bytes at ${offset} is out of range (size ${size})`)
+    }
+    if (length === 0) {
+      return Buffer.alloc(0)
+    }
+
+    const diskBlockSize = this.#diskBlockSize as number
+    // zero-filled: unallocated blocks, and any source block shorter than
+    // announced, are left as zeroes
+    const result = Buffer.alloc(length)
+    const end = offset + length
+    const lastIndex = Math.floor((end - 1) / diskBlockSize)
+    for (let index = Math.floor(offset / diskBlockSize); index <= lastIndex; index++) {
+      if (!this.#disk.hasBlock(index)) {
+        continue
+      }
+      const blockStart = index * diskBlockSize
+      const from = Math.max(offset, blockStart)
+      const to = Math.min(end, blockStart + diskBlockSize)
+      const { data } = await this.#disk.readBlock(index)
+      data.copy(result, from - offset, from - blockStart, to - blockStart)
+    }
+    return result
+  }
+
+  /**
+   * Always throws: the source disk is read-only. The target answers CHECK
+   * CONDITION / MEDIUM ERROR, which initiators surface as an I/O error.
+   */
+  async write(): Promise<void> {
+    throw new Error('DiskBlockDevice is read-only')
+  }
+
+  async flush(): Promise<void> {
+    // nothing to flush: read-only
+  }
+
+  async close(): Promise<void> {
+    await this.#disk.close()
+  }
+}

@vates/iscsi/src/DiskBlockDevice.test.mts

@@ -0,0 +1,169 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { RandomAccessDisk, type DiskBlock } from '@xen-orchestra/disk-transform'
+
+import { DiskBlockDevice } from './DiskBlockDevice.mjs'
+
+const BLOCK_SIZE = 4096
+
+/**
+ * Sparse in-memory {@link RandomAccessDisk}: `blocks` maps a block index to its
+ * content, every other index is unallocated and must never be read (the real
+ * `RemoteVhdDiskChain` throws in that case, which is what this asserts).
+ */
+class StubDisk extends RandomAccessDisk {
+  readBlockCalls: Array<number> = []
+  closed = false
+
+  constructor(
+    readonly blocks: Map<number, Buffer>,
+    readonly virtualSize: number,
+    readonly blockSize: number = BLOCK_SIZE
+  ) {
+    super()
+  }
+
+  getBlockSize(): number {
+    return this.blockSize
+  }
+  getVirtualSize(): number {
+    return this.virtualSize
+  }
+  isDifferencing(): boolean {
+    return false
+  }
+  getBlockIndexes(): Array<number> {
+    return [...this.blocks.keys()]
+  }
+  hasBlock(index: number): boolean {
+    return this.blocks.has(index)
+  }
+  async init(): Promise<void> {}
+  async close(): Promise<void> {
+    this.closed = true
+  }
+  async readBlock(index: number): Promise<DiskBlock> {
+    const data = this.blocks.get(index)
+    if (data === undefined) {
+      throw new Error(`Block ${index} not found`)
+    }
+    this.readBlockCalls.push(index)
+    return { index, data }
+  }
+}
+
+const filled = (byte: number, length = BLOCK_SIZE) => Buffer.alloc(length, byte)
+
+// 4 blocks, only 0 and 2 allocated
+const makeDevice = async (blockSize?: number) => {
+  const disk = new StubDisk(
+    new Map([
+      [0, filled(0xaa)],
+      [2, filled(0xcc)],
+    ]),
+    4 * BLOCK_SIZE
+  )
+  const device = new DiskBlockDevice({ disk, blockSize })
+  await device.open()
+  return { disk, device }
+}
+
+describe('open', () => {
+  it('exposes the disk capacity and the requested block size', async () => {
+    const { device } = await makeDevice()
+    assert.equal(device.getSize(), 4 * BLOCK_SIZE)
+    assert.equal(device.getBlockSize(), 512)
+  })
+
+  it('rejects a disk block size that is not a multiple of the LUN block size', async () => {
+    const disk = new StubDisk(new Map(), 4096, 600)
+    await assert.rejects(new DiskBlockDevice({ disk }).open(), /not a multiple of the LUN block size/)
+  })
+
+  it('rejects a capacity that is not a multiple of the LUN block size', async () => {
+    const disk = new StubDisk(new Map(), BLOCK_SIZE + 100)
+    await assert.rejects(new DiskBlockDevice({ disk }).open(), /not a positive multiple/)
+  })
+
+  it('rejects an invalid block size', () => {
+    const disk = new StubDisk(new Map(), BLOCK_SIZE)
+    assert.throws(() => new DiskBlockDevice({ disk, blockSize: 0 }), /positive integer/)
+  })
+
+  it('refuses I/O before open()', () => {
+    const disk = new StubDisk(new Map(), BLOCK_SIZE)
+    assert.throws(() => new DiskBlockDevice({ disk }).getSize(), /open\(\) must be called/)
+  })
+})
+
+describe('read', () => {
+  it('reads a whole allocated block', async () => {
+    const { device } = await makeDevice()
+    assert.deepEqual(await device.read(0, BLOCK_SIZE), filled(0xaa))
+  })
+
+  it('reads an unaligned slice inside one block', async () => {
+    const { device, disk } = await makeDevice()
+    assert.deepEqual(await device.read(BLOCK_SIZE * 2 + 512, 1024), filled(0xcc, 1024))
+    // a single source block was fetched, not the whole disk
+    assert.deepEqual(disk.readBlockCalls, [2])
+  })
+
+  it('zero-fills unallocated blocks instead of reading them', async () => {
+    const { device, disk } = await makeDevice()
+    assert.deepEqual(await device.read(BLOCK_SIZE, BLOCK_SIZE), Buffer.alloc(BLOCK_SIZE))
+    assert.deepEqual(disk.readBlockCalls, [])
+  })
+
+  it('stitches a range spanning allocated and unallocated blocks', async () => {
+    const { device } = await makeDevice()
+    const data = await device.read(BLOCK_SIZE - 512, BLOCK_SIZE + 1024)
+    assert.deepEqual(
+      data,
+      Buffer.concat([
+        filled(0xaa, 512), // tail of block 0
+        Buffer.alloc(BLOCK_SIZE), // block 1, unallocated
+        filled(0xcc, 512), // head of block 2
+      ])
+    )
+  })
+
+  it('reads the last block of the disk', async () => {
+    const { device } = await makeDevice()
+    assert.deepEqual(await device.read(3 * BLOCK_SIZE, BLOCK_SIZE), Buffer.alloc(BLOCK_SIZE))
+  })
+
+  it('returns an empty buffer for a zero-length read', async () => {
+    const { device, disk } = await makeDevice()
+    assert.equal((await device.read(0, 0)).length, 0)
+    assert.deepEqual(disk.readBlockCalls, [])
+  })
+
+  it('rejects a read past the end of the disk', async () => {
+    const { device } = await makeDevice()
+    await assert.rejects(device.read(4 * BLOCK_SIZE - 512, 1024), /out of range/)
+    await assert.rejects(device.read(-512, 512), /out of range/)
+  })
+
+  it('zero-pads a source block shorter than announced', async () => {
+    const disk = new StubDisk(new Map([[0, filled(0xaa, 1024)]]), BLOCK_SIZE)
+    const device = new DiskBlockDevice({ disk })
+    await device.open()
+    assert.deepEqual(await device.read(0, BLOCK_SIZE), Buffer.concat([filled(0xaa, 1024)], BLOCK_SIZE))
+  })
+})
+
+describe('write', () => {
+  it('always fails', async () => {
+    const { device } = await makeDevice()
+    await assert.rejects(device.write(), /read-only/)
+  })
+})
+
+describe('close', () => {
+  it('closes the underlying disk', async () => {
+    const { device, disk } = await makeDevice()
+    await device.close()
+    assert.equal(disk.closed, true)
+  })
+})

@vates/iscsi/src/IscsiDisk.mts

@@ -0,0 +1,98 @@
+import { RandomAccessDisk, type DiskBlock } from '@xen-orchestra/disk-transform'
+
+import { IscsiInitiator, type IscsiInitiatorOptions } from './initiator.mjs'
+
+export interface IscsiDiskOptions {
+  /**
+   * Block size, in bytes, presented to the disk-transform pipeline. Must be a
+   * multiple of the LUN's logical block size (checked at {@link IscsiDisk.init}).
+   * A single SCSI READ(16) fetches one whole block.
+   */
+  readonly blockSize: number
+}
+
+/**
+ * A {@link RandomAccessDisk} backed by a remote iSCSI LUN read through an
+ * {@link IscsiInitiator} — the iSCSI analogue of `@vates/nbd-client`'s `NbdDisk`.
+ * It plugs a target LUN into the `@xen-orchestra/disk-transform` pipeline
+ * (`ReadAhead`, `DiskLargerBlock`, block generator) unchanged.
+ *
+ * First implementation: the LUN is treated as fully allocated — every block is
+ * reported as present (dense, like `RawDisk`). A future version can narrow this
+ * with a changed-block map (e.g. a Pure "Volume Difference"). Read-only.
+ */
+export class IscsiDisk extends RandomAccessDisk {
+  readonly #options: IscsiInitiatorOptions
+  readonly #blockSize: number
+  #initiator?: IscsiInitiator
+
+  constructor(options: IscsiInitiatorOptions, { blockSize }: IscsiDiskOptions) {
+    super()
+    this.#options = options
+    this.#blockSize = blockSize
+  }
+
+  async init(): Promise<void> {
+    const initiator = new IscsiInitiator(this.#options)
+    await initiator.connect()
+    const lunBlockSize = initiator.getBlockSize()
+    if (this.#blockSize % lunBlockSize !== 0) {
+      await initiator.close()
+      throw new Error(`block size ${this.#blockSize} is not a multiple of the LUN block size ${lunBlockSize}`)
+    }
+    this.#initiator = initiator
+  }
+
+  async close(): Promise<void> {
+    const initiator = this.#initiator
+    this.#initiator = undefined
+    await initiator?.close()
+  }
+
+  #requireInitiator(): IscsiInitiator {
+    const initiator = this.#initiator
+    if (initiator === undefined) {
+      throw new Error('IscsiDisk.init() must be called first')
+    }
+    return initiator
+  }
+
+  getBlockSize(): number {
+    return this.#blockSize
+  }
+
+  getVirtualSize(): number {
+    return this.#requireInitiator().getSize()
+  }
+
+  isDifferencing(): boolean {
+    return false
+  }
+
+  getBlockIndexes(): Array<number> {
+    const count = Math.ceil(this.getVirtualSize() / this.#blockSize)
+    const indexes = new Array<number>(count)
+    for (let i = 0; i < count; i++) {
+      indexes[i] = i
+    }
+    return indexes
+  }
+
+  hasBlock(index: number): boolean {
+    return index >= 0 && index * this.#blockSize < this.getVirtualSize()
+  }
+
+  async readBlock(index: number): Promise<DiskBlock> {
+    const initiator = this.#requireInitiator()
+    const size = this.getVirtualSize()
+    const offset = index * this.#blockSize
+    const length = Math.min(this.#blockSize, size - offset)
+    let data = await initiator.read(offset, length)
+    if (data.length < this.#blockSize) {
+      // Last (short) block on a LUN whose capacity is not a multiple of the
+      // disk block size: zero-pad the tail to a full block.
+      data = Buffer.concat([data], this.#blockSize)
+    }
+    return { index, data }
+  }
+}

@vates/iscsi/src/backend.mts

@@ -0,0 +1,131 @@
+import { open, type FileHandle } from 'node:fs/promises'
+
+/**
+ * Byte-range random-access store backing a single iSCSI LUN.
+ *
+ * The protocol layer translates SCSI READ/WRITE CDBs (LBA + block count) into
+ * byte offsets/lengths against this interface, so an implementation only has to
+ * provide flat random access — it is intentionally decoupled from the wire
+ * code. `DiskBlockDevice` is such an implementation, over
+ * `@xen-orchestra/disk-transform`'s `RandomAccessDisk` (VHD/raw/NBD).
+ */
+export interface BlockDevice {
+  /** Optional one-time initialization, awaited by the target before serving I/O. */
+  open?(): Promise<void>
+  /** Total capacity in bytes. Must be a multiple of {@link BlockDevice.getBlockSize}. */
+  getSize(): number
+  /** Logical block size in bytes (typically 512). */
+  getBlockSize(): number
+  /** Read exactly `length` bytes starting at byte `offset`. */
+  read(offset: number, length: number): Promise<Buffer>
+  /** Write `data` starting at byte `offset`. */
+  write(offset: number, data: Buffer): Promise<void>
+  /** Flush any buffered data to stable storage (SYNCHRONIZE CACHE). */
+  flush(): Promise<void>
+  /** Release underlying resources. */
+  close(): Promise<void>
+}
+
+const DEFAULT_BLOCK_SIZE = 512
+
+export interface FileBlockDeviceOptions {
+  /** Path to the backing file. It must already exist and be sized to capacity. */
+  readonly path: string
+  /** Logical block size in bytes. Defaults to 512. */
+  readonly blockSize?: number
+}
+
+/**
+ * A {@link BlockDevice} backed by a regular (sparse) file opened read/write.
+ *
+ * The file must already exist and be sized to the desired capacity (e.g. via
+ * `fs.truncate`); this keeps the device a pure data store with no provisioning
+ * policy of its own.
+ */
+export class FileBlockDevice implements BlockDevice {
+  readonly #path: string
+  readonly #blockSize: number
+  #handle?: FileHandle
+  #size = 0
+
+  constructor({ path, blockSize = DEFAULT_BLOCK_SIZE }: FileBlockDeviceOptions) {
+    if (!Number.isInteger(blockSize) || blockSize <= 0) {
+      throw new Error(`blockSize must be a positive integer, got ${blockSize}`)
+    }
+    this.#path = path
+    this.#blockSize = blockSize
+  }
+
+  /** Open the backing file and read its current size. Must be called before any I/O. */
+  async open(): Promise<void> {
+    if (this.#handle !== undefined) {
+      return
+    }
+    const handle = await open(this.#path, 'r+')
+    try {
+      const { size } = await handle.stat()
+      if (size % this.#blockSize !== 0) {
+        throw new Error(`backing file size (${size}) is not a multiple of block size (${this.#blockSize})`)
+      }
+      this.#handle = handle
+      this.#size = size
+    } catch (error) {
+      await handle.close()
+      throw error
+    }
+  }
+
+  #requireHandle(): FileHandle {
+    const handle = this.#handle
+    if (handle === undefined) {
+      throw new Error('FileBlockDevice.open() must be called before I/O')
+    }
+    return handle
+  }
+
+  getSize(): number {
+    return this.#size
+  }
+
+  getBlockSize(): number {
+    return this.#blockSize
+  }
+
+  async read(offset: number, length: number): Promise<Buffer> {
+    const handle = this.#requireHandle()
+    const buffer = Buffer.alloc(length, 0)
+    let read = 0
+    // A single fh.read may return fewer bytes than requested; loop to fill.
+    while (read < length) {
+      const { bytesRead } = await handle.read(buffer, read, length - read, offset + read)
+      if (bytesRead === 0) {
+        // Reading past EOF (sparse tail): zero-fill the remainder.
+        buffer.fill(0, read)
+        break
+      }
+      read += bytesRead
+    }
+    return buffer
+  }
+
+  async write(offset: number, data: Buffer): Promise<void> {
+    const handle = this.#requireHandle()
+    let written = 0
+    while (written < data.length) {
+      const { bytesWritten } = await handle.write(data, written, data.length - written, offset + written)
+      written += bytesWritten
+    }
+  }
+
+  async flush(): Promise<void> {
+    await this.#requireHandle().sync()
+  }
+
+  async close(): Promise<void> {
+    const handle = this.#handle
+    if (handle !== undefined) {
+      this.#handle = undefined
+      await handle.close()
+    }
+  }
+}

@vates/iscsi/src/chap.mts

@@ -0,0 +1,90 @@
+// Shared CHAP (RFC 1994) primitives for both login directions: the target as
+// authenticator, the initiator as responder. Kept in one place so the MD5
+// computation and large-binary codec agree byte-for-byte between the two
+// (cross-tested against each other in loopback).
+//
+// RFC 7143 §11.1.4 pins CHAP to MD5 (algorithm id 5) — a wire-format
+// requirement, not a security choice.
+
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+
+/** The only CHAP algorithm iSCSI defines / we support: MD5 (RFC 7143 §11.1.4). */
+export const CHAP_ALGORITHM_MD5 = 5
+
+/** Default challenge length in bytes; 16 is what open-iscsi and most targets use. */
+const DEFAULT_CHALLENGE_LENGTH = 16
+
+/**
+ * Compute a CHAP response: `MD5(id ‖ secret ‖ challenge)` (RFC 1994 §4.1).
+ *
+ * `id` is the single CHAP_I octet (0-255) — the raw byte, NOT its ASCII decimal.
+ * `secret` is the shared secret (a string is hashed as its UTF-8 bytes).
+ */
+export function computeResponse(id: number, secret: string | Buffer, challenge: Buffer): Buffer {
+  return createHash('md5')
+    .update(Buffer.from([id & 0xff]))
+    .update(secret)
+    .update(challenge)
+    .digest()
+}
+
+/**
+ * Encode a binary value (CHAP_C / CHAP_R) as an iSCSI hex-constant, e.g.
+ * `0xa1b2…` (RFC 7143 §5.1). We always emit hex; {@link decodeChapValue} accepts
+ * both hex and base64 so we interoperate with peers that send either.
+ */
+export function encodeChapValue(value: Buffer): string {
+  return '0x' + value.toString('hex')
+}
+
+/**
+ * Decode an iSCSI large-binary value: `0x`/`0X` hex-constant or `0b`/`0B`
+ * base64-constant (RFC 7143 §5.1). Throws on an unrecognized encoding.
+ */
+export function decodeChapValue(value: string): Buffer {
+  const prefix = value.slice(0, 2)
+  const body = value.slice(2)
+  if (prefix === '0x' || prefix === '0X') {
+    return Buffer.from(body, 'hex')
+  }
+  if (prefix === '0b' || prefix === '0B') {
+    return Buffer.from(body, 'base64')
+  }
+  throw new Error(`unsupported CHAP value encoding: ${value.slice(0, 2)}…`)
+}
+
+/** Generate a random CHAP challenge (CHAP_C). */
+export function generateChallenge(length: number = DEFAULT_CHALLENGE_LENGTH): Buffer {
+  return randomBytes(length)
+}
+
+/** Generate a random CHAP identifier (CHAP_I), a single octet. */
+export function generateId(): number {
+  return randomBytes(1)[0]
+}
+
+/** Parse a CHAP_A value (`"5"` or a `"5,6,7"` preference list) into algorithm ids. */
+export function parseAlgorithmList(value: string): number[] {
+  return value
+    .split(',')
+    .map(part => Number.parseInt(part.trim(), 10))
+    .filter(id => Number.isInteger(id))
+}
+
+/**
+ * Pick the algorithm we will use from the ones the peer offered: MD5 if present,
+ * else `undefined` (we only implement MD5, so an offer without it must fail —
+ * never fall back to the first offered id).
+ */
+export function selectAlgorithm(offered: readonly number[]): number | undefined {
+  return offered.includes(CHAP_ALGORITHM_MD5) ? CHAP_ALGORITHM_MD5 : undefined
+}
+
+/**
+ * Constant-time comparison of an expected response against a received one. A
+ * wrong-length `got` (or the length-mismatch `timingSafeEqual` would throw on)
+ * counts as a failed authentication, not an exception.
+ */
+export function verifyResponse(expected: Buffer, got: Buffer): boolean {
+  return expected.length === got.length && timingSafeEqual(expected, got)
+}

@vates/iscsi/src/chap.test.mts

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import { describe, it } from 'node:test'
+
+import {
+  CHAP_ALGORITHM_MD5,
+  computeResponse,
+  decodeChapValue,
+  encodeChapValue,
+  generateChallenge,
+  generateId,
+  parseAlgorithmList,
+  selectAlgorithm,
+  verifyResponse,
+} from './chap.mjs'
+
+describe('computeResponse', () => {
+  // Known-answer vector: MD5(0x01 ‖ "s3cr3t" ‖ <16-byte challenge>), computed
+  // independently so this pins the exact byte layout (id octet first), not MD5
+  // against itself.
+  const id = 1
+  const secret = 's3cr3t'
+  const challenge = Buffer.from('0102030405060708090a0b0c0d0e0f10', 'hex')
+  const expected = 'fc14fb49f184c847514a10278d75a10f'
+
+  it('hashes id ‖ secret ‖ challenge (RFC 1994)', () => {
+    assert.equal(computeResponse(id, secret, challenge).toString('hex'), expected)
+  })
+
+  it('treats a string secret as its UTF-8 bytes', () => {
+    assert.deepEqual(
+      computeResponse(id, Buffer.from(secret, 'utf8'), challenge),
+      computeResponse(id, secret, challenge)
+    )
+  })
+
+  it('uses the id as a raw octet, not its ASCII decimal', () => {
+    // computeResponse(1, …) must hash the byte 0x01, whereas hashing the ASCII
+    // text "1" would hash 0x31 — the two must differ.
+    const rawOctet = createHash('md5')
+      .update(Buffer.from([1]))
+      .update(secret)
+      .update(challenge)
+      .digest()
+    const asciiText = createHash('md5').update(Buffer.from('1', 'ascii')).update(secret).update(challenge).digest()
+    assert.deepEqual(computeResponse(1, secret, challenge), rawOctet)
+    assert.notDeepEqual(computeResponse(1, secret, challenge), asciiText)
+  })
+})
+
+describe('CHAP value codec', () => {
+  it('encodes as a 0x hex-constant', () => {
+    assert.equal(encodeChapValue(Buffer.from([0xab, 0xcd, 0x01])), '0xabcd01')
+  })
+
+  it('round-trips through hex', () => {
+    const value = generateChallenge()
+    assert.deepEqual(decodeChapValue(encodeChapValue(value)), value)
+  })
+
+  it('decodes a 0b base64-constant', () => {
+    const raw = Buffer.from('0102030405060708090a0b0c0d0e0f10', 'hex')
+    assert.deepEqual(decodeChapValue('0b' + raw.toString('base64')), raw)
+  })
+
+  it('accepts uppercase 0X / 0B prefixes', () => {
+    assert.deepEqual(decodeChapValue('0Xabcd'), Buffer.from('abcd', 'hex'))
+    assert.deepEqual(decodeChapValue('0B' + Buffer.from([1, 2]).toString('base64')), Buffer.from([1, 2]))
+  })
+
+  it('rejects an unknown encoding', () => {
+    assert.throws(() => decodeChapValue('12345'), /unsupported CHAP value encoding/)
+  })
+})
+
+describe('algorithm selection', () => {
+  it('parses a preference list', () => {
+    assert.deepEqual(parseAlgorithmList('5,6,7'), [5, 6, 7])
+    assert.deepEqual(parseAlgorithmList('5'), [5])
+  })
+
+  it('picks MD5 when offered', () => {
+    assert.equal(selectAlgorithm([1, CHAP_ALGORITHM_MD5, 6]), CHAP_ALGORITHM_MD5)
+  })
+
+  it('returns undefined when MD5 is not offered (never falls back)', () => {
+    assert.equal(selectAlgorithm([1, 2]), undefined)
+  })
+})
+
+describe('verifyResponse', () => {
+  const secret = 's3cr3t'
+  const challenge = generateChallenge()
+  const id = generateId()
+  const good = computeResponse(id, secret, challenge)
+
+  it('accepts a matching response', () => {
+    assert.equal(verifyResponse(good, computeResponse(id, secret, challenge)), true)
+  })
+
+  it('rejects a wrong secret', () => {
+    assert.equal(verifyResponse(good, computeResponse(id, 'wrong', challenge)), false)
+  })
+
+  it('rejects a wrong-length response without throwing', () => {
+    assert.equal(verifyResponse(good, Buffer.alloc(4)), false)
+  })
+})

@vates/iscsi/src/cli.mts

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { stat, truncate, writeFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { parseArgs } from 'node:util'
+
+import { FileBlockDevice, IscsiTarget } from './index.mjs'
+
+const USAGE = `Usage: vates-iscsi <file> [options]
+
+Serve a single read/write iSCSI LUN backed by <file>.
+
+Arguments:
+  <file>                  Backing file. Must exist and have a size that is a
+                          multiple of the block size, unless --size is given.
+
+Options:
+  --serial <serial>       LUN serial number (default: derived from the IQN).
+  --size <bytes>          Create/grow the backing file to this many bytes.
+                          Accepts suffixes K, M, G, T (e.g. 10G).
+  --iqn <iqn>             Target IQN (default: iqn.2024-01.tech.vates:<file>).
+  --host <host>           Listen address (default: 0.0.0.0).
+  --port <port>           Listen port (default: 3260).
+  --block-size <bytes>    Logical block size (default: 512).
+  -h, --help              Show this help.
+`
+
+function fail(message: string): never {
+  process.stderr.write(`vates-iscsi: ${message}\n`)
+  process.exit(1)
+}
+
+/** Parse a positive integer with optional K/M/G/T suffix (powers of 1024). */
+function parseSize(value: string, label: string): number {
+  const match = /^(\d+)([KMGT]?)$/i.exec(value.trim())
+  if (match === null) {
+    fail(`invalid ${label}: ${value}`)
+  }
+  const units: Record<string, number> = { '': 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4 }
+  return Number(match[1]) * units[match[2].toUpperCase()]
+}
+
+/** Sanitize a string into the characters allowed in the IQN-specific part. */
+function sanitizeIqnPart(value: string): string {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9.-]+/g, '-').replace(/^-+|-+$/g, '')
+  return cleaned.length > 0 ? cleaned : 'lun0'
+}
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    serial: { type: 'string' },
+    size: { type: 'string' },
+    iqn: { type: 'string' },
+    host: { type: 'string' },
+    port: { type: 'string' },
+    'block-size': { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+  },
+})
+
+if (values.help || positionals.length === 0) {
+  process.stdout.write(USAGE)
+  process.exit(values.help ? 0 : 1)
+}
+if (positionals.length > 1) {
+  fail(`expected a single <file>, got ${positionals.length}`)
+}
+
+const path = positionals[0]
+const blockSize = values['block-size'] !== undefined ? parseSize(values['block-size'], 'block size') : 512
+const port = values.port !== undefined ? Number.parseInt(values.port, 10) : 3260
+if (!Number.isInteger(port) || port < 0 || port > 65535) {
+  fail(`invalid port: ${values.port}`)
+}
+
+// Create/grow the backing file when --size is requested.
+if (values.size !== undefined) {
+  const size = parseSize(values.size, 'size')
+  if (size % blockSize !== 0) {
+    fail(`--size (${size}) must be a multiple of the block size (${blockSize})`)
+  }
+  const exists = await stat(path).then(
+    () => true,
+    () => false
+  )
+  if (!exists) {
+    await writeFile(path, Buffer.alloc(0))
+  }
+  await truncate(path, size)
+}
+
+// Validate the backing file before binding the socket.
+const stats = await stat(path).catch(() => fail(`backing file not found: ${path} (create one, e.g. \`truncate -s 10G ${path}\`, or pass --size)`))
+if (stats.size === 0) {
+  fail(`backing file is empty: ${path} (size it first, e.g. \`truncate -s 10G ${path}\`, or pass --size)`)
+}
+
+const iqn = values.iqn ?? `iqn.2024-01.tech.vates:${sanitizeIqnPart(basename(path).replace(/\.[^.]+$/, ''))}`
+
+const target = new IscsiTarget({
+  iqn,
+  host: values.host,
+  port,
+  lun: new FileBlockDevice({ path, blockSize }),
+  identity: values.serial !== undefined ? { serial: values.serial } : undefined,
+})
+
+await target.listen()
+
+const address = target.address()
+const listenHost = values.host ?? '0.0.0.0'
+const listenPort = address?.port ?? port
+process.stdout.write(
+  [
+    `iSCSI target listening on ${listenHost}:${listenPort}`,
+    `  IQN:     ${iqn}`,
+    `  LUN:     ${path} (${stats.size} bytes, ${blockSize}-byte blocks)`,
+    `  serial:  ${values.serial ?? iqn}`,
+    ``,
+    `Discover with:  iscsiadm -m discovery -t sendtargets -p ${listenHost === '0.0.0.0' ? '127.0.0.1' : listenHost}:${listenPort}`,
+    `Press Ctrl-C to stop.`,
+    ``,
+  ].join('\n')
+)
+
+let stopping = false
+function stop(): void {
+  if (stopping) {
+    return
+  }
+  stopping = true
+  target.close().then(
+    () => process.exit(0),
+    error => {
+      process.stderr.write(`vates-iscsi: error on shutdown: ${String(error)}\n`)
+      process.exit(1)
+    }
+  )
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)

@vates/iscsi/src/connection.mts

@@ -0,0 +1,582 @@
+import type { Socket } from 'node:net'
+import { createLogger, type Logger } from '@xen-orchestra/log'
+
+import type { BlockDevice } from './backend.mjs'
+import {
+  Asc,
+  DATA_IN_FLAG_FINAL,
+  DATA_IN_FLAG_OVERFLOW,
+  DATA_IN_FLAG_STATUS,
+  DATA_IN_FLAG_UNDERFLOW,
+  FLAG_FINAL,
+  InitiatorOpcode,
+  ISCSI_VERSION,
+  LoginStatusClass,
+  LogoutResponse,
+  RejectReason,
+  RESERVED_TAG,
+  SCSI_RESP_FLAG_OVERFLOW,
+  SCSI_RESP_FLAG_UNDERFLOW,
+  SCSI_RESPONSE_COMMAND_COMPLETED,
+  ScsiStatus,
+  SenseKey,
+  TargetOpcode,
+  TEXT_FLAG_FINAL,
+} from './constants.mjs'
+import { buildFixedSense, handleScsiCommand, type ScsiIdentity } from './scsi.mjs'
+import { buildSendTargetsResponse, LoginNegotiator, parseTextKeys } from './login.mjs'
+import { allocBhs, assemblePdu, type IncomingPdu, readPdu, writePdu } from './pdu.mjs'
+import {
+  decodeCdb,
+  type ChapCredentials,
+  type CommandContext,
+  type NegotiatedParams,
+  type ScsiResponseOptions,
+  type SessionType,
+} from './types.mjs'
+import { buildR2t, receiveDataOut, type PendingWrite } from './writePath.mjs'
+import { Semaphore } from './semaphore.mjs'
+
+const log: Logger = createLogger('vates:iscsi')
+
+/** 2^32: the modulus for all iSCSI sequence-number arithmetic. */
+export const SERIAL_MODULO = 0x1_0000_0000
+
+/** Increment an iSCSI serial number with 32-bit wraparound. */
+export function incrementSerial(value: number): number {
+  return (value + 1) % SERIAL_MODULO
+}
+
+/** Add `delta` to an iSCSI serial number with 32-bit wraparound. */
+export function addSerial(value: number, delta: number): number {
+  return (value + delta) % SERIAL_MODULO
+}
+
+/**
+ * Initiator opcodes whose BHS bytes 24-27 are CmdSN. The two that are missing —
+ * SCSI Data-Out and SNACK — have those bytes reserved instead; see the comment
+ * on `Connection`'s `#updateCommandWindow` for what reading them would cost.
+ */
+const CARRIES_CMD_SN: ReadonlySet<number> = new Set([
+  InitiatorOpcode.NOP_OUT,
+  InitiatorOpcode.SCSI_COMMAND,
+  InitiatorOpcode.SCSI_TASK_MGMT_REQUEST,
+  InitiatorOpcode.LOGIN_REQUEST,
+  InitiatorOpcode.TEXT_REQUEST,
+  InitiatorOpcode.LOGOUT_REQUEST,
+])
+
+/** Everything a {@link Connection} needs from the owning target. */
+export interface ConnectionDeps {
+  readonly iqn: string
+  readonly identity: ScsiIdentity
+  readonly lun: BlockDevice
+  /** Drain timeout for outbound PDUs, in ms (0 disables). */
+  readonly writeTimeoutMs: number
+  /** Size of the CmdSN command window advertised to the initiator. */
+  readonly cmdWindow: number
+  /** Max number of READs served concurrently (see {@link Connection}). */
+  readonly readConcurrency: number
+  /** Allocate a fresh, non-zero Target Session Identifying Handle. */
+  allocateTsih(): number
+  /** When set, require one-way CHAP: the target challenges and verifies the initiator. */
+  readonly chap?: ChapCredentials
+}
+
+type Phase = 'login' | 'fullFeature' | 'closed'
+
+/**
+ * Drives one iSCSI connection: login, command-window/StatSN sequencing, and
+ * full-feature-phase PDU dispatch. With MaxConnections=1 a connection is also
+ * the whole session.
+ *
+ * Everything but READ runs one at a time; the read loop advances only once a
+ * command fully completes. READ is dispatched without waiting on its own
+ * `lun.read()` (can be a slow network fetch) — up to `readConcurrency` at
+ * once, via `#readGate` — so one slow read can't block every other command.
+ *
+ * StatSN is allocated and written to the socket synchronously, with no
+ * `await` in between, so responses reach the wire in whatever order the event
+ * loop runs their completions — no extra sequencing needed. This does not
+ * order a READ against a concurrent WRITE to the same LBA range: it may see
+ * old or new bytes, like an untagged SCSI command with no ordering barrier.
+ */
+export class Connection implements CommandContext {
+  readonly #socket: Socket
+  readonly #deps: ConnectionDeps
+  readonly #login: LoginNegotiator
+  readonly #readGate: Semaphore
+
+  #phase: Phase = 'login'
+  #sessionType: SessionType = 'Normal'
+  #params: NegotiatedParams = { initiatorMaxRecvDataSegmentLength: 8192, maxBurstLength: 262144 }
+
+  #statSN = 0
+  #expCmdSN = 0
+  #maxCmdSN = 0
+  #cmdSNInitialized = false
+  #tsih = 0
+
+  // In-progress WRITEs keyed by Initiator Task Tag. Data-Out PDUs are routed
+  // here, so writes can be interleaved with (and outstanding alongside) other
+  // commands without blocking the read loop.
+  readonly #pendingWrites = new Map<number, PendingWrite>()
+  #nextTargetTransferTag = 1
+
+  constructor(socket: Socket, deps: ConnectionDeps) {
+    this.#socket = socket
+    this.#deps = deps
+    this.#login = new LoginNegotiator(deps.chap)
+    this.#readGate = new Semaphore(deps.readConcurrency)
+  }
+
+  get lun(): BlockDevice {
+    return this.#deps.lun
+  }
+
+  /** Forcibly tear down the connection (used when the target is closing). */
+  destroy(): void {
+    this.#phase = 'closed'
+    this.#socket.destroy()
+  }
+
+  /** Read and service PDUs until the peer logs out or the connection drops. */
+  async serve(): Promise<void> {
+    try {
+      for (;;) {
+        const pdu = await readPdu(this.#socket)
+        if (pdu === null) {
+          break // peer closed the connection
+        }
+        const finished = await this.#dispatch(pdu)
+        if (finished) {
+          break
+        }
+      }
+    } catch (error) {
+      this.#fail(error)
+    } finally {
+      this.#phase = 'closed'
+      this.#socket.destroy()
+    }
+  }
+
+  /**
+   * Log a connection-ending error and tear the socket down — the same outcome
+   * an uncaught error in the main `serve()` loop already had, now also reached
+   * by a concurrently-dispatched READ that fails (e.g. a backend read error):
+   * with nothing else awaiting it directly, it would otherwise surface only as
+   * an unhandled rejection while the initiator hangs waiting for a response
+   * that will never come. Safe to call more than once — `socket.destroy()` is
+   * itself idempotent.
+   */
+  #fail(error: unknown): void {
+    if (this.#phase === 'closed') {
+      return
+    }
+    const err = error instanceof Error ? error : new Error(String(error))
+    const code = (err as NodeJS.ErrnoException).code
+    // A peer dropping the socket (e.g. on logout) is normal, not a fault.
+    if (code === 'ECONNRESET' || code === 'EPIPE' || code === 'ECONNABORTED') {
+      log.debug('connection closed by peer', { code })
+    } else {
+      log.warn('connection error', err)
+    }
+    this.#phase = 'closed'
+    this.#socket.destroy()
+  }
+
+  // --- sequencing -----------------------------------------------------------
+
+  /**
+   * Advance the command window from a freshly received PDU — but only from one
+   * that actually carries a CmdSN.
+   *
+   * BHS bytes 24-27 hold CmdSN on command PDUs only; on a SCSI Data-Out (RFC
+   * 7143 §11.7) and a SNACK they are reserved, as is the immediate bit. An
+   * initiator zeroes them, so treating such a PDU as a command reads CmdSN=0,
+   * takes the non-immediate branch, and rewinds the window to ExpCmdSN=1 /
+   * MaxCmdSN=1+window — then advertises it on the very next R2T, SCSI Response,
+   * or concurrent READ's Data-In. Initiators discard the rewind as stale only
+   * while the session's CmdSN stays below 2^31; past that it compares as newer
+   * under serial arithmetic, is adopted, and the window collapses into a stall.
+   *
+   * Since every WRITE is R2T-solicited (InitialR2T=Yes), Data-Out is the common
+   * case, not an edge one. Allowlisting the opcodes that do carry CmdSN, rather
+   * than skipping the two that don't, keeps a newly handled opcode from
+   * silently inheriting the bug.
+   */
+  #updateCommandWindow(pdu: IncomingPdu): void {
+    if (!CARRIES_CMD_SN.has(pdu.opcode)) {
+      return
+    }
+    const cmdSN = pdu.cmdSN
+    if (!this.#cmdSNInitialized) {
+      this.#expCmdSN = cmdSN
+      this.#cmdSNInitialized = true
+    }
+    // Immediate PDUs (Login, NOP pings, aborts) do not consume a CmdSN slot.
+    if (!pdu.immediate) {
+      this.#expCmdSN = incrementSerial(cmdSN)
+    }
+    this.#maxCmdSN = addSerial(this.#expCmdSN, this.#deps.cmdWindow)
+  }
+
+  /** Current StatSN without advancing (for R2T, NOP-In, Reject, non-final Data-In). */
+  #currentStatSN(): number {
+    return this.#statSN
+  }
+
+  /** Return the current StatSN and advance it (for status-bearing responses). */
+  #nextStatSN(): number {
+    const value = this.#statSN
+    this.#statSN = incrementSerial(value)
+    return value
+  }
+
+  #send(buffer: Buffer): Promise<void> {
+    return writePdu(this.#socket, buffer, this.#deps.writeTimeoutMs)
+  }
+
+  // --- dispatch -------------------------------------------------------------
+
+  /** Returns true when the connection should be closed (after a logout). */
+  async #dispatch(pdu: IncomingPdu): Promise<boolean> {
+    this.#updateCommandWindow(pdu)
+
+    if (this.#phase === 'login') {
+      if (pdu.opcode === InitiatorOpcode.LOGIN_REQUEST) {
+        return await this.#handleLogin(pdu)
+      }
+      await this.#sendReject(pdu, RejectReason.PROTOCOL_ERROR)
+      return false
+    }
+
+    switch (pdu.opcode) {
+      case InitiatorOpcode.SCSI_COMMAND:
+        if (this.#sessionType === 'Discovery') {
+          await this.#sendReject(pdu, RejectReason.PROTOCOL_ERROR)
+        } else {
+          await this.#handleScsiCommand(pdu)
+        }
+        return false
+      case InitiatorOpcode.TEXT_REQUEST:
+        await this.#handleText(pdu)
+        return false
+      case InitiatorOpcode.NOP_OUT:
+        await this.#handleNopOut(pdu)
+        return false
+      case InitiatorOpcode.LOGOUT_REQUEST:
+        await this.#handleLogout(pdu)
+        return true
+      case InitiatorOpcode.SCSI_DATA_OUT:
+        await this.#handleDataOut(pdu)
+        return false
+      default:
+        await this.#sendReject(pdu, RejectReason.COMMAND_NOT_SUPPORTED)
+        return false
+    }
+  }
+
+  /** Returns true when the login failed and the connection must be closed. */
+  async #handleLogin(pdu: IncomingPdu): Promise<boolean> {
+    const { flagsByte, data, statusClass = LoginStatusClass.SUCCESS, statusDetail = 0 } = this.#login.process(pdu)
+    if (this.#login.complete && this.#tsih === 0) {
+      this.#tsih = this.#deps.allocateTsih()
+    }
+
+    const bhs = allocBhs(TargetOpcode.LOGIN_RESPONSE)
+    bhs[1] = flagsByte
+    bhs[2] = ISCSI_VERSION // Version-max
+    bhs[3] = ISCSI_VERSION // Version-active
+    pdu.bhs.copy(bhs, 8, 8, 14) // echo ISID (6 bytes)
+    bhs.writeUInt16BE(this.#tsih, 14)
+    bhs.writeUInt32BE(pdu.itt, 16)
+    bhs.writeUInt32BE(this.#nextStatSN(), 24)
+    bhs.writeUInt32BE(this.#expCmdSN, 28)
+    bhs.writeUInt32BE(this.#maxCmdSN, 32)
+    bhs[36] = statusClass
+    bhs[37] = statusDetail
+    await this.#send(assemblePdu(bhs, data))
+
+    if (statusClass !== LoginStatusClass.SUCCESS) {
+      // RFC 7143 §6.3: the failure response goes out first (above), then the
+      // target closes the connection.
+      log.warn('login rejected', { statusClass, statusDetail, initiator: this.#login.initiatorName })
+      this.#phase = 'closed'
+      return true
+    }
+
+    if (this.#login.complete) {
+      this.#phase = 'fullFeature'
+      this.#sessionType = this.#login.sessionType
+      this.#params = this.#login.params
+      log.info('session established', {
+        initiator: this.#login.initiatorName,
+        sessionType: this.#sessionType,
+        target: this.#login.targetName,
+      })
+    }
+    return false
+  }
+
+  async #handleText(pdu: IncomingPdu): Promise<void> {
+    const keys = parseTextKeys(pdu.data)
+    // SendTargets discovery: advertise this target at the address the initiator
+    // actually connected to.
+    const data =
+      keys.get('SendTargets') !== undefined
+        ? buildSendTargetsResponse(
+            this.#deps.iqn,
+            this.#socket.localAddress ?? '0.0.0.0',
+            this.#socket.localPort ?? 3260
+          )
+        : Buffer.alloc(0)
+
+    const bhs = allocBhs(TargetOpcode.TEXT_RESPONSE)
+    bhs[1] = TEXT_FLAG_FINAL
+    bhs.writeUInt32BE(pdu.itt, 16)
+    bhs.writeUInt32BE(RESERVED_TAG, 20) // Target Transfer Tag: none / final
+    bhs.writeUInt32BE(this.#nextStatSN(), 24)
+    bhs.writeUInt32BE(this.#expCmdSN, 28)
+    bhs.writeUInt32BE(this.#maxCmdSN, 32)
+    await this.#send(assemblePdu(bhs, data))
+  }
+
+  async #handleNopOut(pdu: IncomingPdu): Promise<void> {
+    // A NOP-Out with the reserved ITT is the initiator's reply to a NOP-In we
+    // sent; nothing to do. Otherwise echo it back as a NOP-In ping reply.
+    if (pdu.itt === RESERVED_TAG) {
+      return
+    }
+    const bhs = allocBhs(TargetOpcode.NOP_IN)
+    bhs[1] = FLAG_FINAL
+    pdu.bhs.copy(bhs, 8, 8, 16) // echo LUN
+    bhs.writeUInt32BE(pdu.itt, 16)
+    bhs.writeUInt32BE(RESERVED_TAG, 20) // Target Transfer Tag
+    bhs.writeUInt32BE(this.#currentStatSN(), 24) // NOP-In does not advance StatSN
+    bhs.writeUInt32BE(this.#expCmdSN, 28)
+    bhs.writeUInt32BE(this.#maxCmdSN, 32)
+    await this.#send(assemblePdu(bhs, pdu.data)) // echo ping data
+  }
+
+  async #handleLogout(pdu: IncomingPdu): Promise<void> {
+    const bhs = allocBhs(TargetOpcode.LOGOUT_RESPONSE)
+    bhs[1] = FLAG_FINAL
+    bhs[2] = LogoutResponse.SUCCESS
+    bhs.writeUInt32BE(pdu.itt, 16)
+    bhs.writeUInt32BE(this.#nextStatSN(), 24)
+    bhs.writeUInt32BE(this.#expCmdSN, 28)
+    bhs.writeUInt32BE(this.#maxCmdSN, 32)
+    await this.#send(assemblePdu(bhs))
+  }
+
+  async #handleScsiCommand(pdu: IncomingPdu): Promise<void> {
+    // Login declares ImmediateData=No unconditionally, so a data segment here is
+    // write data we never solicited and have no path to apply. Ignoring it would
+    // acknowledge a write missing its first bytes — exactly the silent loss the
+    // solicited path is built to avoid — so fail the command loudly instead and
+    // let the initiator retry or give up.
+    if (pdu.data.length > 0) {
+      log.warn('immediate data is not supported', { itt: pdu.itt, length: pdu.data.length })
+      const sense = buildFixedSense({ key: SenseKey.ILLEGAL_REQUEST, ...Asc.INVALID_FIELD_IN_CDB })
+      await this.sendScsiResponse(pdu.itt, ScsiStatus.CHECK_CONDITION, { sense })
+      return
+    }
+
+    const cdb = pdu.bhs.subarray(32, 48)
+    if (decodeCdb(cdb).kind === 'read') {
+      // Not awaited: the read loop must move on immediately rather than block on
+      // this `lun.read()`. See the class doc for why no extra ordering is needed.
+      void this.#readGate
+        .run(() => handleScsiCommand(cdb, pdu.itt, this, this.#deps.identity))
+        .catch(error => {
+          this.#fail(error)
+        })
+      return
+    }
+    await handleScsiCommand(cdb, pdu.itt, this, this.#deps.identity)
+  }
+
+  async #sendReject(pdu: IncomingPdu, reason: number): Promise<void> {
+    log.debug('rejecting PDU', { opcode: pdu.opcode, itt: pdu.itt, reason, phase: this.#phase })
+    const bhs = allocBhs(TargetOpcode.REJECT)
+    bhs[1] = FLAG_FINAL
+    bhs[2] = reason
+    bhs.writeUInt32BE(RESERVED_TAG, 16)
+    bhs.writeUInt32BE(this.#currentStatSN(), 24) // Reject snapshots StatSN
+    bhs.writeUInt32BE(this.#expCmdSN, 28)
+    bhs.writeUInt32BE(this.#maxCmdSN, 32)
+    // The rejected PDU's header is returned as the data segment.
+    await this.#send(assemblePdu(bhs, pdu.bhs))
+  }
+
+  // --- CommandContext implementation ----------------------------------------
+
+  async sendReadData(itt: number, data: Buffer, allocationLength: number): Promise<void> {
+    let payload = data
+    let residualOverflow = 0
+    let residualUnderflow = 0
+    if (data.length > allocationLength) {
+      payload = data.subarray(0, allocationLength)
+      residualOverflow = data.length - allocationLength
+    } else if (data.length < allocationLength) {
+      residualUnderflow = allocationLength - data.length
+    }
+
+    if (payload.length === 0) {
+      return this.sendScsiResponse(itt, ScsiStatus.GOOD, { residualOverflow, residualUnderflow })
+    }
+
+    const maxSegment = this.#params.initiatorMaxRecvDataSegmentLength
+    let offset = 0
+    let dataSN = 0
+    while (offset < payload.length) {
+      const end = Math.min(offset + maxSegment, payload.length)
+      const chunk = payload.subarray(offset, end)
+      const isLast = end >= payload.length
+
+      const bhs = allocBhs(TargetOpcode.SCSI_DATA_IN)
+      let flags = 0
+      if (isLast) {
+        // Piggyback GOOD status on the final Data-In PDU.
+        flags |= DATA_IN_FLAG_FINAL | DATA_IN_FLAG_STATUS
+        if (residualOverflow > 0) {
+          flags |= DATA_IN_FLAG_OVERFLOW
+        }
+        if (residualUnderflow > 0) {
+          flags |= DATA_IN_FLAG_UNDERFLOW
+        }
+        bhs[3] = ScsiStatus.GOOD // Status valid only when the S bit is set
+      }
+      bhs[1] = flags
+      bhs.writeUInt32BE(itt, 16)
+      bhs.writeUInt32BE(RESERVED_TAG, 20) // Target Transfer Tag
+      if (isLast) {
+        bhs.writeUInt32BE(this.#nextStatSN(), 24) // StatSN valid only with the S bit
+      }
+      bhs.writeUInt32BE(this.#expCmdSN, 28)
+      bhs.writeUInt32BE(this.#maxCmdSN, 32)
+      bhs.writeUInt32BE(dataSN, 36)
+      bhs.writeUInt32BE(offset, 40) // Buffer Offset
+      if (isLast) {
+        bhs.writeUInt32BE(residualOverflow || residualUnderflow, 44)
+      }
+      await this.#send(assemblePdu(bhs, chunk))
+
+      offset = end
+      dataSN++
+    }
+  }
+
+  async beginWrite(itt: number, lunOffset: number, totalLength: number): Promise<void> {
+    const pending: PendingWrite = {
+      itt,
+      targetTransferTag: this.#nextTargetTransferTag++,
+      lunOffset,
+      // zero-filled, not `allocUnsafe`: belt to `receiveDataOut`'s braces, so a
+      // buffer that somehow reaches the LUN partly filled writes zeroes rather
+      // than recycled heap (which the initiator could then read straight back)
+      buffer: Buffer.alloc(totalLength),
+      totalLength,
+      contiguousReceived: 0,
+      solicited: 0,
+      r2tSN: 0,
+    }
+    this.#pendingWrites.set(itt, pending)
+    log.debug('write begin', { itt, lunOffset, totalLength })
+    await this.#sendNextR2t(pending)
+  }
+
+  /** Solicit the next burst (≤ MaxBurstLength) of a pending write via an R2T. */
+  async #sendNextR2t(pending: PendingWrite): Promise<void> {
+    const desiredLength = Math.min(pending.totalLength - pending.solicited, this.#params.maxBurstLength)
+    const bufferOffset = pending.solicited
+    const r2tSN = pending.r2tSN
+    pending.solicited += desiredLength
+    pending.r2tSN++
+    await this.#send(
+      buildR2t(
+        { itt: pending.itt, r2tSN, targetTransferTag: pending.targetTransferTag, bufferOffset, desiredLength },
+        { statSN: this.#currentStatSN(), expCmdSN: this.#expCmdSN, maxCmdSN: this.#maxCmdSN }
+      )
+    )
+  }
+
+  async #handleDataOut(pdu: IncomingPdu): Promise<void> {
+    const pending = this.#pendingWrites.get(pdu.itt)
+    if (pending === undefined) {
+      // Data-Out for an unknown command: protocol desync.
+      await this.#sendReject(pdu, RejectReason.PROTOCOL_ERROR)
+      return
+    }
+    const bufferOffset = pdu.readU32(40) // BufferOffset is relative to the command's data
+    const outcome = receiveDataOut(pending, {
+      targetTransferTag: pdu.readU32(20),
+      bufferOffset,
+      data: pdu.data,
+    })
+    log.debug('write data-out', {
+      itt: pending.itt,
+      offset: bufferOffset,
+      length: pdu.data.length,
+      received: pending.contiguousReceived,
+      total: pending.totalLength,
+    })
+
+    if (!outcome.ok) {
+      // The command is dropped, not just the PDU: leaving it pending would hang
+      // the initiator on an R2T that never comes, until its command timeout.
+      this.#pendingWrites.delete(pdu.itt)
+      log.warn('unplaceable write data-out', { itt: pending.itt, reason: outcome.reason })
+      await this.#sendReject(pdu, RejectReason.PROTOCOL_ERROR)
+      return
+    }
+
+    if (outcome.complete) {
+      this.#pendingWrites.delete(pdu.itt)
+      try {
+        await this.lun.write(pending.lunOffset, pending.buffer)
+      } catch (error) {
+        log.warn('LUN write failed', error instanceof Error ? error : new Error(String(error)))
+        const sense = buildFixedSense({ key: SenseKey.MEDIUM_ERROR, ...Asc.NO_ADDITIONAL_SENSE })
+        await this.sendScsiResponse(pending.itt, ScsiStatus.CHECK_CONDITION, { sense })
+        return
+      }
+      await this.sendScsiResponse(pending.itt, ScsiStatus.GOOD)
+    } else if (outcome.burstComplete) {
+      // Current burst complete and data remains: solicit the next one.
+      await this.#sendNextR2t(pending)
+    }
+  }
+
+  async sendScsiResponse(itt: number, status: number, options: ScsiResponseOptions = {}): Promise<void> {
+    const { sense, residualOverflow = 0, residualUnderflow = 0 } = options
+
+    const bhs = allocBhs(TargetOpcode.SCSI_RESPONSE)
+    let flags = FLAG_FINAL // bit 7 is always set on a SCSI Response
+    if (residualOverflow > 0) {
+      flags |= SCSI_RESP_FLAG_OVERFLOW
+    }
+    if (residualUnderflow > 0) {
+      flags |= SCSI_RESP_FLAG_UNDERFLOW
+    }
+    bhs[1] = flags
+    bhs[2] = SCSI_RESPONSE_COMMAND_COMPLETED
+    bhs[3] = status
+    bhs.writeUInt32BE(itt, 16)
+    bhs.writeUInt32BE(this.#nextStatSN(), 24)
+    bhs.writeUInt32BE(this.#expCmdSN, 28)
+    bhs.writeUInt32BE(this.#maxCmdSN, 32)
+    bhs.writeUInt32BE(residualOverflow || residualUnderflow, 44)
+
+    let data: Buffer | undefined
+    if (sense !== undefined) {
+      // Sense data in a SCSI Response is prefixed with a 2-byte length.
+      data = Buffer.alloc(2 + sense.length)
+      data.writeUInt16BE(sense.length, 0)
+      sense.copy(data, 2)
+    }
+    await this.#send(assemblePdu(bhs, data))
+  }
+}

@vates/iscsi/src/connection.test.mts

@@ -0,0 +1,712 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import type { Socket } from 'node:net'
+import { Duplex } from 'node:stream'
+
+import type { BlockDevice } from './backend.mjs'
+import {
+  DATA_IN_FLAG_FINAL,
+  DATA_IN_FLAG_OVERFLOW,
+  DATA_IN_FLAG_STATUS,
+  DATA_IN_FLAG_UNDERFLOW,
+  FLAG_FINAL,
+  InitiatorOpcode,
+  LOGIN_CSG_SHIFT,
+  LOGIN_FLAG_TRANSIT,
+  LoginStage,
+  LoginStatusClass,
+  OPCODE_IMMEDIATE,
+  RejectReason,
+  RESERVED_TAG,
+  ScsiStatus,
+  SenseKey,
+  TargetOpcode,
+} from './constants.mjs'
+import { Connection, type ConnectionDeps } from './connection.mjs'
+import { serializeTextKeys } from './login.mjs'
+import { assemblePdu, IncomingPdu } from './pdu.mjs'
+import type { ScsiIdentity } from './scsi.mjs'
+
+const IDENTITY: ScsiIdentity = { vendor: 'VATES', product: 'ISCSI LUN', revision: '0001', serial: 'unit-serial-1' }
+const BLOCK_SIZE = 512
+const LUN_SIZE = 16 * BLOCK_SIZE
+
+// Small enough that a handful of blocks splits into several PDUs / bursts, so
+// the chunking and multi-burst paths are exercised without huge buffers.
+const MAX_RECV_DATA_SEGMENT_LENGTH = 512
+const MAX_BURST_LENGTH = 512
+
+// --- test doubles -----------------------------------------------------------
+
+/**
+ * Stands in for the TCP socket. `deliver()` queues a PDU for the connection's
+ * read loop (the readable side); everything the connection writes is captured
+ * in `sent` rather than transmitted. `Connection` only ever reads, writes, and
+ * destroys its socket, plus `localAddress`/`localPort` for SendTargets — hence
+ * the narrow cast in `asSocket()`.
+ */
+class FakeSocket extends Duplex {
+  readonly sent: Array<Buffer> = []
+  readonly localAddress = '10.0.0.1'
+  readonly localPort = 3260
+
+  override _read(): void {}
+
+  override _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    this.sent.push(Buffer.from(chunk))
+    callback()
+  }
+
+  /** Hand a PDU to the connection. */
+  deliver(pdu: Buffer): void {
+    this.push(pdu)
+  }
+
+  /** Clean end-of-stream, which ends `serve()`'s read loop. */
+  finish(): void {
+    this.push(null)
+  }
+
+  asSocket(): Socket {
+    return this as unknown as Socket
+  }
+}
+
+class MemoryLun implements BlockDevice {
+  readonly content = Buffer.alloc(LUN_SIZE)
+  /** Set to make the next `write()` fail, standing in for a backend error. */
+  failNextWrite = false
+
+  getSize(): number {
+    return this.content.length
+  }
+  getBlockSize(): number {
+    return BLOCK_SIZE
+  }
+  async read(offset: number, length: number): Promise<Buffer> {
+    return Buffer.from(this.content.subarray(offset, offset + length))
+  }
+  async write(offset: number, data: Buffer): Promise<void> {
+    if (this.failNextWrite) {
+      this.failNextWrite = false
+      throw new Error('backend write failed')
+    }
+    data.copy(this.content, offset)
+  }
+  async flush(): Promise<void> {}
+  async close(): Promise<void> {}
+}
+
+// --- initiator-side PDU builders --------------------------------------------
+
+/** A single-PDU operational login that transits straight to Full Feature Phase. */
+const loginPdu = (): Buffer => {
+  const bhs = Buffer.alloc(48)
+  bhs[0] = InitiatorOpcode.LOGIN_REQUEST | OPCODE_IMMEDIATE
+  bhs[1] = LOGIN_FLAG_TRANSIT | (LoginStage.OPERATIONAL_NEGOTIATION << LOGIN_CSG_SHIFT) | LoginStage.FULL_FEATURE_PHASE
+  bhs.writeUInt32BE(1, 16) // ITT
+  return assemblePdu(
+    bhs,
+    serializeTextKeys([
+      ['InitiatorName', 'iqn.2026-01.tech.vates:test-initiator'],
+      ['SessionType', 'Normal'],
+      ['HeaderDigest', 'None'],
+      ['DataDigest', 'None'],
+      ['MaxRecvDataSegmentLength', String(MAX_RECV_DATA_SEGMENT_LENGTH)],
+      ['MaxBurstLength', String(MAX_BURST_LENGTH)],
+    ])
+  )
+}
+
+const scsiCommandPdu = ({
+  itt,
+  cmdSN,
+  cdb,
+  data,
+}: {
+  itt: number
+  cmdSN: number
+  cdb: Buffer
+  data?: Buffer
+}): Buffer => {
+  const bhs = Buffer.alloc(48)
+  bhs[0] = InitiatorOpcode.SCSI_COMMAND
+  bhs[1] = FLAG_FINAL
+  bhs.writeUInt32BE(itt, 16)
+  bhs.writeUInt32BE(cmdSN, 24)
+  cdb.copy(bhs, 32)
+  return assemblePdu(bhs, data)
+}
+
+const dataOutPdu = ({
+  itt,
+  targetTransferTag,
+  bufferOffset,
+  data,
+  dataSN = 0,
+}: {
+  itt: number
+  targetTransferTag: number
+  bufferOffset: number
+  data: Buffer
+  dataSN?: number
+}): Buffer => {
+  const bhs = Buffer.alloc(48)
+  bhs[0] = InitiatorOpcode.SCSI_DATA_OUT
+  bhs[1] = FLAG_FINAL
+  bhs.writeUInt32BE(itt, 16)
+  bhs.writeUInt32BE(targetTransferTag, 20)
+  bhs.writeUInt32BE(dataSN, 36)
+  bhs.writeUInt32BE(bufferOffset, 40)
+  return assemblePdu(bhs, data)
+}
+
+const cdb10 = (opcode: number, lba: number, blocks: number): Buffer => {
+  const cdb = Buffer.alloc(16)
+  cdb[0] = opcode
+  cdb.writeUInt32BE(lba, 2)
+  cdb.writeUInt16BE(blocks, 7)
+  return cdb
+}
+const read10 = (lba: number, blocks: number) => cdb10(0x28, lba, blocks)
+const write10 = (lba: number, blocks: number) => cdb10(0x2a, lba, blocks)
+
+const cdb16 = (opcode: number, lba: bigint, blocks: number): Buffer => {
+  const cdb = Buffer.alloc(16)
+  cdb[0] = opcode
+  cdb.writeBigUInt64BE(lba, 2)
+  cdb.writeUInt32BE(blocks, 10)
+  return cdb
+}
+const read16 = (lba: bigint, blocks: number) => cdb16(0x88, lba, blocks)
+const write16 = (lba: bigint, blocks: number) => cdb16(0x8a, lba, blocks)
+
+const inquiry = (allocationLength: number): Buffer => {
+  const cdb = Buffer.alloc(16)
+  cdb[0] = 0x12
+  cdb.writeUInt16BE(allocationLength, 3)
+  return cdb
+}
+
+// --- harness ----------------------------------------------------------------
+
+/** Re-read a PDU the target sent, so assertions can talk in field names. */
+const parseSent = (buffer: Buffer): IncomingPdu => {
+  const dataSegmentLength = buffer.readUIntBE(5, 3)
+  return new IncomingPdu(buffer.subarray(0, 48), Buffer.alloc(0), buffer.subarray(48, 48 + dataSegmentLength))
+}
+
+/**
+ * Sense key of a SCSI Response: its data segment is a 2-byte sense length then
+ * the fixed-format sense data, whose byte 2 holds the key in its low nibble.
+ */
+const senseKey = (response: IncomingPdu): number => response.data[4] & 0x0f
+
+class Harness {
+  readonly socket = new FakeSocket()
+  readonly lun = new MemoryLun()
+  readonly serving: Promise<void>
+
+  constructor(overrides: Partial<ConnectionDeps> = {}) {
+    const deps: ConnectionDeps = {
+      iqn: 'iqn.2026-01.tech.vates:target',
+      identity: IDENTITY,
+      lun: this.lun,
+      writeTimeoutMs: 0,
+      cmdWindow: 64,
+      readConcurrency: 4,
+      allocateTsih: () => 1,
+      ...overrides,
+    }
+    this.serving = new Connection(this.socket.asSocket(), deps).serve()
+  }
+
+  /** Every PDU the target has sent, parsed. */
+  get sent(): Array<IncomingPdu> {
+    return this.socket.sent.map(parseSent)
+  }
+
+  /**
+   * Let the read loop run until the target has sent `count` PDUs in total,
+   * optionally delivering something first. Bounded so a response that never
+   * comes fails the test instead of hanging it.
+   */
+  async untilSent(count: number, deliver?: () => void): Promise<Array<IncomingPdu>> {
+    deliver?.()
+    for (let turn = 0; turn < 500 && this.socket.sent.length < count; turn++) {
+      await new Promise(resolve => setImmediate(resolve))
+    }
+    const sent = this.sent
+    assert.ok(
+      sent.length >= count,
+      `expected ${count} PDUs, got ${sent.length}: ${sent.map(pdu => pdu.opcode.toString(16)).join(',')}`
+    )
+    return sent
+  }
+
+  /** Log in and confirm the target accepted it. */
+  async login(): Promise<void> {
+    // relative to what has already been sent, so this works mid-connection too
+    const baseline = this.socket.sent.length
+    const response = (await this.untilSent(baseline + 1, () => this.socket.deliver(loginPdu())))[baseline]
+    assert.equal(response.opcode, TargetOpcode.LOGIN_RESPONSE)
+    assert.equal(response.readU8(36), LoginStatusClass.SUCCESS)
+  }
+
+  async close(): Promise<void> {
+    this.socket.finish()
+    await this.serving
+  }
+}
+
+/** Log in, then run `body`, always tearing the connection down afterwards. */
+const withSession = async (body: (harness: Harness) => Promise<void>, overrides?: Partial<ConnectionDeps>) => {
+  const harness = new Harness(overrides)
+  try {
+    await harness.login()
+    await body(harness)
+  } finally {
+    await harness.close()
+  }
+}
+
+const CMD_WINDOW = 64
+/** ExpCmdSN (bytes 28-31) and MaxCmdSN (32-35), the command window we advertise. */
+const commandWindow = (pdu: IncomingPdu) => ({ expCmdSN: pdu.readU32(28), maxCmdSN: pdu.readU32(32) })
+
+describe('command window', () => {
+  // Bytes 24-27 are CmdSN only on command PDUs. On a Data-Out (RFC 7143 §11.7)
+  // and a SNACK they are reserved, so reading a window out of them yields the
+  // zeroes an initiator puts there — advertising ExpCmdSN=1 mid-session. Real
+  // initiators discard that as stale only while session CmdSN < 2^31; past the
+  // wrap it compares as newer, is adopted, and the window collapses to a stall.
+  it('is not recomputed from the reserved bytes of a Data-Out', async () => {
+    await withSession(async harness => {
+      // two bursts, so an R2T is emitted *after* a Data-Out has been processed
+      harness.socket.deliver(scsiCommandPdu({ itt: 31, cmdSN: 50, cdb: write10(0, 2) }))
+      const [, firstR2t] = await harness.untilSent(2)
+      const expected = { expCmdSN: 51, maxCmdSN: 51 + CMD_WINDOW }
+      assert.deepEqual(commandWindow(firstR2t), expected)
+
+      const ttt = firstR2t.readU32(20)
+      harness.socket.deliver(
+        dataOutPdu({ itt: 31, targetTransferTag: ttt, bufferOffset: 0, data: Buffer.alloc(BLOCK_SIZE, 0x11) })
+      )
+
+      const [, , secondR2t] = await harness.untilSent(3)
+      assert.equal(secondR2t.opcode, TargetOpcode.R2T)
+      assert.deepEqual(commandWindow(secondR2t), expected)
+
+      harness.socket.deliver(
+        dataOutPdu({
+          itt: 31,
+          targetTransferTag: ttt,
+          bufferOffset: BLOCK_SIZE,
+          data: Buffer.alloc(BLOCK_SIZE, 0x22),
+          dataSN: 1,
+        })
+      )
+
+      const [, , , response] = await harness.untilSent(4)
+      assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+      assert.deepEqual(commandWindow(response), expected)
+    })
+  })
+
+  it('is not recomputed from an opcode the target does not implement', async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(scsiCommandPdu({ itt: 33, cmdSN: 70, cdb: read10(0, 1) }))
+      const [, dataIn] = await harness.untilSent(2)
+      const expected = { expCmdSN: 71, maxCmdSN: 71 + CMD_WINDOW }
+      assert.deepEqual(commandWindow(dataIn), expected)
+
+      // SNACK also has bytes 24-27 reserved; it is rejected, but the Reject it
+      // gets must still carry the window the session actually reached
+      const bhs = Buffer.alloc(48)
+      bhs[0] = InitiatorOpcode.SNACK_REQUEST
+      harness.socket.deliver(assemblePdu(bhs))
+
+      const [, , rejected] = await harness.untilSent(3)
+      assert.equal(rejected.opcode, TargetOpcode.REJECT)
+      assert.equal(rejected.readU8(2), RejectReason.COMMAND_NOT_SUPPORTED)
+      assert.deepEqual(commandWindow(rejected), expected)
+    })
+  })
+
+  it('advances the window for each command PDU, but not for an immediate one', async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(scsiCommandPdu({ itt: 35, cmdSN: 5, cdb: read10(0, 1) }))
+      const [, dataIn] = await harness.untilSent(2)
+      assert.deepEqual(commandWindow(dataIn), { expCmdSN: 6, maxCmdSN: 6 + CMD_WINDOW })
+
+      // an immediate NOP-Out is answered but consumes no CmdSN slot
+      const bhs = Buffer.alloc(48)
+      bhs[0] = InitiatorOpcode.NOP_OUT | OPCODE_IMMEDIATE
+      bhs[1] = FLAG_FINAL
+      bhs.writeUInt32BE(37, 16)
+      bhs.writeUInt32BE(RESERVED_TAG, 20)
+      bhs.writeUInt32BE(6, 24)
+      harness.socket.deliver(assemblePdu(bhs))
+
+      const [, , nopIn] = await harness.untilSent(3)
+      assert.equal(nopIn.opcode, TargetOpcode.NOP_IN)
+      assert.deepEqual(commandWindow(nopIn), { expCmdSN: 6, maxCmdSN: 6 + CMD_WINDOW })
+    })
+  })
+})
+
+describe('login', () => {
+  it('reaches full feature phase and only then accepts commands', async () => {
+    const harness = new Harness()
+    try {
+      // a command before login is a protocol error, not a served command
+      harness.socket.deliver(scsiCommandPdu({ itt: 5, cmdSN: 0, cdb: read10(0, 1) }))
+      const [rejected] = await harness.untilSent(1)
+      assert.equal(rejected.opcode, TargetOpcode.REJECT)
+      assert.equal(rejected.readU8(2), RejectReason.PROTOCOL_ERROR)
+
+      await harness.login()
+
+      // the same command now gets served
+      harness.socket.deliver(scsiCommandPdu({ itt: 5, cmdSN: 1, cdb: read10(0, 1) }))
+      const sent = await harness.untilSent(3)
+      assert.equal(sent[2].opcode, TargetOpcode.SCSI_DATA_IN)
+    } finally {
+      await harness.close()
+    }
+  })
+})
+
+describe('write path wiring', () => {
+  it('solicits the data, commits it to the LUN, and answers GOOD', async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(scsiCommandPdu({ itt: 9, cmdSN: 1, cdb: write10(2, 1) }))
+
+      const [, r2t] = await harness.untilSent(2)
+      assert.equal(r2t.opcode, TargetOpcode.R2T)
+      assert.equal(r2t.itt, 9)
+      assert.equal(r2t.readU32(36), 0) // R2TSN
+      assert.equal(r2t.readU32(40), 0) // BufferOffset
+      assert.equal(r2t.readU32(44), BLOCK_SIZE) // DesiredDataTransferLength
+
+      const payload = Buffer.alloc(BLOCK_SIZE, 0xab)
+      harness.socket.deliver(dataOutPdu({ itt: 9, targetTransferTag: r2t.readU32(20), bufferOffset: 0, data: payload }))
+
+      const [, , response] = await harness.untilSent(3)
+      assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+      assert.equal(response.readU8(3), ScsiStatus.GOOD)
+      // ... and the bytes landed at the LBA the CDB asked for, nowhere else
+      assert.deepEqual(harness.lun.content.subarray(2 * BLOCK_SIZE, 3 * BLOCK_SIZE), payload)
+      assert.deepEqual(harness.lun.content.subarray(0, 2 * BLOCK_SIZE), Buffer.alloc(2 * BLOCK_SIZE))
+      assert.deepEqual(harness.lun.content.subarray(3 * BLOCK_SIZE), Buffer.alloc(LUN_SIZE - 3 * BLOCK_SIZE))
+    })
+  })
+
+  it('solicits one burst at a time for a write larger than MaxBurstLength', async () => {
+    await withSession(async harness => {
+      // 2 blocks with a 1-block burst limit: two R2Ts, second only after the first lands
+      harness.socket.deliver(scsiCommandPdu({ itt: 11, cmdSN: 1, cdb: write10(0, 2) }))
+
+      const [, first] = await harness.untilSent(2)
+      assert.equal(first.readU32(36), 0) // R2TSN
+      assert.equal(first.readU32(40), 0) // BufferOffset
+      assert.equal(first.readU32(44), MAX_BURST_LENGTH)
+
+      const ttt = first.readU32(20)
+      harness.socket.deliver(
+        dataOutPdu({ itt: 11, targetTransferTag: ttt, bufferOffset: 0, data: Buffer.alloc(BLOCK_SIZE, 0x11) })
+      )
+
+      const [, , second] = await harness.untilSent(3)
+      assert.equal(second.opcode, TargetOpcode.R2T)
+      assert.equal(second.readU32(36), 1) // R2TSN advanced
+      assert.equal(second.readU32(40), BLOCK_SIZE) // next burst picks up where the first ended
+      assert.equal(second.readU32(44), MAX_BURST_LENGTH)
+      // nothing is committed until the whole command has landed
+      assert.deepEqual(harness.lun.content.subarray(0, BLOCK_SIZE), Buffer.alloc(BLOCK_SIZE))
+
+      harness.socket.deliver(
+        dataOutPdu({
+          itt: 11,
+          targetTransferTag: ttt,
+          bufferOffset: BLOCK_SIZE,
+          data: Buffer.alloc(BLOCK_SIZE, 0x22),
+          dataSN: 1,
+        })
+      )
+
+      const [, , , response] = await harness.untilSent(4)
+      assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+      assert.equal(response.readU8(3), ScsiStatus.GOOD)
+      assert.deepEqual(
+        harness.lun.content.subarray(0, 2 * BLOCK_SIZE),
+        Buffer.concat([Buffer.alloc(BLOCK_SIZE, 0x11), Buffer.alloc(BLOCK_SIZE, 0x22)])
+      )
+    })
+  })
+
+  it('rejects an unplaceable Data-Out and drops the command with it', async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(scsiCommandPdu({ itt: 13, cmdSN: 1, cdb: write10(0, 1) }))
+      const [, r2t] = await harness.untilSent(2)
+      const ttt = r2t.readU32(20)
+
+      // BufferOffset past the end of the command's data: a copy there would land
+      // nothing, so the write must be refused rather than acknowledged
+      harness.socket.deliver(
+        dataOutPdu({
+          itt: 13,
+          targetTransferTag: ttt,
+          bufferOffset: BLOCK_SIZE,
+          data: Buffer.alloc(BLOCK_SIZE, 0xcc),
+        })
+      )
+
+      const [, , rejected] = await harness.untilSent(3)
+      assert.equal(rejected.opcode, TargetOpcode.REJECT)
+      assert.equal(rejected.readU8(2), RejectReason.PROTOCOL_ERROR)
+      assert.deepEqual(harness.lun.content, Buffer.alloc(LUN_SIZE))
+
+      // the command is gone, not merely stalled: a now-valid Data-Out for it is
+      // an unknown ITT, and no SCSI Response ever completes it
+      harness.socket.deliver(
+        dataOutPdu({ itt: 13, targetTransferTag: ttt, bufferOffset: 0, data: Buffer.alloc(BLOCK_SIZE, 0xdd) })
+      )
+      const sent = await harness.untilSent(4)
+      assert.equal(sent[3].opcode, TargetOpcode.REJECT)
+      assert.deepEqual(harness.lun.content, Buffer.alloc(LUN_SIZE))
+      assert.equal(
+        sent.some(pdu => pdu.opcode === TargetOpcode.SCSI_RESPONSE),
+        false
+      )
+    })
+  })
+
+  it("rejects a Data-Out carrying another command's Target Transfer Tag", async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(scsiCommandPdu({ itt: 15, cmdSN: 1, cdb: write10(0, 1) }))
+      const [, r2t] = await harness.untilSent(2)
+
+      harness.socket.deliver(
+        dataOutPdu({
+          itt: 15,
+          targetTransferTag: r2t.readU32(20) + 1,
+          bufferOffset: 0,
+          data: Buffer.alloc(BLOCK_SIZE, 0xee),
+        })
+      )
+
+      const [, , rejected] = await harness.untilSent(3)
+      assert.equal(rejected.opcode, TargetOpcode.REJECT)
+      assert.deepEqual(harness.lun.content, Buffer.alloc(LUN_SIZE))
+    })
+  })
+
+  it('rejects a Data-Out for a command it knows nothing about', async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(
+        dataOutPdu({ itt: 404, targetTransferTag: 1, bufferOffset: 0, data: Buffer.alloc(BLOCK_SIZE, 0xff) })
+      )
+
+      const [, rejected] = await harness.untilSent(2)
+      assert.equal(rejected.opcode, TargetOpcode.REJECT)
+      assert.equal(rejected.readU8(2), RejectReason.PROTOCOL_ERROR)
+    })
+  })
+
+  it('reports a failed backend write as CHECK CONDITION, not a dropped connection', async () => {
+    await withSession(async harness => {
+      harness.lun.failNextWrite = true
+      harness.socket.deliver(scsiCommandPdu({ itt: 17, cmdSN: 1, cdb: write10(0, 1) }))
+      const [, r2t] = await harness.untilSent(2)
+
+      harness.socket.deliver(
+        dataOutPdu({
+          itt: 17,
+          targetTransferTag: r2t.readU32(20),
+          bufferOffset: 0,
+          data: Buffer.alloc(BLOCK_SIZE, 0xab),
+        })
+      )
+
+      const [, , response] = await harness.untilSent(3)
+      assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+      assert.equal(response.readU8(3), ScsiStatus.CHECK_CONDITION)
+      assert.equal(senseKey(response), SenseKey.MEDIUM_ERROR)
+    })
+  })
+
+  it('fails a command carrying immediate data instead of silently dropping it', async () => {
+    await withSession(async harness => {
+      // ImmediateData=No is declared at login, so this cannot be honoured — and
+      // must not be ignored either, since the write would be short by these bytes
+      harness.socket.deliver(
+        scsiCommandPdu({ itt: 19, cmdSN: 1, cdb: write10(0, 1), data: Buffer.alloc(BLOCK_SIZE, 0x99) })
+      )
+
+      const [, response] = await harness.untilSent(2)
+      assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+      assert.equal(response.readU8(3), ScsiStatus.CHECK_CONDITION)
+      assert.equal(senseKey(response), SenseKey.ILLEGAL_REQUEST)
+      assert.deepEqual(harness.lun.content, Buffer.alloc(LUN_SIZE))
+      // no R2T either: the command never started
+      assert.equal(
+        harness.sent.some(pdu => pdu.opcode === TargetOpcode.R2T),
+        false
+      )
+    })
+  })
+})
+
+describe('Data-In chunking', () => {
+  /** Read `blocks` blocks of a LUN pre-filled with a recognizable pattern. */
+  const readBack = async (harness: Harness, blocks: number): Promise<Array<IncomingPdu>> => {
+    for (let i = 0; i < harness.lun.content.length; i++) {
+      harness.lun.content[i] = (i * 7 + 3) & 0xff
+    }
+    harness.socket.deliver(scsiCommandPdu({ itt: 21, cmdSN: 1, cdb: read10(0, blocks) }))
+    const expected = Math.ceil((blocks * BLOCK_SIZE) / MAX_RECV_DATA_SEGMENT_LENGTH)
+    const sent = await harness.untilSent(1 + expected)
+    return sent.slice(1)
+  }
+
+  it('splits the payload at the initiator MaxRecvDataSegmentLength', async () => {
+    await withSession(async harness => {
+      const dataIn = await readBack(harness, 4)
+
+      assert.equal(dataIn.length, 4)
+      for (const pdu of dataIn) {
+        assert.equal(pdu.opcode, TargetOpcode.SCSI_DATA_IN)
+        assert.equal(pdu.data.length, MAX_RECV_DATA_SEGMENT_LENGTH)
+      }
+      // reassembled, it is exactly what the LUN holds
+      assert.deepEqual(Buffer.concat(dataIn.map(pdu => pdu.data)), harness.lun.content.subarray(0, 4 * BLOCK_SIZE))
+    })
+  })
+
+  it('numbers the PDUs with a gapless DataSN and stamps each BufferOffset', async () => {
+    await withSession(async harness => {
+      const dataIn = await readBack(harness, 3)
+
+      assert.deepEqual(
+        dataIn.map(pdu => pdu.readU32(36)),
+        [0, 1, 2]
+      )
+      assert.deepEqual(
+        dataIn.map(pdu => pdu.readU32(40)),
+        [0, MAX_RECV_DATA_SEGMENT_LENGTH, 2 * MAX_RECV_DATA_SEGMENT_LENGTH]
+      )
+      // Target Transfer Tag is unused on Data-In
+      for (const pdu of dataIn) {
+        assert.equal(pdu.readU32(20), RESERVED_TAG)
+      }
+    })
+  })
+
+  it('carries the status only on the final PDU, and advances StatSN once', async () => {
+    await withSession(async harness => {
+      const statSNAfterLogin = parseSent(harness.socket.sent[0]).readU32(24) + 1
+      const dataIn = await readBack(harness, 3)
+
+      for (const pdu of dataIn.slice(0, -1)) {
+        assert.equal(pdu.flags & DATA_IN_FLAG_FINAL, 0)
+        assert.equal(pdu.flags & DATA_IN_FLAG_STATUS, 0)
+        // both fields are defined as meaningless without the S bit, and are left
+        // unset rather than filled with a value an initiator might act on
+        assert.equal(pdu.readU8(3), 0)
+        assert.equal(pdu.readU32(24), 0)
+      }
+
+      const last = dataIn[dataIn.length - 1]
+      assert.equal(last.flags & DATA_IN_FLAG_FINAL, DATA_IN_FLAG_FINAL)
+      assert.equal(last.flags & DATA_IN_FLAG_STATUS, DATA_IN_FLAG_STATUS)
+      assert.equal(last.readU8(3), ScsiStatus.GOOD)
+      // exactly one StatSN consumed for the whole command, on its final PDU
+      assert.equal(last.readU32(24), statSNAfterLogin)
+    })
+  })
+
+  it('sends a single Data-In when the payload fits one segment', async () => {
+    await withSession(async harness => {
+      const dataIn = await readBack(harness, 1)
+
+      assert.equal(dataIn.length, 1)
+      assert.equal(
+        dataIn[0].flags & (DATA_IN_FLAG_FINAL | DATA_IN_FLAG_STATUS),
+        DATA_IN_FLAG_FINAL | DATA_IN_FLAG_STATUS
+      )
+      assert.equal(dataIn[0].readU32(36), 0)
+    })
+  })
+
+  it('flags residual overflow when the allocation length truncates the payload', async () => {
+    await withSession(async harness => {
+      // standard INQUIRY data is 36 bytes; ask for 8
+      harness.socket.deliver(scsiCommandPdu({ itt: 23, cmdSN: 1, cdb: inquiry(8) }))
+
+      const [, dataIn] = await harness.untilSent(2)
+      assert.equal(dataIn.opcode, TargetOpcode.SCSI_DATA_IN)
+      assert.equal(dataIn.data.length, 8)
+      assert.equal(dataIn.flags & DATA_IN_FLAG_OVERFLOW, DATA_IN_FLAG_OVERFLOW)
+      assert.equal(dataIn.flags & DATA_IN_FLAG_UNDERFLOW, 0)
+      assert.equal(dataIn.readU32(44), 36 - 8) // Residual Count
+    })
+  })
+
+  it('flags residual underflow when the payload is shorter than requested', async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(scsiCommandPdu({ itt: 25, cmdSN: 1, cdb: inquiry(100) }))
+
+      const [, dataIn] = await harness.untilSent(2)
+      assert.equal(dataIn.data.length, 36)
+      assert.equal(dataIn.flags & DATA_IN_FLAG_UNDERFLOW, DATA_IN_FLAG_UNDERFLOW)
+      assert.equal(dataIn.flags & DATA_IN_FLAG_OVERFLOW, 0)
+      assert.equal(dataIn.readU32(44), 100 - 36)
+    })
+  })
+
+  it('answers with status alone, no Data-In, when nothing is allocated for the data', async () => {
+    await withSession(async harness => {
+      harness.socket.deliver(scsiCommandPdu({ itt: 27, cmdSN: 1, cdb: inquiry(0) }))
+
+      const [, response] = await harness.untilSent(2)
+      assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+      assert.equal(response.readU8(3), ScsiStatus.GOOD)
+      assert.equal(
+        harness.sent.some(pdu => pdu.opcode === TargetOpcode.SCSI_DATA_IN),
+        false
+      )
+    })
+  })
+})
+
+describe('unservable CDBs', () => {
+  // An LBA above 2^53 cannot be held exactly by a JS number. Decoding it must
+  // not throw: the error would unwind out of the dispatch loop and destroy the
+  // socket, turning one bogus CDB — a buggy or hostile initiator's — into the
+  // loss of the whole session and every command in flight on it.
+  for (const [name, cdb] of [
+    ['READ(16)', read16(0xffffffffffffffffn, 1)],
+    ['WRITE(16)', write16(0xffffffffffffffffn, 1)],
+  ] as const) {
+    it(`answers a ${name} past the addressable range with CHECK CONDITION, keeping the session`, async () => {
+      await withSession(async harness => {
+        harness.socket.deliver(scsiCommandPdu({ itt: 31, cmdSN: 1, cdb }))
+
+        const [, response] = await harness.untilSent(2)
+        assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+        assert.equal(response.readU8(3), ScsiStatus.CHECK_CONDITION)
+        assert.equal(senseKey(response), SenseKey.ILLEGAL_REQUEST)
+        assert.equal(
+          harness.sent.some(pdu => pdu.opcode === TargetOpcode.R2T),
+          false
+        )
+
+        // the connection is still serving: a following command is answered
+        harness.socket.deliver(scsiCommandPdu({ itt: 32, cmdSN: 2, cdb: inquiry(36) }))
+        const [, , dataIn] = await harness.untilSent(3)
+        assert.equal(dataIn.opcode, TargetOpcode.SCSI_DATA_IN)
+      })
+    })
+  }
+})

@vates/iscsi/src/constants.mts

@@ -0,0 +1,198 @@
+// iSCSI (RFC 7143 / RFC 3720) and SCSI (SPC-3 / SBC-3) protocol constants.
+//
+// Only the subset required by a minimal single-LUN target is defined here.
+
+// --- iSCSI PDU layout -------------------------------------------------------
+
+/** Length of the Basic Header Segment, in bytes. Fixed by the protocol. */
+export const BHS_LENGTH = 48
+
+/** Bit set in byte 0 for initiator PDUs that must be processed immediately. */
+export const OPCODE_IMMEDIATE = 0x40
+
+/** Mask extracting the 6-bit opcode from byte 0. */
+export const OPCODE_MASK = 0x3f
+
+/** Final bit, byte 1, set on the last PDU of a sequence. */
+export const FLAG_FINAL = 0x80
+
+/** Sentinel for "no tag" in Initiator/Target Task Tag fields. */
+export const RESERVED_TAG = 0xffffffff
+
+// --- iSCSI opcodes ----------------------------------------------------------
+
+/** Opcodes sent by the initiator (request PDUs). */
+export const InitiatorOpcode = {
+  NOP_OUT: 0x00,
+  SCSI_COMMAND: 0x01,
+  SCSI_TASK_MGMT_REQUEST: 0x02,
+  LOGIN_REQUEST: 0x03,
+  TEXT_REQUEST: 0x04,
+  SCSI_DATA_OUT: 0x05,
+  LOGOUT_REQUEST: 0x06,
+  SNACK_REQUEST: 0x10,
+} as const
+
+/** Opcodes sent by the target (response PDUs). */
+export const TargetOpcode = {
+  NOP_IN: 0x20,
+  SCSI_RESPONSE: 0x21,
+  SCSI_TASK_MGMT_RESPONSE: 0x22,
+  LOGIN_RESPONSE: 0x23,
+  TEXT_RESPONSE: 0x24,
+  SCSI_DATA_IN: 0x25,
+  LOGOUT_RESPONSE: 0x26,
+  R2T: 0x31,
+  ASYNC_MESSAGE: 0x32,
+  REJECT: 0x3f,
+} as const
+
+// --- Login negotiation ------------------------------------------------------
+
+/** Login/text stage codes used in the CSG/NSG fields. */
+export const LoginStage = {
+  SECURITY_NEGOTIATION: 0,
+  OPERATIONAL_NEGOTIATION: 1,
+  FULL_FEATURE_PHASE: 3,
+} as const
+
+/** Login Request/Response byte 1 flags. */
+export const LOGIN_FLAG_TRANSIT = 0x80
+export const LOGIN_FLAG_CONTINUE = 0x40
+/** Mask + shift for the Current Stage (CSG) field in byte 1. */
+export const LOGIN_CSG_MASK = 0x0c
+export const LOGIN_CSG_SHIFT = 2
+/** Mask for the Next Stage (NSG) field in byte 1. */
+export const LOGIN_NSG_MASK = 0x03
+
+/** iSCSI version (only version 0 exists). */
+export const ISCSI_VERSION = 0x00
+
+/** Login Response Status-Class values. */
+export const LoginStatusClass = {
+  SUCCESS: 0x00,
+  REDIRECTION: 0x01,
+  INITIATOR_ERROR: 0x02,
+  TARGET_ERROR: 0x03,
+} as const
+
+/**
+ * Login Response Status-Detail values (byte 37), qualifying the Status-Class.
+ * `AUTHENTICATION_FAILURE` pairs with `INITIATOR_ERROR` to reject a bad CHAP
+ * login (RFC 7143 §11.1.5).
+ */
+export const LoginStatusDetail = {
+  SUCCESS: 0x00,
+  AUTHENTICATION_FAILURE: 0x01,
+} as const
+
+/** `AuthMethod` login-key values we understand (RFC 7143 §12.1). */
+export const AuthMethod = {
+  NONE: 'None',
+  CHAP: 'CHAP',
+} as const
+
+// --- Text/Data flags --------------------------------------------------------
+
+export const TEXT_FLAG_FINAL = 0x80
+export const TEXT_FLAG_CONTINUE = 0x40
+
+/** SCSI Data-In byte 1 flags. */
+export const DATA_IN_FLAG_FINAL = 0x80
+export const DATA_IN_FLAG_ACK = 0x40
+export const DATA_IN_FLAG_OVERFLOW = 0x04
+export const DATA_IN_FLAG_UNDERFLOW = 0x02
+export const DATA_IN_FLAG_STATUS = 0x01
+
+/** SCSI Command (initiator) byte 1 flags. */
+export const SCSI_CMD_FLAG_READ = 0x40
+export const SCSI_CMD_FLAG_WRITE = 0x20
+
+/** SCSI Response byte 1 residual flags. */
+export const SCSI_RESP_FLAG_OVERFLOW = 0x04
+export const SCSI_RESP_FLAG_UNDERFLOW = 0x02
+
+/** SCSI Response "Response" field (byte 2). */
+export const SCSI_RESPONSE_COMMAND_COMPLETED = 0x00
+
+/** Logout reason codes (byte 1, low 7 bits). */
+export const LogoutReason = {
+  CLOSE_SESSION: 0,
+  CLOSE_CONNECTION: 1,
+  REMOVE_CONNECTION_FOR_RECOVERY: 2,
+} as const
+
+/** Logout Response codes (byte 2). */
+export const LogoutResponse = {
+  SUCCESS: 0,
+} as const
+
+// --- SCSI status codes ------------------------------------------------------
+
+export const ScsiStatus = {
+  GOOD: 0x00,
+  CHECK_CONDITION: 0x02,
+} as const
+
+// --- SCSI CDB opcodes -------------------------------------------------------
+
+export const ScsiOpcode = {
+  TEST_UNIT_READY: 0x00,
+  REQUEST_SENSE: 0x03,
+  INQUIRY: 0x12,
+  MODE_SENSE_6: 0x1a,
+  READ_CAPACITY_10: 0x25,
+  READ_10: 0x28,
+  WRITE_10: 0x2a,
+  SYNCHRONIZE_CACHE_10: 0x35,
+  MODE_SENSE_10: 0x5a,
+  READ_16: 0x88,
+  WRITE_16: 0x8a,
+  SYNCHRONIZE_CACHE_16: 0x91,
+  SERVICE_ACTION_IN_16: 0x9e, // READ CAPACITY(16) lives under this opcode
+  REPORT_LUNS: 0xa0,
+} as const
+
+/** Service action (CDB byte 1, low 5 bits) for SERVICE_ACTION_IN_16. */
+export const SERVICE_ACTION_READ_CAPACITY_16 = 0x10
+
+// --- SCSI sense keys / additional sense codes -------------------------------
+
+export const SenseKey = {
+  NO_SENSE: 0x00,
+  RECOVERED_ERROR: 0x01,
+  NOT_READY: 0x02,
+  MEDIUM_ERROR: 0x03,
+  HARDWARE_ERROR: 0x04,
+  ILLEGAL_REQUEST: 0x05,
+  UNIT_ATTENTION: 0x06,
+} as const
+
+/** Additional Sense Code / Qualifier pairs we may emit. */
+export const Asc = {
+  NO_ADDITIONAL_SENSE: { asc: 0x00, ascq: 0x00 },
+  INVALID_COMMAND_OPERATION_CODE: { asc: 0x20, ascq: 0x00 },
+  INVALID_FIELD_IN_CDB: { asc: 0x24, ascq: 0x00 },
+  LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE: { asc: 0x21, ascq: 0x00 },
+} as const
+
+/** Reject reason codes (Reject PDU byte 2). */
+export const RejectReason = {
+  PROTOCOL_ERROR: 0x04,
+  COMMAND_NOT_SUPPORTED: 0x05,
+} as const
+
+// --- debugging --------------------------------------------------------------
+
+// Initiator opcodes (0x00-0x10) and target opcodes (0x20-0x3f) never collide,
+// so one reverse map names both directions for logs.
+const OPCODE_NAMES: Record<number, string> = {
+  ...Object.fromEntries(Object.entries(InitiatorOpcode).map(([name, code]) => [code, name])),
+  ...Object.fromEntries(Object.entries(TargetOpcode).map(([name, code]) => [code, name])),
+}
+
+/** Human-readable name of a PDU opcode (for debug logs). */
+export function opcodeName(opcode: number): string {
+  const code = opcode & OPCODE_MASK
+  return OPCODE_NAMES[code] ?? `0x${code.toString(16).padStart(2, '0')}`
+}

@vates/iscsi/src/declarations.d.mts

@@ -0,0 +1,30 @@
+// Ambient declarations for untyped external packages used by this module.
+// (CLAUDE.md: "Add declaration.d.ts for untyped external packages.")
+
+declare module '@vates/read-chunk' {
+  import type { Readable } from 'node:stream'
+
+  /**
+   * Resolves to exactly `size` bytes read from `stream`, or `null` if the
+   * stream ends before any byte of the requested chunk is available.
+   */
+  export function readChunk(stream: Readable, size?: number): Promise<Buffer | null>
+
+  /**
+   * Resolves to exactly `size` bytes read from `stream`; rejects if the stream
+   * ends before `size` bytes have been read.
+   */
+  export function readChunkStrict(stream: Readable, size: number): Promise<Buffer>
+}
+
+declare module 'promise-toolbox' {
+  /**
+   * Reject the promise it is bound to if it does not settle within `delay`
+   * milliseconds. Used as `pTimeout.call(promise, delay)`.
+   */
+  interface PTimeout {
+    <T>(this: Promise<T>, delay: number, onReject?: () => void): Promise<T>
+    call<T>(promise: Promise<T>, delay: number, onReject?: () => void): Promise<T>
+  }
+  export const pTimeout: PTimeout
+}

@vates/iscsi/src/index.mts

@@ -0,0 +1,193 @@
+import { createServer, type AddressInfo, type Server, type Socket } from 'node:net'
+import { createLogger, type Logger } from '@xen-orchestra/log'
+
+import type { BlockDevice } from './backend.mjs'
+import { Connection, type ConnectionDeps } from './connection.mjs'
+import type { ScsiIdentity } from './scsi.mjs'
+import type { ChapCredentials } from './types.mjs'
+
+export { FileBlockDevice } from './backend.mjs'
+export type { BlockDevice, FileBlockDeviceOptions } from './backend.mjs'
+export type { ScsiIdentity } from './scsi.mjs'
+export type { ChapCredentials } from './types.mjs'
+export { IscsiInitiator } from './initiator.mjs'
+export type { IscsiInitiatorOptions } from './initiator.mjs'
+export { IscsiDisk } from './IscsiDisk.mjs'
+export type { IscsiDiskOptions } from './IscsiDisk.mjs'
+export { DiskBlockDevice } from './DiskBlockDevice.mjs'
+export type { DiskBlockDeviceOptions } from './DiskBlockDevice.mjs'
+export { CachedDiskBlockDevice } from './CachedDiskBlockDevice.mjs'
+export type { CachedDiskBlockDeviceOptions } from './CachedDiskBlockDevice.mjs'
+
+const log: Logger = createLogger('vates:iscsi')
+
+const DEFAULT_PORT = 3260
+const DEFAULT_WRITE_TIMEOUT_MS = 30_000
+const DEFAULT_CMD_WINDOW = 64
+const DEFAULT_READ_CONCURRENCY = 16
+
+const DEFAULT_IDENTITY: ScsiIdentity = {
+  vendor: 'VATES',
+  product: 'ISCSI LUN',
+  revision: '0001',
+  serial: '',
+}
+
+export interface IscsiTargetOptions {
+  /** The target's iSCSI Qualified Name, e.g. `iqn.2024-01.tech.vates:lun0`. */
+  readonly iqn: string
+  /** The single LUN exposed by this target. */
+  readonly lun: BlockDevice
+  /** Listen address. Defaults to all interfaces. */
+  readonly host?: string
+  /** Listen port. Defaults to 3260. */
+  readonly port?: number
+  /** Overrides for the SCSI INQUIRY identity strings. */
+  readonly identity?: Partial<ScsiIdentity>
+  /** Drain timeout for outbound PDUs in ms (0 disables). Defaults to 30000. */
+  readonly writeTimeoutMs?: number
+  /** CmdSN command-window depth advertised to the initiator. Defaults to 64. */
+  readonly cmdWindow?: number
+  /**
+   * Max number of READ commands served concurrently — the command window lets
+   * the initiator keep many outstanding, but this caps how many `lun.read()`
+   * calls actually run at once regardless (e.g. so a deep queue depth doesn't
+   * fire dozens of simultaneous fetches against a real backend). Defaults to 16.
+   */
+  readonly readConcurrency?: number
+  /**
+   * When set, require one-way CHAP: the target challenges each initiator and
+   * rejects the login unless it proves this credential (interop with the
+   * open-iscsi `node.session.auth` username/password). Omit for no authentication.
+   */
+  readonly chap?: ChapCredentials
+}
+
+/**
+ * A minimal iSCSI target exposing exactly one read/write LUN.
+ *
+ * Single initiator, single connection (`MaxConnections=1`),
+ * `ErrorRecoveryLevel=0`, no digests. A new connection always replaces the
+ * current one rather than being refused (see `#onConnection`): there is no
+ * way to tell a stale, abandoned connection (initiator gave up without
+ * closing the socket) from a healthy one, so refusing would let one stuck
+ * connection wedge the target forever. Not RFC 7143 session reinstatement (no
+ * ISID matching) — safe here since the target is ephemeral, CHAP-guarded, and
+ * single-consumer.
+ */
+export class IscsiTarget {
+  readonly #iqn: string
+  readonly #lun: BlockDevice
+  readonly #host?: string
+  readonly #port: number
+  readonly #identity: ScsiIdentity
+  readonly #writeTimeoutMs: number
+  readonly #cmdWindow: number
+  readonly #readConcurrency: number
+  readonly #chap?: ChapCredentials
+
+  #server?: Server
+  #connection?: Connection
+  #tsih = 0
+
+  constructor(options: IscsiTargetOptions) {
+    this.#iqn = options.iqn
+    this.#lun = options.lun
+    this.#host = options.host
+    this.#port = options.port ?? DEFAULT_PORT
+    this.#writeTimeoutMs = options.writeTimeoutMs ?? DEFAULT_WRITE_TIMEOUT_MS
+    this.#cmdWindow = options.cmdWindow ?? DEFAULT_CMD_WINDOW
+    this.#readConcurrency = options.readConcurrency ?? DEFAULT_READ_CONCURRENCY
+    this.#chap = options.chap
+    this.#identity = {
+      ...DEFAULT_IDENTITY,
+      // Default the serial to the IQN so the LUN has a stable, unique identity.
+      serial: options.iqn,
+      ...options.identity,
+    }
+  }
+
+  #allocateTsih(): number {
+    this.#tsih = (this.#tsih % 0xffff) + 1 // non-zero, wraps within 16 bits
+    return this.#tsih
+  }
+
+  #deps(): ConnectionDeps {
+    return {
+      iqn: this.#iqn,
+      identity: this.#identity,
+      lun: this.#lun,
+      writeTimeoutMs: this.#writeTimeoutMs,
+      cmdWindow: this.#cmdWindow,
+      readConcurrency: this.#readConcurrency,
+      allocateTsih: () => this.#allocateTsih(),
+      chap: this.#chap,
+    }
+  }
+
+  #onConnection(socket: Socket): void {
+    const existing = this.#connection
+    if (existing !== undefined) {
+      // Replaces a possibly-stale connection rather than refusing; see the class doc.
+      log.warn('replacing existing connection with a new one', { remote: socket.remoteAddress })
+      existing.destroy()
+    }
+    socket.setNoDelay(true)
+    const connection = new Connection(socket, this.#deps())
+    this.#connection = connection
+    // Long-lived per-connection task; serve() handles its own errors and never
+    // rejects, so detaching it here is safe.
+    void connection.serve().finally(() => {
+      if (this.#connection === connection) {
+        this.#connection = undefined
+      }
+    })
+  }
+
+  /** Open the LUN (if needed) and start accepting connections. */
+  async listen(): Promise<void> {
+    if (this.#server !== undefined) {
+      throw new Error('iSCSI target is already listening')
+    }
+    await this.#lun.open?.()
+
+    const server = createServer(socket => this.#onConnection(socket))
+    this.#server = server
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onError = (error: Error) => reject(error)
+        server.once('error', onError)
+        server.listen(this.#port, this.#host, () => {
+          server.removeListener('error', onError)
+          resolve()
+        })
+      })
+    } catch (error) {
+      this.#server = undefined
+      throw error
+    }
+    log.info('target listening', { iqn: this.#iqn, address: this.address() })
+  }
+
+  /** The bound address, or undefined if not listening on an IP socket. */
+  address(): AddressInfo | undefined {
+    const address = this.#server?.address()
+    return address !== null && typeof address === 'object' ? address : undefined
+  }
+
+  /** Stop accepting connections, drop the active connection, and close the LUN. */
+  async close(): Promise<void> {
+    const server = this.#server
+    const connection = this.#connection
+    this.#server = undefined
+    this.#connection = undefined
+    if (server !== undefined) {
+      await new Promise<void>((resolve, reject) => {
+        server.close(error => (error ? reject(error) : resolve()))
+        // Drop the live connection so server.close() can complete.
+        connection?.destroy()
+      })
+    }
+    await this.#lun.close()
+  }
+}

@vates/iscsi/src/initiator.integ.mts

@@ -0,0 +1,261 @@
+import assert from 'node:assert/strict'
+import { createServer, type Server, type Socket } from 'node:net'
+import { once } from 'node:events'
+import { describe, it } from 'node:test'
+
+import {
+  DATA_IN_FLAG_FINAL,
+  DATA_IN_FLAG_STATUS,
+  FLAG_FINAL,
+  InitiatorOpcode,
+  ISCSI_VERSION,
+  LOGIN_FLAG_TRANSIT,
+  LoginStage,
+  RESERVED_TAG,
+  ScsiStatus,
+  TargetOpcode,
+} from './constants.mjs'
+import { IscsiInitiator } from './initiator.mjs'
+import { allocBhs, assemblePdu, type IncomingPdu, readPdu } from './pdu.mjs'
+
+const IQN = 'iqn.2024-01.tech.vates:nop-test'
+const BLOCK_SIZE = 512
+const BLOCK_COUNT = 2048
+
+/**
+ * A target that speaks just enough to get a session up — login, READ
+ * CAPACITY(16), READ(16) — and can then ping the initiator on demand, which
+ * the real {@link IscsiTarget} never does. Everything here is about what the
+ * *initiator* does with an unsolicited NOP-In.
+ */
+class PingingTarget {
+  readonly #server: Server
+  #socket?: Socket
+  /** PDUs received from the initiator after the session was established. */
+  readonly received: Array<IncomingPdu> = []
+  #statSN = 0
+
+  constructor() {
+    this.#server = createServer(socket => {
+      this.#socket = socket
+      socket.setNoDelay(true)
+      this.#serve(socket).catch(() => {}) // the initiator hanging up is normal
+    })
+  }
+
+  async listen(): Promise<number> {
+    this.#server.listen(0, '127.0.0.1')
+    await once(this.#server, 'listening')
+    return (this.#server.address() as { port: number }).port
+  }
+
+  async close(): Promise<void> {
+    this.#socket?.destroy()
+    this.#server.close()
+  }
+
+  #send(socket: Socket, buffer: Buffer): Promise<void> {
+    return new Promise((resolve, reject) => {
+      socket.write(buffer, error => (error ? reject(error) : resolve()))
+    })
+  }
+
+  /** Ping the initiator the way a target does when the session goes quiet. */
+  async ping(targetTransferTag: number, data = Buffer.alloc(0)): Promise<void> {
+    const socket = this.#socket
+    assert.ok(socket !== undefined, 'no initiator connected')
+    const bhs = allocBhs(TargetOpcode.NOP_IN)
+    bhs[1] = FLAG_FINAL
+    bhs.writeUInt32BE(RESERVED_TAG, 16) // ITT: unsolicited, so none
+    bhs.writeUInt32BE(targetTransferTag, 20)
+    bhs.writeUInt32BE(this.#statSN, 24) // NOP-In does not advance StatSN
+    await this.#send(socket, assemblePdu(bhs, data))
+  }
+
+  /** Resolves once the initiator has sent a PDU with `opcode`. */
+  async waitFor(opcode: number, timeoutMs = 2000): Promise<IncomingPdu> {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const found = this.received.find(pdu => pdu.opcode === opcode)
+      if (found !== undefined) {
+        return found
+      }
+      assert.ok(Date.now() < deadline, `initiator never sent opcode 0x${opcode.toString(16)}`)
+      await new Promise(resolve => setTimeout(resolve, 10))
+    }
+  }
+
+  async #serve(socket: Socket): Promise<void> {
+    let established = false
+    for (;;) {
+      const pdu = await readPdu(socket)
+      if (pdu === null) {
+        return
+      }
+      if (established) {
+        this.received.push(pdu)
+      }
+      switch (pdu.opcode) {
+        case InitiatorOpcode.LOGIN_REQUEST:
+          await this.#sendLoginResponse(socket, pdu)
+          established = true
+          break
+        case InitiatorOpcode.SCSI_COMMAND:
+          await this.#sendReadData(socket, pdu)
+          break
+        case InitiatorOpcode.LOGOUT_REQUEST: {
+          const bhs = allocBhs(TargetOpcode.LOGOUT_RESPONSE)
+          bhs[1] = FLAG_FINAL
+          bhs.writeUInt32BE(pdu.itt, 16)
+          bhs.writeUInt32BE(this.#statSN++, 24)
+          await this.#send(socket, assemblePdu(bhs))
+          return
+        }
+        default: // NOP-Out replies land in `received`; nothing to answer
+          break
+      }
+    }
+  }
+
+  async #sendLoginResponse(socket: Socket, request: IncomingPdu): Promise<void> {
+    const bhs = allocBhs(TargetOpcode.LOGIN_RESPONSE)
+    bhs[1] = LOGIN_FLAG_TRANSIT | (LoginStage.OPERATIONAL_NEGOTIATION << 2) | LoginStage.FULL_FEATURE_PHASE
+    bhs[2] = ISCSI_VERSION
+    bhs[3] = ISCSI_VERSION
+    request.bhs.copy(bhs, 8, 8, 14) // echo ISID
+    bhs.writeUInt16BE(1, 14) // TSIH
+    bhs.writeUInt32BE(request.itt, 16)
+    bhs.writeUInt32BE(this.#statSN++, 24)
+    await this.#send(socket, assemblePdu(bhs))
+  }
+
+  /** Answer any read-type command with a single Data-In carrying GOOD status. */
+  async #sendReadData(socket: Socket, command: IncomingPdu): Promise<void> {
+    const cdb = command.bhs.subarray(32, 48)
+    const expectedLength = command.readU32(20)
+    let payload
+    if (cdb[0] === 0x9e) {
+      // SERVICE ACTION IN(16) / READ CAPACITY(16)
+      payload = Buffer.alloc(expectedLength)
+      payload.writeBigUInt64BE(BigInt(BLOCK_COUNT - 1), 0)
+      payload.writeUInt32BE(BLOCK_SIZE, 8)
+    } else {
+      payload = Buffer.alloc(expectedLength, 0x5a)
+    }
+
+    const bhs = allocBhs(TargetOpcode.SCSI_DATA_IN)
+    bhs[1] = DATA_IN_FLAG_FINAL | DATA_IN_FLAG_STATUS
+    bhs[3] = ScsiStatus.GOOD
+    bhs.writeUInt32BE(command.itt, 16)
+    bhs.writeUInt32BE(RESERVED_TAG, 20)
+    bhs.writeUInt32BE(this.#statSN++, 24)
+    await this.#send(socket, assemblePdu(bhs, payload))
+  }
+}
+
+/** Run `body` against a connected initiator, always tearing both ends down. */
+const withSession = async (body: (initiator: IscsiInitiator, target: PingingTarget) => Promise<void>) => {
+  const target = new PingingTarget()
+  const port = await target.listen()
+  const initiator = new IscsiInitiator({
+    host: '127.0.0.1',
+    port,
+    targetIqn: IQN,
+    messageTimeoutMs: 5000,
+  })
+  await initiator.connect()
+  try {
+    await body(initiator, target)
+  } finally {
+    await initiator.close()
+    await target.close()
+  }
+}
+
+describe('NOP-In keepalives', () => {
+  // The read loop used to stop as soon as no read was outstanding, and it is
+  // the only reader of the socket — so a ping arriving while idle sat unread in
+  // a paused stream. Targets drop a session whose pings go unanswered (30s on
+  // LIO by default), and nothing here reconnects, so an idle mount died.
+  it('are answered while the session is idle', async () => {
+    await withSession(async (initiator, target) => {
+      // no read in flight, and none will be
+      await target.ping(7)
+
+      const reply = await target.waitFor(InitiatorOpcode.NOP_OUT)
+      assert.equal(reply.readU32(20), 7) // echoes the Target Transfer Tag
+      assert.equal(reply.itt, RESERVED_TAG) // unsolicited reply, so no ITT
+      assert.notEqual(reply.bhs[0] & 0x40, 0) // immediate
+    })
+  })
+
+  it('echo the ping payload back', async () => {
+    await withSession(async (initiator, target) => {
+      const ping = Buffer.from('are you there')
+      await target.ping(9, ping)
+
+      const reply = await target.waitFor(InitiatorOpcode.NOP_OUT)
+      assert.deepEqual(reply.data, ping)
+    })
+  })
+
+  it('are answered between reads, without disturbing them', async () => {
+    await withSession(async (initiator, target) => {
+      assert.equal((await initiator.read(0, BLOCK_SIZE)).length, BLOCK_SIZE)
+
+      await target.ping(11)
+      await target.waitFor(InitiatorOpcode.NOP_OUT)
+
+      // the session is still usable afterwards
+      const data = await initiator.read(BLOCK_SIZE, BLOCK_SIZE)
+      assert.deepEqual(data, Buffer.alloc(BLOCK_SIZE, 0x5a))
+    })
+  })
+
+  it('are ignored when they are a reply to our own ping', async () => {
+    await withSession(async (initiator, target) => {
+      // a NOP-In with no Target Transfer Tag is a reply, not a ping: answering
+      // it would start an endless exchange
+      await target.ping(RESERVED_TAG)
+      await new Promise(resolve => setTimeout(resolve, 200))
+
+      assert.equal(
+        target.received.some(pdu => pdu.opcode === InitiatorOpcode.NOP_OUT),
+        false
+      )
+      // and the session still works
+      assert.equal((await initiator.read(0, BLOCK_SIZE)).length, BLOCK_SIZE)
+    })
+  })
+})
+
+describe('session teardown', () => {
+  it('logs out cleanly even though the read loop owns the socket', async () => {
+    const target = new PingingTarget()
+    const port = await target.listen()
+    const initiator = new IscsiInitiator({ host: '127.0.0.1', port, targetIqn: IQN, messageTimeoutMs: 5000 })
+    await initiator.connect()
+
+    await initiator.close()
+
+    // the Logout Request reached the target, i.e. `close()` did not give up on
+    // its own response for lack of a reader
+    await target.waitFor(InitiatorOpcode.LOGOUT_REQUEST)
+    await target.close()
+  })
+
+  it('fails a read with the reason the session died, rather than timing out', async () => {
+    const target = new PingingTarget()
+    const port = await target.listen()
+    const initiator = new IscsiInitiator({ host: '127.0.0.1', port, targetIqn: IQN, messageTimeoutMs: 5000 })
+    await initiator.connect()
+
+    await target.close() // target vanishes while the initiator is idle
+    await new Promise(resolve => setTimeout(resolve, 100))
+
+    const started = Date.now()
+    await assert.rejects(initiator.read(0, BLOCK_SIZE), /connection closed/)
+    // far below messageTimeoutMs: the dead session is known, not discovered
+    assert.ok(Date.now() - started < 1000)
+  })
+})

@vates/iscsi/src/initiator.mts

@@ -0,0 +1,501 @@
+import { connect, type Socket } from 'node:net'
+import { once } from 'node:events'
+import { createLogger, type Logger } from '@xen-orchestra/log'
+import { pTimeout } from 'promise-toolbox'
+
+import {
+  AuthMethod,
+  DATA_IN_FLAG_STATUS,
+  FLAG_FINAL,
+  InitiatorOpcode,
+  LOGIN_CSG_SHIFT,
+  LOGIN_FLAG_TRANSIT,
+  LOGIN_NSG_MASK,
+  LoginStage,
+  LoginStatusClass,
+  OPCODE_IMMEDIATE,
+  RESERVED_TAG,
+  SCSI_CMD_FLAG_READ,
+  ScsiOpcode,
+  ScsiStatus,
+  SERVICE_ACTION_READ_CAPACITY_16,
+  TargetOpcode,
+} from './constants.mjs'
+import { CHAP_ALGORITHM_MD5, computeResponse, decodeChapValue, encodeChapValue } from './chap.mjs'
+import { parseTextKeys, serializeTextKeys } from './login.mjs'
+import { allocBhs, assemblePdu, type IncomingPdu, readPdu, writePdu } from './pdu.mjs'
+import type { ChapCredentials } from './types.mjs'
+
+const log: Logger = createLogger('vates:iscsi:initiator')
+
+const DEFAULT_PORT = 3260
+const DEFAULT_MESSAGE_TIMEOUT_MS = 60_000
+const DEFAULT_MAX_RECV_DATA_SEGMENT_LENGTH = 262144
+const READ_CAPACITY_16_LENGTH = 32
+
+export interface IscsiInitiatorOptions {
+  /** Portal address to connect to. */
+  readonly host: string
+  /** Portal port. Defaults to 3260. */
+  readonly port?: number
+  /** Target IQN (`TargetName`) to log into. */
+  readonly targetIqn: string
+  /** Our initiator IQN (`InitiatorName`). Defaults to a generated one. */
+  readonly initiatorIqn?: string
+  /**
+   * One-way CHAP responder credential. When the target requests CHAP we answer
+   * its challenge with this user/secret. Omit for an unauthenticated login.
+   */
+  readonly chap?: ChapCredentials
+  /** Per-message timeout for login/read responses, in ms. Defaults to 60000. */
+  readonly messageTimeoutMs?: number
+}
+
+/** An outstanding SCSI read, keyed by its Initiator Task Tag. */
+interface Pending {
+  /** Preallocated buffer sized to the expected transfer length. */
+  readonly buffer: Buffer
+  resolve(data: Buffer): void
+  reject(error: Error): void
+}
+
+/**
+ * A minimal userspace iSCSI initiator (client), mirroring {@link IscsiTarget}'s
+ * framing and negotiation (read-only, single connection, one LUN, digests
+ * off, `ErrorRecoveryLevel=0`).
+ *
+ * A backlog `Map` keyed by ITT, drained by a single read loop, demultiplexes
+ * responses so several reads can be outstanding at once (e.g. under a
+ * `ReadAhead` disk wrapper).
+ */
+export class IscsiInitiator {
+  readonly #host: string
+  readonly #port: number
+  readonly #targetIqn: string
+  readonly #initiatorIqn: string
+  readonly #chap?: ChapCredentials
+  readonly #messageTimeoutMs: number
+
+  #socket?: Socket
+  #itt = 0
+  #cmdSN = 0
+  #expStatSN = 0
+
+  #blockSize = 0
+  #capacityBytes = 0
+
+  // Outstanding reads, keyed by ITT. A single #readLoop() (guarded by #reading)
+  // is the only consumer of readPdu, so it is safe to have many entries here.
+  readonly #backlog = new Map<number, Pending>()
+  #reading = false
+  // set once `close()` starts, so the read loop's own end is not reported as a
+  // fault and it stops instead of racing the socket teardown
+  #closing = false
+  // why the read loop stopped, when it was not us closing
+  #failure?: Error
+  // resolved by the read loop when the target's Logout Response arrives
+  #logoutAnswered?: () => void
+
+  constructor(options: IscsiInitiatorOptions) {
+    this.#host = options.host
+    this.#port = options.port ?? DEFAULT_PORT
+    this.#targetIqn = options.targetIqn
+    this.#initiatorIqn = options.initiatorIqn ?? 'iqn.2024-01.tech.vates:initiator'
+    this.#chap = options.chap
+    this.#messageTimeoutMs = options.messageTimeoutMs ?? DEFAULT_MESSAGE_TIMEOUT_MS
+  }
+
+  /** LUN logical block size in bytes (valid after {@link connect}). */
+  getBlockSize(): number {
+    return this.#blockSize
+  }
+
+  /** LUN capacity in bytes (valid after {@link connect}). */
+  getSize(): number {
+    return this.#capacityBytes
+  }
+
+  // --- lifecycle ------------------------------------------------------------
+
+  /** Open the TCP connection, log in, and read the LUN capacity. */
+  async connect(): Promise<void> {
+    const socket = connect(this.#port, this.#host)
+    this.#socket = socket
+    try {
+      await once(socket, 'connect')
+      socket.setNoDelay(true)
+      // A socket error with no read in flight would otherwise go unnoticed.
+      socket.on('error', error => this.#rejectAll(error instanceof Error ? error : new Error(String(error))))
+      // `#login` reads its own responses; from here on the read loop owns the
+      // socket, and it must be running before anything can answer a NOP-In
+      await this.#login()
+      void this.#pump()
+      await this.#readCapacity()
+      log.info('session established', { target: this.#targetIqn, capacity: this.#capacityBytes })
+    } catch (error) {
+      socket.destroy()
+      this.#socket = undefined
+      throw error
+    }
+  }
+
+  #requireSocket(): Socket {
+    const socket = this.#socket
+    if (socket === undefined) {
+      throw new Error('IscsiInitiator.connect() must be called first')
+    }
+    return socket
+  }
+
+  #send(buffer: Buffer): Promise<void> {
+    return writePdu(this.#requireSocket(), buffer, this.#messageTimeoutMs)
+  }
+
+  #nextItt(): number {
+    this.#itt = (this.#itt + 1) >>> 0
+    return this.#itt
+  }
+
+  /** Best-effort Logout, then close the socket. */
+  async close(): Promise<void> {
+    const socket = this.#socket
+    if (socket === undefined) {
+      return
+    }
+    // stops the read loop and keeps its own end from being logged as a fault
+    this.#closing = true
+    try {
+      const bhs = allocBhs(InitiatorOpcode.LOGOUT_REQUEST | OPCODE_IMMEDIATE)
+      bhs[1] = FLAG_FINAL // reason 0: close the session
+      bhs.writeUInt32BE(this.#nextItt(), 16)
+      bhs.writeUInt32BE(this.#cmdSN, 24)
+      bhs.writeUInt32BE(this.#expStatSN, 28)
+      // the read loop owns the socket, so the response comes through it: reading
+      // here too would put two consumers on one stream and split PDUs between them
+      const answered = new Promise<void>(resolve => {
+        this.#logoutAnswered = resolve
+      })
+      await this.#send(assemblePdu(bhs))
+      await pTimeout.call(answered, this.#messageTimeoutMs)
+    } catch (error) {
+      log.debug('logout failed, closing anyway', { error })
+    } finally {
+      this.#logoutAnswered = undefined
+      this.#socket = undefined
+      socket.destroy()
+    }
+  }
+
+  // --- login ----------------------------------------------------------------
+
+  /** Build the flags byte (T/CSG/NSG) of a Login Request. */
+  #loginFlags(transit: boolean, csg: number, nsg: number): number {
+    return (transit ? LOGIN_FLAG_TRANSIT : 0) | (csg << LOGIN_CSG_SHIFT) | (nsg & LOGIN_NSG_MASK)
+  }
+
+  async #sendLogin(itt: number, flags: number, keys: Array<[string, string]>): Promise<IncomingPdu> {
+    const bhs = allocBhs(InitiatorOpcode.LOGIN_REQUEST | OPCODE_IMMEDIATE)
+    bhs[1] = flags
+    Buffer.from([0x80, 0, 0, 0, 0, 1]).copy(bhs, 8) // ISID (fixed; single session)
+    bhs.writeUInt32BE(itt, 16)
+    bhs.writeUInt32BE(this.#cmdSN, 24) // login is immediate: does not advance CmdSN
+    bhs.writeUInt32BE(this.#expStatSN, 28)
+    log.debug('login request', { flags: `0x${flags.toString(16)}`, keys: Object.fromEntries(keys) })
+    await this.#send(assemblePdu(bhs, serializeTextKeys(keys)))
+
+    const pdu = await pTimeout.call(readPdu(this.#requireSocket()), this.#messageTimeoutMs)
+    if (pdu === null) {
+      throw new Error('connection closed during login')
+    }
+    if (pdu.opcode !== TargetOpcode.LOGIN_RESPONSE) {
+      throw new Error(`expected Login Response, got opcode 0x${pdu.opcode.toString(16)}`)
+    }
+    const statusClass = pdu.readU8(36)
+    log.debug('login response', {
+      statusClass,
+      statusDetail: pdu.readU8(37),
+      transit: (pdu.readU8(1) & LOGIN_FLAG_TRANSIT) !== 0,
+      keys: Object.fromEntries(parseTextKeys(pdu.data)),
+    })
+    if (statusClass !== LoginStatusClass.SUCCESS) {
+      throw new Error(
+        `login rejected (status-class 0x${statusClass.toString(16)}, detail 0x${pdu.readU8(37).toString(16)})`
+      )
+    }
+    this.#expStatSN = (pdu.readU32(24) + 1) >>> 0
+    return pdu
+  }
+
+  /**
+   * Drive the login: an optional CHAP security stage (we are the responder),
+   * then the operational stage into the full-feature phase. All PDUs of one
+   * login share a single ITT.
+   */
+  async #login(): Promise<void> {
+    const itt = this.#nextItt()
+    const names: Array<[string, string]> = [
+      ['InitiatorName', this.#initiatorIqn],
+      ['TargetName', this.#targetIqn],
+      ['SessionType', 'Normal'],
+    ]
+
+    if (this.#chap !== undefined) {
+      // Round 1: offer CHAP (falling back to None) in the security stage.
+      const r1 = await this.#sendLogin(
+        itt,
+        this.#loginFlags(false, LoginStage.SECURITY_NEGOTIATION, LoginStage.OPERATIONAL_NEGOTIATION),
+        [...names, ['AuthMethod', `${AuthMethod.CHAP},${AuthMethod.NONE}`]]
+      )
+      const method = parseTextKeys(r1.data).get('AuthMethod')
+      log.debug('chap: target selected AuthMethod', { method })
+      if (method === AuthMethod.CHAP) {
+        // Round 2: propose MD5.
+        const r2 = await this.#sendLogin(
+          itt,
+          this.#loginFlags(false, LoginStage.SECURITY_NEGOTIATION, LoginStage.OPERATIONAL_NEGOTIATION),
+          [['CHAP_A', String(CHAP_ALGORITHM_MD5)]]
+        )
+        // Round 3: answer the target's challenge, transiting to operational.
+        // (Mutual CHAP is not supported: we never challenge the target; a target
+        // that *requires* mutual auth will reject this login, surfaced above.)
+        const challenge = parseTextKeys(r2.data)
+        const id = Number.parseInt(challenge.get('CHAP_I') ?? '', 10)
+        const challengeValue = challenge.get('CHAP_C')
+        if (!Number.isInteger(id) || challengeValue === undefined) {
+          throw new Error('malformed CHAP challenge from target')
+        }
+        const response = computeResponse(id, this.#chap.secret, decodeChapValue(challengeValue))
+        log.debug('chap: answering challenge', { id, user: this.#chap.user })
+        await this.#sendLogin(
+          itt,
+          this.#loginFlags(true, LoginStage.SECURITY_NEGOTIATION, LoginStage.OPERATIONAL_NEGOTIATION),
+          [
+            ['CHAP_N', this.#chap.user],
+            ['CHAP_R', encodeChapValue(response)],
+          ]
+        )
+        await this.#operationalLogin(itt, [])
+        return
+      }
+      if (method !== AuthMethod.NONE && method !== undefined) {
+        throw new Error(`target selected unsupported AuthMethod=${method}`)
+      }
+      // Target did not require CHAP: continue straight to operational.
+      await this.#operationalLogin(itt, [])
+      return
+    }
+
+    // No CHAP: a single operational-stage PDU straight to the full-feature phase.
+    await this.#operationalLogin(itt, names)
+  }
+
+  /** Operational-stage login PDU, transiting to the full-feature phase. */
+  async #operationalLogin(itt: number, extraKeys: Array<[string, string]>): Promise<void> {
+    const pdu = await this.#sendLogin(
+      itt,
+      this.#loginFlags(true, LoginStage.OPERATIONAL_NEGOTIATION, LoginStage.FULL_FEATURE_PHASE),
+      [
+        ...extraKeys,
+        ['HeaderDigest', 'None'],
+        ['DataDigest', 'None'],
+        ['InitialR2T', 'Yes'],
+        ['ImmediateData', 'No'],
+        ['ErrorRecoveryLevel', '0'],
+        ['MaxRecvDataSegmentLength', String(DEFAULT_MAX_RECV_DATA_SEGMENT_LENGTH)],
+      ]
+    )
+    if ((pdu.readU8(1) & LOGIN_FLAG_TRANSIT) === 0) {
+      throw new Error('target did not transit to the full-feature phase')
+    }
+  }
+
+  // --- read path ------------------------------------------------------------
+
+  /**
+   * Read exactly `length` bytes from byte `offset` of the LUN. `offset` and
+   * `length` must be block-aligned (multiples of {@link getBlockSize}).
+   */
+  read(offset: number, length: number): Promise<Buffer> {
+    const blockSize = this.#blockSize
+    if (offset % blockSize !== 0 || length % blockSize !== 0) {
+      return Promise.reject(new Error(`unaligned read (offset ${offset}, length ${length}, block ${blockSize})`))
+    }
+    const cdb = Buffer.alloc(16)
+    cdb[0] = ScsiOpcode.READ_16
+    cdb.writeBigUInt64BE(BigInt(offset / blockSize), 2) // LBA
+    cdb.writeUInt32BE(length / blockSize, 10) // transfer length, in blocks
+    return this.#scsiRead(cdb, length)
+  }
+
+  /** Issue READ CAPACITY(16) and record the LUN block size and capacity. */
+  async #readCapacity(): Promise<void> {
+    const cdb = Buffer.alloc(16)
+    cdb[0] = ScsiOpcode.SERVICE_ACTION_IN_16
+    cdb[1] = SERVICE_ACTION_READ_CAPACITY_16
+    cdb.writeUInt32BE(READ_CAPACITY_16_LENGTH, 10) // allocation length
+    // Block size is unknown here, so bypass the alignment guard in read().
+    const data = await this.#scsiRead(cdb, READ_CAPACITY_16_LENGTH)
+    const maxLba = data.readBigUInt64BE(0)
+    this.#blockSize = data.readUInt32BE(8)
+    this.#capacityBytes = Number((maxLba + 1n) * BigInt(this.#blockSize))
+    log.debug('read capacity', { blockSize: this.#blockSize, capacityBytes: this.#capacityBytes })
+  }
+
+  /** Issue a read-type SCSI command and resolve with its assembled Data-In. */
+  #scsiRead(cdb: Buffer, expectedLength: number): Promise<Buffer> {
+    const failure = this.#failure
+    if (failure !== undefined) {
+      // the session is already gone: fail with why, rather than writing into a
+      // half-closed socket and waiting out the message timeout
+      return Promise.reject(failure)
+    }
+    const socket = this.#requireSocket()
+    const itt = this.#nextItt()
+    const bhs = allocBhs(InitiatorOpcode.SCSI_COMMAND)
+    bhs[1] = FLAG_FINAL | SCSI_CMD_FLAG_READ
+    bhs.writeUInt32BE(itt, 16)
+    bhs.writeUInt32BE(expectedLength, 20) // Expected Data Transfer Length
+    bhs.writeUInt32BE(this.#cmdSN, 24)
+    this.#cmdSN = (this.#cmdSN + 1) >>> 0
+    bhs.writeUInt32BE(this.#expStatSN, 28)
+    cdb.copy(bhs, 32)
+    log.debug('scsi read', { itt, cdb: `0x${cdb[0].toString(16)}`, expectedLength, cmdSN: (this.#cmdSN - 1) >>> 0 })
+
+    // Register the pending read BEFORE writing, so a fast response cannot arrive
+    // before the backlog entry exists. No await between allocate → register →
+    // send → pump, which keeps concurrent reads correct.
+    const promise = new Promise<Buffer>((resolve, reject) => {
+      this.#backlog.set(itt, { buffer: Buffer.alloc(expectedLength), resolve, reject })
+    })
+    writePdu(socket, assemblePdu(bhs), this.#messageTimeoutMs).catch(error => {
+      const pending = this.#backlog.get(itt)
+      if (pending !== undefined) {
+        this.#backlog.delete(itt)
+        pending.reject(error instanceof Error ? error : new Error(String(error)))
+      }
+    })
+    void this.#pump()
+    return pTimeout.call(promise, this.#messageTimeoutMs)
+  }
+
+  /**
+   * Drain inbound PDUs for as long as the session lives. Only ever one runs at
+   * a time, and it is the only reader of the socket after login.
+   *
+   * It deliberately does not stop when the backlog empties. A target sends its
+   * NOP-In keepalives precisely when nothing else is going on, and it is the
+   * only reader — so a loop that parked between reads would leave those pings
+   * sitting unread in a paused stream. Targets drop a session whose pings go
+   * unanswered (LIO's `nopin_response_timeout` is 30s by default, arrays are
+   * similar), and nothing here reconnects, so the session would die during any
+   * idle period: right after `connect()`, between reads, or while the consumer
+   * of a mounted disk stalls.
+   */
+  async #pump(): Promise<void> {
+    if (this.#reading) {
+      return
+    }
+    this.#reading = true
+    try {
+      while (!this.#closing) {
+        const socket = this.#socket
+        if (socket === undefined) {
+          throw new Error('connection closed')
+        }
+        const pdu = await readPdu(socket)
+        if (pdu === null) {
+          throw new Error('connection closed by target')
+        }
+        this.#route(pdu)
+      }
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error))
+      if (!this.#closing) {
+        // The loop now runs while idle, so it is usually the first to notice the
+        // session die — with nothing in the backlog to reject and nobody to
+        // return an error to. Log it where it happens, and keep the reason so
+        // later reads fail with the original cause instead of whatever the dead
+        // socket produces.
+        this.#failure = failure
+        log.warn('read loop stopped, session is dead', { error: failure })
+        this.#rejectAll(failure)
+      }
+    } finally {
+      this.#reading = false
+    }
+  }
+
+  /** Route one inbound PDU to its pending read (by ITT), completing it if done. */
+  #route(pdu: IncomingPdu): void {
+    switch (pdu.opcode) {
+      case TargetOpcode.SCSI_DATA_IN: {
+        const pending = this.#backlog.get(pdu.itt)
+        if (pending === undefined) {
+          return // stale/duplicate; ignore
+        }
+        pdu.data.copy(pending.buffer, pdu.readU32(40)) // copy at Buffer Offset
+        const hasStatus = (pdu.flags & DATA_IN_FLAG_STATUS) !== 0
+        log.debug('data-in', { itt: pdu.itt, offset: pdu.readU32(40), length: pdu.data.length, final: hasStatus })
+        if (hasStatus) {
+          this.#expStatSN = (pdu.readU32(24) + 1) >>> 0
+          this.#complete(pdu.itt, pending, pdu.readU8(3))
+        }
+        return
+      }
+      case TargetOpcode.SCSI_RESPONSE: {
+        const pending = this.#backlog.get(pdu.itt)
+        if (pending !== undefined) {
+          this.#expStatSN = (pdu.readU32(24) + 1) >>> 0
+          this.#complete(pdu.itt, pending, pdu.readU8(3))
+        }
+        return
+      }
+      case TargetOpcode.NOP_IN: {
+        // A target-initiated NOP ping (TTT set) must be answered to keep the
+        // session alive; a NOP reply to our own ping (none here) is ignored.
+        const ttt = pdu.readU32(20)
+        if (ttt !== RESERVED_TAG) {
+          void this.#replyNop(ttt, pdu.data)
+        }
+        return
+      }
+      case TargetOpcode.LOGOUT_RESPONSE:
+        // awaited by `close()`, which cannot read the socket itself
+        this.#logoutAnswered?.()
+        return
+      default:
+        // R2T/Async/Reject are not expected on the read-only path; ignore.
+        log.debug('ignoring unexpected PDU', { opcode: pdu.opcode })
+    }
+  }
+
+  #complete(itt: number, pending: Pending, status: number): void {
+    this.#backlog.delete(itt)
+    log.debug('read complete', { itt, status, pending: this.#backlog.size })
+    if (status === ScsiStatus.GOOD) {
+      pending.resolve(pending.buffer)
+    } else {
+      pending.reject(new Error(`SCSI command failed with status 0x${status.toString(16)}`))
+    }
+  }
+
+  async #replyNop(targetTransferTag: number, ping: Buffer): Promise<void> {
+    const bhs = allocBhs(InitiatorOpcode.NOP_OUT | OPCODE_IMMEDIATE)
+    bhs[1] = FLAG_FINAL
+    bhs.writeUInt32BE(RESERVED_TAG, 16) // ITT: none (this is an unsolicited reply)
+    bhs.writeUInt32BE(targetTransferTag, 20)
+    bhs.writeUInt32BE(this.#cmdSN, 24)
+    bhs.writeUInt32BE(this.#expStatSN, 28)
+    await this.#send(assemblePdu(bhs, ping)).catch(error => log.debug('NOP reply failed', { error }))
+  }
+
+  #rejectAll(error: Error): void {
+    if (this.#backlog.size > 0) {
+      log.debug('rejecting all pending reads', { count: this.#backlog.size, error: error.message })
+    }
+    for (const [itt, pending] of this.#backlog) {
+      this.#backlog.delete(itt)
+      pending.reject(error)
+    }
+  }
+}

@vates/iscsi/src/login.mts

@@ -0,0 +1,369 @@
+import { isIP } from 'node:net'
+import { createLogger, type Logger } from '@xen-orchestra/log'
+
+import {
+  AuthMethod,
+  LOGIN_CSG_MASK,
+  LOGIN_CSG_SHIFT,
+  LOGIN_FLAG_CONTINUE,
+  LOGIN_FLAG_TRANSIT,
+  LOGIN_NSG_MASK,
+  LoginStage,
+  LoginStatusClass,
+  LoginStatusDetail,
+} from './constants.mjs'
+import {
+  computeResponse,
+  encodeChapValue,
+  decodeChapValue,
+  generateChallenge,
+  generateId,
+  parseAlgorithmList,
+  selectAlgorithm,
+  verifyResponse,
+} from './chap.mjs'
+import type { IncomingPdu } from './pdu.mjs'
+import type { ChapCredentials, NegotiatedParams, SessionType } from './types.mjs'
+
+const EMPTY = Buffer.alloc(0)
+
+// Target-side login negotiation trace. Enable the `vates:iscsi:login` debug
+// namespace to see every negotiated key and CHAP state change — the usual root
+// cause when a particular initiator fails to attach.
+const log: Logger = createLogger('vates:iscsi:login')
+
+// Operational values the target imposes. The target drives negotiation, so these
+// are pinned to a single code path (see plan): all writes are R2T-solicited
+// (InitialR2T=Yes, ImmediateData=No), no digests, one connection.
+const OUR_MAX_RECV_DATA_SEGMENT_LENGTH = 262144
+const OUR_MAX_BURST_LENGTH = 262144
+const DEFAULT_INITIATOR_MAX_RECV_DATA_SEGMENT_LENGTH = 8192 // RFC 7143 default
+
+/** Parse a NUL-delimited iSCSI text key=value data segment. */
+export function parseTextKeys(data: Buffer): Map<string, string> {
+  const keys = new Map<string, string>()
+  for (const pair of data.toString('utf8').split('\0')) {
+    if (pair.length === 0) {
+      continue
+    }
+    const eq = pair.indexOf('=')
+    if (eq !== -1) {
+      keys.set(pair.slice(0, eq), pair.slice(eq + 1))
+    }
+  }
+  return keys
+}
+
+/** Serialize key=value pairs into a NUL-delimited (and NUL-terminated) buffer. */
+export function serializeTextKeys(entries: ReadonlyArray<readonly [string, string]>): Buffer {
+  if (entries.length === 0) {
+    return Buffer.alloc(0)
+  }
+  return Buffer.from(entries.map(([key, value]) => `${key}=${value}\0`).join(''), 'utf8')
+}
+
+function parsePositiveInt(value: string | undefined, fallback: number): number {
+  if (value === undefined) {
+    return fallback
+  }
+  const parsed = Number.parseInt(value, 10)
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback
+}
+
+/**
+ * Format an `address:port,portal-group-tag` value for a SendTargets
+ * `TargetAddress`, per the iSCSI grammar:
+ * - unwrap IPv4-mapped IPv6 (`::ffff:1.2.3.4`, produced by a dual-stack socket
+ *   accepting an IPv4 connection) to plain IPv4, so initiators get a clean,
+ *   matchable portal;
+ * - bracket real IPv6 literals (`[2001:db8::1]:3260,1`).
+ */
+export function formatPortal(address: string, port: number): string {
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address)
+  const normalized = mapped !== null ? mapped[1] : address
+  const bracketed = isIP(normalized) === 6 ? `[${normalized}]` : normalized
+  return `${bracketed}:${port},1`
+}
+
+/** Build the SendTargets discovery Text Response data segment. */
+export function buildSendTargetsResponse(iqn: string, address: string, port: number): Buffer {
+  return serializeTextKeys([
+    ['TargetName', iqn],
+    ['TargetAddress', formatPortal(address, port)],
+  ])
+}
+
+/** Outcome of processing a single Login Request PDU. */
+export interface LoginStepResult {
+  /** Byte 1 (T/C/CSG/NSG) of the Login Response. */
+  flagsByte: number
+  /** Response key=value text segment. */
+  data: Buffer
+  /** Login Response Status-Class (byte 36). Defaults to SUCCESS when omitted. */
+  statusClass?: number
+  /** Login Response Status-Detail (byte 37). Defaults to 0 when omitted. */
+  statusDetail?: number
+}
+
+/** A rejected login: the Status-Class/Detail bytes the response must carry. */
+interface AuthFailure {
+  statusClass: number
+  statusDetail: number
+}
+
+/** CHAP authentication failure (RFC 7143 §11.1.5): Initiator Error / auth failure. */
+const AUTH_FAILURE: AuthFailure = {
+  statusClass: LoginStatusClass.INITIATOR_ERROR,
+  statusDetail: LoginStatusDetail.AUTHENTICATION_FAILURE,
+}
+
+/** Progress of the target-side one-way CHAP exchange (RFC 7143 §11.1.4). */
+type ChapState = 'none' | 'awaitAlgorithm' | 'awaitResponse' | 'authenticated' | 'failed'
+
+/**
+ * Negotiates one connection's login: the target is authoritative, so every
+ * key is answered with the pinned value, and RFC 7143's boolean rules
+ * guarantee the session collapses to the one supported path regardless of
+ * what the initiator offers.
+ *
+ * With {@link ChapCredentials}, the target challenges the initiator during
+ * security negotiation and refuses to reach the operational stage until it
+ * proves the secret; without one, it uses the legacy `AuthMethod=None` path.
+ */
+export class LoginNegotiator {
+  #firstResponseSent = false
+  #complete = false
+
+  readonly #chap?: ChapCredentials
+  #chapState: ChapState = 'none'
+  #chapId = 0
+  #chapChallenge: Buffer = EMPTY
+
+  sessionType: SessionType = 'Normal'
+  initiatorName?: string
+  targetName?: string
+  readonly params: NegotiatedParams = {
+    initiatorMaxRecvDataSegmentLength: DEFAULT_INITIATOR_MAX_RECV_DATA_SEGMENT_LENGTH,
+    maxBurstLength: OUR_MAX_BURST_LENGTH,
+  }
+
+  constructor(chap?: ChapCredentials) {
+    this.#chap = chap
+  }
+
+  /** True once the session has transited to the full-feature phase. */
+  get complete(): boolean {
+    return this.#complete
+  }
+
+  /** True once CHAP authentication has definitively failed for this connection. */
+  get failed(): boolean {
+    return this.#chapState === 'failed'
+  }
+
+  /** CHAP is enforced only when configured and only for Normal (data) sessions. */
+  get #chapRequired(): boolean {
+    return this.#chap !== undefined && this.sessionType === 'Normal'
+  }
+
+  process(pdu: IncomingPdu): LoginStepResult {
+    const flags = pdu.flags
+    const csg = (flags & LOGIN_CSG_MASK) >> LOGIN_CSG_SHIFT
+    const nsg = flags & LOGIN_NSG_MASK
+    const transit = (flags & LOGIN_FLAG_TRANSIT) !== 0
+    const cont = (flags & LOGIN_FLAG_CONTINUE) !== 0
+    const keys = parseTextKeys(pdu.data)
+    log.debug('login request', { csg, nsg, transit, cont, keys: Object.fromEntries(keys) })
+
+    const sessionType = keys.get('SessionType')
+    if (sessionType !== undefined) {
+      this.sessionType = sessionType === 'Discovery' ? 'Discovery' : 'Normal'
+    }
+    this.initiatorName ??= keys.get('InitiatorName')
+    this.targetName ??= keys.get('TargetName')
+
+    const responseKeys: Array<[string, string]> = []
+    // A normal session's first Login Response must carry the portal group tag.
+    if (!this.#firstResponseSent && this.sessionType === 'Normal') {
+      responseKeys.push(['TargetPortalGroupTag', '1'])
+    }
+
+    let failure: AuthFailure | undefined
+    if (csg === LoginStage.SECURITY_NEGOTIATION) {
+      // Act only on a complete key set (C bit clear); while the initiator is
+      // still sending keys we accumulate without answering the exchange.
+      if (!cont) {
+        failure = this.#handleSecurity(keys, responseKeys)
+      }
+    } else if (csg === LoginStage.OPERATIONAL_NEGOTIATION) {
+      if (this.#chapRequired && this.#chapState !== 'authenticated') {
+        // Normal session jumped to operational negotiation without completing the
+        // CHAP security stage we require.
+        this.#chapState = 'failed'
+        failure = AUTH_FAILURE
+      } else {
+        this.#negotiateOperational(keys, responseKeys)
+      }
+    }
+
+    let flagsByte = csg << LOGIN_CSG_SHIFT
+    // Transit only when the initiator asked to, is not still sending keys, and
+    // (if CHAP is required) authentication has succeeded. This single gate blocks
+    // a premature Transit bit and any transit before/without CHAP.
+    const authReady = !this.#chapRequired || this.#chapState === 'authenticated'
+    if (transit && !cont && authReady) {
+      flagsByte |= LOGIN_FLAG_TRANSIT | nsg
+      if (nsg === LoginStage.FULL_FEATURE_PHASE) {
+        this.#complete = true
+      }
+    }
+
+    this.#firstResponseSent = true
+    log.debug('login response', {
+      transit: (flagsByte & LOGIN_FLAG_TRANSIT) !== 0,
+      nsg: flagsByte & LOGIN_NSG_MASK,
+      keys: Object.fromEntries(responseKeys),
+      statusClass: failure?.statusClass ?? 0,
+      statusDetail: failure?.statusDetail ?? 0,
+      chapState: this.#chapState,
+    })
+    return {
+      flagsByte,
+      data: serializeTextKeys(responseKeys),
+      statusClass: failure?.statusClass,
+      statusDetail: failure?.statusDetail,
+    }
+  }
+
+  /**
+   * Drive one round of the target-side one-way CHAP exchange, mutating
+   * {@link ChapState} and appending any response keys. Returns an
+   * {@link AuthFailure} when authentication is rejected, otherwise `undefined`
+   * (success or "still in progress, awaiting the next PDU").
+   */
+  #handleSecurity(keys: Map<string, string>, responseKeys: Array<[string, string]>): AuthFailure | undefined {
+    // CHAP applies only to Normal (data) sessions. Discovery sessions can only
+    // run SendTargets — they never reach the LUN — so they negotiate
+    // AuthMethod=None, keeping the standard unauthenticated `iscsiadm -m
+    // discovery` flow working. Without CHAP configured, this is the only path.
+    const chap = this.#chap
+    if (chap === undefined || this.sessionType !== 'Normal') {
+      if (keys.has('AuthMethod')) {
+        responseKeys.push(['AuthMethod', AuthMethod.NONE])
+      }
+      return undefined
+    }
+
+    switch (this.#chapState) {
+      case 'none': {
+        const offer = keys.get('AuthMethod')
+        if (offer === undefined) {
+          return undefined // still waiting for the AuthMethod offer
+        }
+        if (!offer.split(',').includes(AuthMethod.CHAP)) {
+          // Initiator offered only None (or an unknown method) while we require CHAP.
+          log.debug('chap: initiator did not offer CHAP', { offered: offer })
+          this.#chapState = 'failed'
+          return AUTH_FAILURE
+        }
+        responseKeys.push(['AuthMethod', AuthMethod.CHAP])
+        this.#chapState = 'awaitAlgorithm'
+        return undefined
+      }
+      case 'awaitAlgorithm': {
+        const offered = keys.get('CHAP_A')
+        if (offered === undefined) {
+          return undefined // still waiting for CHAP_A
+        }
+        const algorithm = selectAlgorithm(parseAlgorithmList(offered))
+        if (algorithm === undefined) {
+          log.debug('chap: no supported algorithm offered', { offered })
+          this.#chapState = 'failed'
+          return AUTH_FAILURE
+        }
+        this.#chapId = generateId()
+        this.#chapChallenge = generateChallenge()
+        responseKeys.push(['CHAP_A', String(algorithm)])
+        responseKeys.push(['CHAP_I', String(this.#chapId)])
+        responseKeys.push(['CHAP_C', encodeChapValue(this.#chapChallenge)])
+        log.debug('chap: issued challenge', { algorithm, id: this.#chapId })
+        this.#chapState = 'awaitResponse'
+        return undefined
+      }
+      case 'awaitResponse': {
+        const name = keys.get('CHAP_N')
+        const response = keys.get('CHAP_R')
+        if (name === undefined || response === undefined) {
+          return undefined // still waiting for CHAP_N / CHAP_R
+        }
+        let got: Buffer
+        try {
+          got = decodeChapValue(response)
+        } catch {
+          this.#chapState = 'failed'
+          return AUTH_FAILURE
+        }
+        const expected = computeResponse(this.#chapId, chap.secret, this.#chapChallenge)
+        if (name === chap.user && verifyResponse(expected, got)) {
+          log.debug('chap: authenticated', { user: name })
+          this.#chapState = 'authenticated'
+          return undefined
+        }
+        log.debug('chap: verification failed', { user: name, userMatch: name === chap.user })
+        this.#chapState = 'failed'
+        return AUTH_FAILURE
+      }
+      default:
+        return undefined
+    }
+  }
+
+  #negotiateOperational(keys: Map<string, string>, responseKeys: Array<[string, string]>): void {
+    // Only answer what the initiator actually offered: for every key below, the
+    // RFC 7143 default of an unoffered key is already the value we want, so
+    // staying silent and letting the default stand is equivalent.
+    const answer = (key: string, value: string) => {
+      if (keys.has(key)) {
+        responseKeys.push([key, value])
+      }
+    }
+    answer('HeaderDigest', 'None')
+    answer('DataDigest', 'None')
+    answer('MaxConnections', '1')
+    answer('InitialR2T', 'Yes')
+    answer('ErrorRecoveryLevel', '0')
+
+    // ImmediateData is the one exception: its RFC 7143 default is *Yes*, so an
+    // initiator that never offers the key may legally put write data in the SCSI
+    // Command PDU itself — which this target does not implement and would
+    // otherwise silently drop, acknowledging a write it never applied. Declare
+    // No whether or not it was offered. Costs nothing: there is no immediate
+    // data path to lose, and every mainstream initiator offers the key anyway,
+    // so for them this is byte-identical to before.
+    responseKeys.push(['ImmediateData', 'No'])
+    answer('DataPDUInOrder', 'Yes')
+    answer('DataSequenceInOrder', 'Yes')
+    answer('DefaultTime2Wait', '2')
+    answer('DefaultTime2Retain', '0')
+    answer('MaxOutstandingR2T', '1')
+
+    // MaxRecvDataSegmentLength is declarative per direction: capture the
+    // initiator's (caps our Data-In) and always declare ours (caps its Data-Out).
+    this.params.initiatorMaxRecvDataSegmentLength = parsePositiveInt(
+      keys.get('MaxRecvDataSegmentLength'),
+      this.params.initiatorMaxRecvDataSegmentLength
+    )
+    responseKeys.push(['MaxRecvDataSegmentLength', String(OUR_MAX_RECV_DATA_SEGMENT_LENGTH)])
+
+    // MaxBurstLength / FirstBurstLength negotiate to the minimum of both offers.
+    const maxBurst = Math.min(parsePositiveInt(keys.get('MaxBurstLength'), OUR_MAX_BURST_LENGTH), OUR_MAX_BURST_LENGTH)
+    this.params.maxBurstLength = maxBurst
+    if (keys.has('MaxBurstLength')) {
+      responseKeys.push(['MaxBurstLength', String(maxBurst)])
+    }
+    if (keys.has('FirstBurstLength')) {
+      const firstBurst = Math.min(parsePositiveInt(keys.get('FirstBurstLength'), maxBurst), maxBurst)
+      responseKeys.push(['FirstBurstLength', String(firstBurst)])
+    }
+  }
+}

@vates/iscsi/src/login.test.mts

@@ -0,0 +1,313 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import {
+  InitiatorOpcode,
+  LOGIN_CSG_SHIFT,
+  LOGIN_FLAG_CONTINUE,
+  LOGIN_FLAG_TRANSIT,
+  LOGIN_NSG_MASK,
+  LoginStage,
+  LoginStatusClass,
+  LoginStatusDetail,
+  OPCODE_IMMEDIATE,
+} from './constants.mjs'
+import { buildSendTargetsResponse, formatPortal, LoginNegotiator, parseTextKeys, serializeTextKeys } from './login.mjs'
+import { computeResponse, decodeChapValue, encodeChapValue } from './chap.mjs'
+import { IncomingPdu } from './pdu.mjs'
+
+function loginFlags(options: { transit?: boolean; cont?: boolean; csg: number; nsg: number }): number {
+  return (
+    (options.transit ? LOGIN_FLAG_TRANSIT : 0) |
+    (options.cont ? LOGIN_FLAG_CONTINUE : 0) |
+    (options.csg << LOGIN_CSG_SHIFT) |
+    (options.nsg & LOGIN_NSG_MASK)
+  )
+}
+
+function makeLoginPdu(flags: number, keys: Record<string, string>): IncomingPdu {
+  const bhs = Buffer.alloc(48)
+  bhs[0] = InitiatorOpcode.LOGIN_REQUEST | OPCODE_IMMEDIATE
+  bhs[1] = flags
+  const data = serializeTextKeys(Object.entries(keys))
+  return new IncomingPdu(bhs, Buffer.alloc(0), data)
+}
+
+describe('text key serialization', () => {
+  it('round-trips NUL-delimited key=value pairs', () => {
+    const buffer = serializeTextKeys([
+      ['A', '1'],
+      ['HeaderDigest', 'None'],
+    ])
+    assert.equal(buffer.toString('binary'), 'A=1\0HeaderDigest=None\0')
+    const keys = parseTextKeys(buffer)
+    assert.equal(keys.get('A'), '1')
+    assert.equal(keys.get('HeaderDigest'), 'None')
+  })
+
+  it('ignores empty fragments and malformed pairs', () => {
+    const keys = parseTextKeys(Buffer.from('\0Key=Value\0bogus\0', 'binary'))
+    assert.equal(keys.size, 1)
+    assert.equal(keys.get('Key'), 'Value')
+  })
+})
+
+describe('LoginNegotiator', () => {
+  it('completes a single-PDU operational login and pins the negotiated values', () => {
+    const negotiator = new LoginNegotiator()
+    const pdu = makeLoginPdu(
+      loginFlags({
+        transit: true,
+        csg: LoginStage.OPERATIONAL_NEGOTIATION,
+        nsg: LoginStage.FULL_FEATURE_PHASE,
+      }),
+      {
+        InitiatorName: 'iqn.1994-05.com.example:initiator',
+        SessionType: 'Normal',
+        HeaderDigest: 'None,CRC32C',
+        DataDigest: 'None,CRC32C',
+        InitialR2T: 'No',
+        ImmediateData: 'Yes',
+        MaxRecvDataSegmentLength: '262144',
+        MaxBurstLength: '16776192',
+      }
+    )
+    const { flagsByte, data } = negotiator.process(pdu)
+
+    assert.equal(negotiator.complete, true)
+    assert.ok((flagsByte & LOGIN_FLAG_TRANSIT) !== 0)
+    assert.equal(flagsByte & LOGIN_NSG_MASK, LoginStage.FULL_FEATURE_PHASE)
+
+    const keys = parseTextKeys(data)
+    assert.equal(keys.get('TargetPortalGroupTag'), '1')
+    assert.equal(keys.get('HeaderDigest'), 'None')
+    assert.equal(keys.get('DataDigest'), 'None')
+    // Pinned to the single write code path regardless of the initiator's offer.
+    assert.equal(keys.get('InitialR2T'), 'Yes')
+    assert.equal(keys.get('ImmediateData'), 'No')
+    // MaxBurstLength negotiates down to our cap.
+    assert.equal(keys.get('MaxBurstLength'), '262144')
+
+    assert.equal(negotiator.sessionType, 'Normal')
+    assert.equal(negotiator.initiatorName, 'iqn.1994-05.com.example:initiator')
+    assert.equal(negotiator.params.initiatorMaxRecvDataSegmentLength, 262144)
+    assert.equal(negotiator.params.maxBurstLength, 262144)
+  })
+
+  it('handles a two-stage security then operational login', () => {
+    const negotiator = new LoginNegotiator()
+
+    const security = negotiator.process(
+      makeLoginPdu(
+        loginFlags({
+          transit: true,
+          csg: LoginStage.SECURITY_NEGOTIATION,
+          nsg: LoginStage.OPERATIONAL_NEGOTIATION,
+        }),
+        { InitiatorName: 'iqn.x:i', SessionType: 'Normal', AuthMethod: 'None' }
+      )
+    )
+    assert.equal(negotiator.complete, false)
+    assert.equal(parseTextKeys(security.data).get('AuthMethod'), 'None')
+
+    const operational = negotiator.process(
+      makeLoginPdu(
+        loginFlags({
+          transit: true,
+          csg: LoginStage.OPERATIONAL_NEGOTIATION,
+          nsg: LoginStage.FULL_FEATURE_PHASE,
+        }),
+        { HeaderDigest: 'None', DataDigest: 'None' }
+      )
+    )
+    assert.equal(negotiator.complete, true)
+    // The portal group tag is only emitted in the first response.
+    assert.equal(parseTextKeys(operational.data).get('TargetPortalGroupTag'), undefined)
+  })
+
+  it('omits the portal group tag for a discovery session', () => {
+    const negotiator = new LoginNegotiator()
+    const { data } = negotiator.process(
+      makeLoginPdu(
+        loginFlags({
+          transit: true,
+          csg: LoginStage.OPERATIONAL_NEGOTIATION,
+          nsg: LoginStage.FULL_FEATURE_PHASE,
+        }),
+        { SessionType: 'Discovery' }
+      )
+    )
+    assert.equal(negotiator.sessionType, 'Discovery')
+    assert.equal(parseTextKeys(data).get('TargetPortalGroupTag'), undefined)
+  })
+
+  it('does not transit while the initiator is still sending keys (C bit)', () => {
+    const negotiator = new LoginNegotiator()
+    const { flagsByte } = negotiator.process(
+      makeLoginPdu(
+        loginFlags({
+          transit: true,
+          cont: true,
+          csg: LoginStage.OPERATIONAL_NEGOTIATION,
+          nsg: LoginStage.FULL_FEATURE_PHASE,
+        }),
+        { HeaderDigest: 'None' }
+      )
+    )
+    assert.equal(negotiator.complete, false)
+    assert.equal(flagsByte & LOGIN_FLAG_TRANSIT, 0)
+  })
+})
+
+describe('LoginNegotiator CHAP authenticator', () => {
+  const CHAP = { user: 'alice', secret: 's3cr3t' }
+
+  const securityFlags = (transit = false) =>
+    loginFlags({ transit, csg: LoginStage.SECURITY_NEGOTIATION, nsg: LoginStage.OPERATIONAL_NEGOTIATION })
+
+  /** Round 1: offer AuthMethod. */
+  function offerAuth(negotiator: LoginNegotiator, methods = 'CHAP,None', transit = false) {
+    return negotiator.process(
+      makeLoginPdu(securityFlags(transit), { InitiatorName: 'iqn.x:i', SessionType: 'Normal', AuthMethod: methods })
+    )
+  }
+
+  /** Round 2: offer CHAP_A, return the target's parsed challenge keys. */
+  function offerAlgorithm(negotiator: LoginNegotiator, list = '5') {
+    const result = negotiator.process(makeLoginPdu(securityFlags(false), { CHAP_A: list }))
+    return { result, keys: parseTextKeys(result.data) }
+  }
+
+  /** Round 3: answer with CHAP_N/CHAP_R for the given challenge. */
+  function answerChallenge(
+    negotiator: LoginNegotiator,
+    challengeKeys: Map<string, string>,
+    { user = CHAP.user, secret = CHAP.secret } = {}
+  ) {
+    const id = Number.parseInt(challengeKeys.get('CHAP_I') ?? '', 10)
+    const challenge = decodeChapValue(challengeKeys.get('CHAP_C') ?? '')
+    const response = encodeChapValue(computeResponse(id, secret, challenge))
+    return negotiator.process(makeLoginPdu(securityFlags(true), { CHAP_N: user, CHAP_R: response }))
+  }
+
+  it('challenges then transits only after a correct response', () => {
+    const negotiator = new LoginNegotiator(CHAP)
+
+    // Round 1: we answer AuthMethod=CHAP and do NOT transit.
+    const r1 = offerAuth(negotiator)
+    assert.equal(parseTextKeys(r1.data).get('AuthMethod'), 'CHAP')
+    assert.equal(r1.flagsByte & LOGIN_FLAG_TRANSIT, 0)
+    assert.equal(r1.statusClass ?? LoginStatusClass.SUCCESS, LoginStatusClass.SUCCESS)
+
+    // Round 2: we issue CHAP_A=5, an identifier and a challenge, still no transit.
+    const { result: r2, keys: challenge } = offerAlgorithm(negotiator)
+    assert.equal(challenge.get('CHAP_A'), '5')
+    assert.ok(challenge.has('CHAP_I'))
+    assert.match(challenge.get('CHAP_C') ?? '', /^0x[0-9a-f]+$/)
+    assert.equal(r2.flagsByte & LOGIN_FLAG_TRANSIT, 0)
+
+    // Round 3: a correct response transits to the operational stage.
+    const r3 = answerChallenge(negotiator, challenge)
+    assert.equal(r3.statusClass ?? LoginStatusClass.SUCCESS, LoginStatusClass.SUCCESS)
+    assert.ok((r3.flagsByte & LOGIN_FLAG_TRANSIT) !== 0, 'transit granted after auth')
+    assert.equal(r3.flagsByte & LOGIN_NSG_MASK, LoginStage.OPERATIONAL_NEGOTIATION)
+    assert.equal(negotiator.failed, false)
+
+    // The operational stage then completes as usual.
+    const op = negotiator.process(
+      makeLoginPdu(
+        loginFlags({ transit: true, csg: LoginStage.OPERATIONAL_NEGOTIATION, nsg: LoginStage.FULL_FEATURE_PHASE }),
+        { HeaderDigest: 'None', DataDigest: 'None' }
+      )
+    )
+    assert.equal(negotiator.complete, true)
+    assert.equal(parseTextKeys(op.data).get('HeaderDigest'), 'None')
+  })
+
+  it('rejects a wrong secret with Initiator Error / authentication failure', () => {
+    const negotiator = new LoginNegotiator(CHAP)
+    offerAuth(negotiator)
+    const { keys: challenge } = offerAlgorithm(negotiator)
+    const r3 = answerChallenge(negotiator, challenge, { secret: 'wrong' })
+
+    assert.equal(r3.statusClass, LoginStatusClass.INITIATOR_ERROR)
+    assert.equal(r3.statusDetail, LoginStatusDetail.AUTHENTICATION_FAILURE)
+    assert.equal(r3.flagsByte & LOGIN_FLAG_TRANSIT, 0)
+    assert.equal(negotiator.complete, false)
+    assert.equal(negotiator.failed, true)
+  })
+
+  it('rejects a wrong username even with the right secret', () => {
+    const negotiator = new LoginNegotiator(CHAP)
+    offerAuth(negotiator)
+    const { keys: challenge } = offerAlgorithm(negotiator)
+    const r3 = answerChallenge(negotiator, challenge, { user: 'mallory' })
+    assert.equal(r3.statusClass, LoginStatusClass.INITIATOR_ERROR)
+    assert.equal(negotiator.failed, true)
+  })
+
+  it('fails when the initiator offers only AuthMethod=None', () => {
+    const negotiator = new LoginNegotiator(CHAP)
+    const r1 = offerAuth(negotiator, 'None')
+    assert.equal(r1.statusClass, LoginStatusClass.INITIATOR_ERROR)
+    assert.equal(r1.statusDetail, LoginStatusDetail.AUTHENTICATION_FAILURE)
+    assert.equal(negotiator.failed, true)
+  })
+
+  it('fails when CHAP_A does not offer MD5', () => {
+    const negotiator = new LoginNegotiator(CHAP)
+    offerAuth(negotiator)
+    const { result } = offerAlgorithm(negotiator, '6,7')
+    assert.equal(result.statusClass, LoginStatusClass.INITIATOR_ERROR)
+    assert.equal(negotiator.failed, true)
+  })
+
+  it('does not transit if the initiator sets the T bit before authenticating', () => {
+    const negotiator = new LoginNegotiator(CHAP)
+    // Round 1 with the Transit bit set: must be ignored until CHAP completes.
+    const r1 = offerAuth(negotiator, 'CHAP,None', true)
+    assert.equal(r1.flagsByte & LOGIN_FLAG_TRANSIT, 0)
+    assert.equal(negotiator.complete, false)
+  })
+
+  it('fails if the initiator skips security and jumps to operational negotiation', () => {
+    const negotiator = new LoginNegotiator(CHAP)
+    const result = negotiator.process(
+      makeLoginPdu(
+        loginFlags({ transit: true, csg: LoginStage.OPERATIONAL_NEGOTIATION, nsg: LoginStage.FULL_FEATURE_PHASE }),
+        { HeaderDigest: 'None' }
+      )
+    )
+    assert.equal(result.statusClass, LoginStatusClass.INITIATOR_ERROR)
+    assert.equal(result.flagsByte & LOGIN_FLAG_TRANSIT, 0)
+    assert.equal(negotiator.complete, false)
+    assert.equal(negotiator.failed, true)
+  })
+})
+
+describe('formatPortal', () => {
+  it('keeps plain IPv4 addresses', () => {
+    assert.equal(formatPortal('10.0.0.1', 3260), '10.0.0.1:3260,1')
+  })
+
+  it('unwraps IPv4-mapped IPv6 (dual-stack socket artifact)', () => {
+    assert.equal(formatPortal('::ffff:192.168.1.8', 3260), '192.168.1.8:3260,1')
+  })
+
+  it('brackets real IPv6 literals', () => {
+    assert.equal(formatPortal('2a01:e0a:e6a:9500::1', 3260), '[2a01:e0a:e6a:9500::1]:3260,1')
+  })
+})
+
+describe('buildSendTargetsResponse', () => {
+  it('advertises the target name and address', () => {
+    const keys = parseTextKeys(buildSendTargetsResponse('iqn.2024-01.tech.vates:lun0', '10.0.0.1', 3260))
+    assert.equal(keys.get('TargetName'), 'iqn.2024-01.tech.vates:lun0')
+    assert.equal(keys.get('TargetAddress'), '10.0.0.1:3260,1')
+  })
+
+  it('advertises a clean IPv4 portal for an IPv4-mapped local address', () => {
+    const keys = parseTextKeys(buildSendTargetsResponse('iqn.x:y', '::ffff:192.168.1.8', 3260))
+    assert.equal(keys.get('TargetAddress'), '192.168.1.8:3260,1')
+  })
+})

@vates/iscsi/src/loopback.integ.mts

@@ -0,0 +1,933 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, readFile, rm, truncate, writeFile } from 'node:fs/promises'
+import { connect, type Socket } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { once } from 'node:events'
+import { after, before, describe, it } from 'node:test'
+
+import {
+  DATA_IN_FLAG_STATUS,
+  FLAG_FINAL,
+  InitiatorOpcode,
+  LOGIN_FLAG_TRANSIT,
+  LOGIN_NSG_MASK,
+  LoginStage,
+  OPCODE_IMMEDIATE,
+  ScsiStatus,
+  TargetOpcode,
+} from './constants.mjs'
+import { RandomAccessDisk, type DiskBlock } from '@xen-orchestra/disk-transform'
+import type { BlockDevice } from './backend.mjs'
+import {
+  CachedDiskBlockDevice,
+  DiskBlockDevice,
+  FileBlockDevice,
+  IscsiDisk,
+  IscsiInitiator,
+  IscsiTarget,
+} from './index.mjs'
+import { allocBhs, assemblePdu, type IncomingPdu, readPdu } from './pdu.mjs'
+import { parseTextKeys, serializeTextKeys } from './login.mjs'
+
+const IQN = 'iqn.2024-01.tech.vates:loopback'
+const LUN_SIZE = 1024 * 1024 // 1 MiB
+const BLOCK_SIZE = 512
+
+// --- a minimal in-process iSCSI initiator (test-only) -----------------------
+//
+// Speaks just enough of the protocol to exercise the target end to end. It
+// reuses the package's framing helpers (independently covered by pdu.test); the
+// assertions here are on the target's session/SCSI behavior and data integrity.
+
+const READ_BIT = 0x40
+const WRITE_BIT = 0x20
+
+function send(socket: Socket, buffer: Buffer): Promise<void> {
+  return new Promise((resolve, reject) => {
+    socket.write(buffer, error => (error ? reject(error) : resolve()))
+  })
+}
+
+async function expectPdu(socket: Socket, opcode: number): Promise<IncomingPdu> {
+  const pdu = await readPdu(socket)
+  assert.ok(pdu !== null, 'expected a PDU, got end-of-stream')
+  assert.equal(pdu.opcode, opcode, `expected opcode 0x${opcode.toString(16)}, got 0x${pdu.opcode.toString(16)}`)
+  return pdu
+}
+
+class MiniInitiator {
+  #socket: Socket
+  #itt = 0
+  #cmdSN = 0
+
+  constructor(socket: Socket) {
+    this.#socket = socket
+  }
+
+  #nextItt(): number {
+    return ++this.#itt
+  }
+
+  async login(sessionType: 'Normal' | 'Discovery'): Promise<void> {
+    const bhs = allocBhs(InitiatorOpcode.LOGIN_REQUEST | OPCODE_IMMEDIATE)
+    bhs[1] = LOGIN_FLAG_TRANSIT | (LoginStage.OPERATIONAL_NEGOTIATION << 2) | LoginStage.FULL_FEATURE_PHASE
+    Buffer.from([0x80, 0, 0, 0, 0, 1]).copy(bhs, 8) // ISID
+    bhs.writeUInt32BE(this.#nextItt(), 16)
+    bhs.writeUInt32BE(this.#cmdSN, 24)
+    const keys: Array<[string, string]> = [
+      ['InitiatorName', 'iqn.1994-05.com.example:test'],
+      ['SessionType', sessionType],
+      ['HeaderDigest', 'None'],
+      ['DataDigest', 'None'],
+      ['MaxRecvDataSegmentLength', '262144'],
+    ]
+    if (sessionType === 'Normal') {
+      keys.push(['TargetName', IQN])
+    }
+    await send(this.#socket, assemblePdu(bhs, serializeTextKeys(keys)))
+
+    const response = await expectPdu(this.#socket, TargetOpcode.LOGIN_RESPONSE)
+    assert.equal(response.bhs[36], 0, 'login status-class should be success')
+    assert.ok((response.bhs[1] & LOGIN_FLAG_TRANSIT) !== 0, 'should transit')
+    assert.equal(response.bhs[1] & LOGIN_NSG_MASK, LoginStage.FULL_FEATURE_PHASE)
+  }
+
+  async sendTargets(): Promise<Map<string, string>> {
+    const bhs = allocBhs(InitiatorOpcode.TEXT_REQUEST | OPCODE_IMMEDIATE)
+    bhs[1] = FLAG_FINAL
+    bhs.writeUInt32BE(this.#nextItt(), 16)
+    bhs.writeUInt32BE(0xffffffff, 20) // Target Transfer Tag: none
+    bhs.writeUInt32BE(this.#cmdSN, 24)
+    await send(this.#socket, assemblePdu(bhs, serializeTextKeys([['SendTargets', 'All']])))
+    const response = await expectPdu(this.#socket, TargetOpcode.TEXT_RESPONSE)
+    return parseTextKeys(response.data)
+  }
+
+  #scsiCommandBhs(cdb: Buffer, flags: number, edtl: number): Buffer {
+    const bhs = allocBhs(InitiatorOpcode.SCSI_COMMAND)
+    bhs[1] = FLAG_FINAL | flags
+    bhs.writeUInt32BE(this.#nextItt(), 16)
+    bhs.writeUInt32BE(edtl, 20)
+    bhs.writeUInt32BE(this.#cmdSN++, 24)
+    cdb.copy(bhs, 32)
+    return bhs
+  }
+
+  /** Issue a read-type command and collect Data-In; returns the assembled data + status. */
+  async read(cdb: Buffer, edtl: number): Promise<{ data: Buffer; status: number }> {
+    await send(this.#socket, assemblePdu(this.#scsiCommandBhs(cdb, READ_BIT, edtl)))
+    const chunks: Buffer[] = []
+    for (;;) {
+      const pdu = await readPdu(this.#socket)
+      assert.ok(pdu !== null)
+      if (pdu.opcode === TargetOpcode.SCSI_DATA_IN) {
+        chunks.push(pdu.data)
+        if ((pdu.flags & DATA_IN_FLAG_STATUS) !== 0) {
+          return { data: Buffer.concat(chunks), status: pdu.bhs[3] }
+        }
+      } else if (pdu.opcode === TargetOpcode.SCSI_RESPONSE) {
+        return { data: Buffer.concat(chunks), status: pdu.bhs[3] }
+      } else {
+        assert.fail(`unexpected opcode during read: 0x${pdu.opcode.toString(16)}`)
+      }
+    }
+  }
+
+  /** Issue a write-type command, satisfy its R2Ts with Data-Out, return the final status. */
+  async write(cdb: Buffer, payload: Buffer): Promise<number> {
+    const itt = this.#itt + 1 // matches the ITT #scsiCommandBhs is about to allocate
+    await send(this.#socket, assemblePdu(this.#scsiCommandBhs(cdb, WRITE_BIT, payload.length)))
+    for (;;) {
+      const pdu = await readPdu(this.#socket)
+      assert.ok(pdu !== null)
+      if (pdu.opcode === TargetOpcode.R2T) {
+        const ttt = pdu.readU32(20)
+        const bufferOffset = pdu.readU32(40)
+        const desiredLength = pdu.readU32(44)
+        const dataOut = allocBhs(InitiatorOpcode.SCSI_DATA_OUT)
+        dataOut[1] = FLAG_FINAL
+        dataOut.writeUInt32BE(itt, 16)
+        dataOut.writeUInt32BE(ttt, 20)
+        dataOut.writeUInt32BE(bufferOffset, 40)
+        await send(this.#socket, assemblePdu(dataOut, payload.subarray(bufferOffset, bufferOffset + desiredLength)))
+      } else if (pdu.opcode === TargetOpcode.SCSI_RESPONSE) {
+        return pdu.bhs[3]
+      } else {
+        assert.fail(`unexpected opcode during write: 0x${pdu.opcode.toString(16)}`)
+      }
+    }
+  }
+
+  // --- low-level primitives (for explicit, interleaved orchestration) -------
+
+  /** Send a SCSI Command without consuming any reply; returns its ITT. */
+  async scsiCommand(cdb: Buffer, kind: 'read' | 'write' | 'none', edtl: number): Promise<number> {
+    const flags = kind === 'read' ? READ_BIT : kind === 'write' ? WRITE_BIT : 0
+    await send(this.#socket, assemblePdu(this.#scsiCommandBhs(cdb, flags, edtl)))
+    return this.#itt
+  }
+
+  /** Read the next inbound PDU. */
+  async recv(): Promise<IncomingPdu> {
+    const pdu = await readPdu(this.#socket)
+    assert.ok(pdu !== null, 'expected a PDU, got end-of-stream')
+    return pdu
+  }
+
+  /** Send a single (final) Data-Out PDU for `itt` carrying `payload` at offset 0. */
+  async dataOut(itt: number, targetTransferTag: number, payload: Buffer): Promise<void> {
+    const bhs = allocBhs(InitiatorOpcode.SCSI_DATA_OUT)
+    bhs[1] = FLAG_FINAL
+    bhs.writeUInt32BE(itt, 16)
+    bhs.writeUInt32BE(targetTransferTag, 20)
+    bhs.writeUInt32BE(0, 40) // buffer offset
+    await send(this.#socket, assemblePdu(bhs, payload))
+  }
+
+  async logout(): Promise<void> {
+    const bhs = allocBhs(InitiatorOpcode.LOGOUT_REQUEST | OPCODE_IMMEDIATE)
+    bhs[1] = FLAG_FINAL // reason 0: close the session
+    bhs.writeUInt32BE(this.#nextItt(), 16)
+    bhs.writeUInt32BE(this.#cmdSN, 24)
+    await send(this.#socket, assemblePdu(bhs))
+    const response = await expectPdu(this.#socket, TargetOpcode.LOGOUT_RESPONSE)
+    assert.equal(response.bhs[2], 0, 'logout should succeed')
+  }
+}
+
+function readCapacity10Cdb(): Buffer {
+  const cdb = Buffer.alloc(16)
+  cdb[0] = 0x25
+  return cdb
+}
+function inquiryCdb(allocationLength: number): Buffer {
+  const cdb = Buffer.alloc(16)
+  cdb[0] = 0x12
+  cdb.writeUInt16BE(allocationLength, 3)
+  return cdb
+}
+function reportLunsCdb(allocationLength: number): Buffer {
+  const cdb = Buffer.alloc(16)
+  cdb[0] = 0xa0
+  cdb.writeUInt32BE(allocationLength, 6)
+  return cdb
+}
+function rwCdb(opcode: number, lba: number, blocks: number): Buffer {
+  const cdb = Buffer.alloc(16)
+  cdb[0] = opcode
+  cdb.writeUInt32BE(lba, 2)
+  cdb.writeUInt16BE(blocks, 7)
+  return cdb
+}
+
+describe('iSCSI target loopback', () => {
+  let dir: string
+  let backingPath: string
+  let target: IscsiTarget
+  let port: number
+
+  before(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'vates-iscsi-'))
+    backingPath = join(dir, 'lun.img')
+    await writeFile(backingPath, Buffer.alloc(0))
+    await truncate(backingPath, LUN_SIZE)
+
+    target = new IscsiTarget({
+      iqn: IQN,
+      host: '127.0.0.1',
+      port: 0, // ephemeral
+      lun: new FileBlockDevice({ path: backingPath, blockSize: BLOCK_SIZE }),
+    })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+    port = address.port
+  })
+
+  after(async () => {
+    await target?.close()
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  async function open(): Promise<Socket> {
+    const socket = connect(port, '127.0.0.1')
+    await once(socket, 'connect')
+    return socket
+  }
+
+  it('answers SendTargets discovery with the target IQN', async () => {
+    const socket = await open()
+    try {
+      const initiator = new MiniInitiator(socket)
+      await initiator.login('Discovery')
+      const keys = await initiator.sendTargets()
+      assert.equal(keys.get('TargetName'), IQN)
+      assert.match(keys.get('TargetAddress') ?? '', /^127\.0\.0\.1:\d+,1$/)
+      await initiator.logout()
+    } finally {
+      socket.destroy()
+    }
+  })
+
+  it('reports identity, capacity, and a single LUN', async () => {
+    const socket = await open()
+    try {
+      const initiator = new MiniInitiator(socket)
+      await initiator.login('Normal')
+
+      const inquiry = await initiator.read(inquiryCdb(36), 36)
+      assert.equal(inquiry.status, ScsiStatus.GOOD)
+      assert.equal(inquiry.data[0], 0x00, 'direct-access block device')
+
+      const reportLuns = await initiator.read(reportLunsCdb(64), 64)
+      assert.equal(reportLuns.status, ScsiStatus.GOOD)
+      assert.equal(reportLuns.data.readUInt32BE(0), 8, 'one LUN reported')
+
+      const capacity = await initiator.read(readCapacity10Cdb(), 8)
+      assert.equal(capacity.status, ScsiStatus.GOOD)
+      assert.equal(capacity.data.readUInt32BE(0), LUN_SIZE / BLOCK_SIZE - 1, 'max LBA')
+      assert.equal(capacity.data.readUInt32BE(4), BLOCK_SIZE)
+
+      await initiator.logout()
+    } finally {
+      socket.destroy()
+    }
+  })
+
+  it('writes blocks (R2T/Data-Out) and reads them back identically', async () => {
+    const socket = await open()
+    try {
+      const initiator = new MiniInitiator(socket)
+      await initiator.login('Normal')
+
+      // A recognizable multi-block pattern starting at LBA 3.
+      const blocks = 4
+      const payload = Buffer.alloc(blocks * BLOCK_SIZE)
+      for (let i = 0; i < payload.length; i++) {
+        payload[i] = (i * 7 + 1) & 0xff
+      }
+      const lba = 3
+
+      const writeStatus = await initiator.write(rwCdb(0x2a, lba, blocks), payload)
+      assert.equal(writeStatus, ScsiStatus.GOOD)
+
+      const readBack = await initiator.read(rwCdb(0x28, lba, blocks), payload.length)
+      assert.equal(readBack.status, ScsiStatus.GOOD)
+      assert.deepEqual(readBack.data, payload, 'read data matches what was written')
+
+      await initiator.logout()
+    } finally {
+      socket.destroy()
+    }
+
+    // The bytes must have actually landed in the backing file at the right offset.
+    const onDisk = await readFile(backingPath)
+    const expected = Buffer.alloc(BLOCK_SIZE)
+    for (let i = 0; i < BLOCK_SIZE; i++) {
+      expected[i] = (i * 7 + 1) & 0xff // first written block
+    }
+    assert.deepEqual(onDisk.subarray(3 * BLOCK_SIZE, 4 * BLOCK_SIZE), expected)
+  })
+
+  // Regression test: real initiators (open-iscsi) send other commands while a
+  // WRITE is awaiting its Data-Out. The target must service them and still
+  // complete the write — not tear the connection down.
+  it('services an interleaved command between R2T and Data-Out', async () => {
+    const socket = await open()
+    try {
+      const initiator = new MiniInitiator(socket)
+      await initiator.login('Normal')
+
+      const payload = Buffer.alloc(BLOCK_SIZE, 0x3c)
+
+      // 1. Issue a WRITE and receive its R2T, but do not send Data-Out yet.
+      const writeItt = await initiator.scsiCommand(rwCdb(0x2a, 5, 1), 'write', BLOCK_SIZE)
+      const r2t = await initiator.recv()
+      assert.equal(r2t.opcode, TargetOpcode.R2T)
+      assert.equal(r2t.itt, writeItt)
+      const ttt = r2t.readU32(20)
+
+      // 2. Interleave a READ CAPACITY before satisfying the write.
+      const capItt = await initiator.scsiCommand(readCapacity10Cdb(), 'read', 8)
+      const capacity = await initiator.recv()
+      assert.equal(capacity.opcode, TargetOpcode.SCSI_DATA_IN)
+      assert.equal(capacity.itt, capItt)
+      assert.equal(capacity.data.readUInt32BE(0), LUN_SIZE / BLOCK_SIZE - 1)
+
+      // 3. Now send the write's Data-Out; the write must complete with GOOD.
+      await initiator.dataOut(writeItt, ttt, payload)
+      const response = await initiator.recv()
+      assert.equal(response.opcode, TargetOpcode.SCSI_RESPONSE)
+      assert.equal(response.itt, writeItt)
+      assert.equal(response.bhs[3], ScsiStatus.GOOD)
+
+      // 4. The interleaved write must have persisted correctly.
+      const readBack = await initiator.read(rwCdb(0x28, 5, 1), BLOCK_SIZE)
+      assert.deepEqual(readBack.data, payload)
+
+      await initiator.logout()
+    } finally {
+      socket.destroy()
+    }
+  })
+
+  // The real IscsiInitiator drives the same target, exercising the client login
+  // driver and the READ backlog/read-loop against the actual server.
+  it('reads the LUN through the IscsiInitiator client', async () => {
+    const initiator = new IscsiInitiator({ host: '127.0.0.1', port, targetIqn: IQN })
+    await initiator.connect()
+    try {
+      assert.equal(initiator.getSize(), LUN_SIZE)
+      assert.equal(initiator.getBlockSize(), BLOCK_SIZE)
+      // Block 3 was written by the earlier test; read it back over READ(16).
+      const data = await initiator.read(3 * BLOCK_SIZE, BLOCK_SIZE)
+      const expected = Buffer.alloc(BLOCK_SIZE)
+      for (let i = 0; i < BLOCK_SIZE; i++) {
+        expected[i] = (i * 7 + 1) & 0xff
+      }
+      assert.deepEqual(data, expected)
+    } finally {
+      await initiator.close()
+    }
+  })
+})
+
+// Regression coverage for concurrent READ dispatch: a slow read must not block
+// a subsequently-dispatched fast one, and StatSN on the wire must still come
+// out strictly increasing in actual completion/transmission order — not
+// necessarily dispatch order.
+describe('concurrent READ dispatch', () => {
+  it('services a fast read before an earlier, slower one — StatSN follows completion order', async () => {
+    let releaseSlow: () => void
+    const slowGate = new Promise<void>(resolve => {
+      releaseSlow = resolve
+    })
+    const lun: BlockDevice = {
+      getSize: () => LUN_SIZE,
+      getBlockSize: () => BLOCK_SIZE,
+      read: async (offset, length) => {
+        if (offset === 0) {
+          await slowGate // LBA 0 is the slow one
+        }
+        return Buffer.alloc(length, offset === 0 ? 0xaa : 0xbb)
+      },
+      write: async () => {
+        throw new Error('not used by this test')
+      },
+      flush: async () => {},
+      close: async () => {},
+    }
+
+    const target = new IscsiTarget({ iqn: IQN, host: '127.0.0.1', port: 0, lun })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+
+    const socket = connect(address.port, '127.0.0.1')
+    await once(socket, 'connect')
+    // Both IscsiTarget and IscsiInitiator disable Nagle internally; this raw
+    // test socket doesn't get that for free, and these tests send several
+    // commands back to back with no read in between — exactly the pattern
+    // Nagle + delayed ACK stalls (~40ms observed without this).
+    socket.setNoDelay(true)
+    try {
+      const initiator = new MiniInitiator(socket)
+      await initiator.login('Normal')
+
+      // Dispatch the slow read (LBA 0) first, then the fast one (LBA 1),
+      // without waiting for either's response — exactly what a real
+      // initiator with a command window > 1 already does.
+      const slowItt = await initiator.scsiCommand(rwCdb(0x28, 0, 1), 'read', BLOCK_SIZE)
+      const fastItt = await initiator.scsiCommand(rwCdb(0x28, 1, 1), 'read', BLOCK_SIZE)
+
+      // The fast one must complete first: proof the read loop didn't block
+      // on the slow one before even starting the fast one's I/O.
+      const fastPdu = await initiator.recv()
+      assert.equal(fastPdu.itt, fastItt)
+      assert.deepEqual(fastPdu.data, Buffer.alloc(BLOCK_SIZE, 0xbb))
+      const fastStatSN = fastPdu.readU32(24)
+
+      releaseSlow!()
+
+      const slowPdu = await initiator.recv()
+      assert.equal(slowPdu.itt, slowItt)
+      assert.deepEqual(slowPdu.data, Buffer.alloc(BLOCK_SIZE, 0xaa))
+      const slowStatSN = slowPdu.readU32(24)
+
+      // StatSN reflects actual transmission order (fast, then slow) even
+      // though the slow one's command was dispatched first.
+      assert.ok(slowStatSN > fastStatSN, `expected slow StatSN (${slowStatSN}) > fast StatSN (${fastStatSN})`)
+
+      await initiator.logout()
+    } finally {
+      socket.destroy()
+      await target.close()
+    }
+  })
+
+  it('caps how many reads run at once, independently of the command window', async () => {
+    const started: number[] = []
+    const releases: Array<() => void> = []
+    const lun: BlockDevice = {
+      getSize: () => LUN_SIZE,
+      getBlockSize: () => BLOCK_SIZE,
+      read: async (offset, length) => {
+        started.push(offset / BLOCK_SIZE)
+        await new Promise<void>(resolve => releases.push(resolve))
+        return Buffer.alloc(length)
+      },
+      write: async () => {
+        throw new Error('not used by this test')
+      },
+      flush: async () => {},
+      close: async () => {},
+    }
+
+    const target = new IscsiTarget({ iqn: IQN, host: '127.0.0.1', port: 0, lun, readConcurrency: 2 })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+
+    const socket = connect(address.port, '127.0.0.1')
+    await once(socket, 'connect')
+    // Both IscsiTarget and IscsiInitiator disable Nagle internally; this raw
+    // test socket doesn't get that for free, and these tests send several
+    // commands back to back with no read in between — exactly the pattern
+    // Nagle + delayed ACK stalls (~40ms observed without this).
+    socket.setNoDelay(true)
+    try {
+      const initiator = new MiniInitiator(socket)
+      await initiator.login('Normal')
+
+      const itts = []
+      for (let lba = 0; lba < 4; lba++) {
+        itts.push(await initiator.scsiCommand(rwCdb(0x28, lba, 1), 'read', BLOCK_SIZE))
+      }
+
+      // Poll instead of a fixed number of ticks: the commands still have to
+      // cross a real (loopback) socket before the LUN sees them.
+      for (let attempt = 0; started.length < 2 && attempt < 100; attempt++) {
+        await new Promise(resolve => setImmediate(resolve))
+      }
+      assert.equal(started.length, 2, 'only readConcurrency reads should have started')
+
+      releases.shift()!()
+      for (let attempt = 0; started.length < 3 && attempt < 100; attempt++) {
+        await new Promise(resolve => setImmediate(resolve))
+      }
+      assert.equal(started.length, 3, 'releasing one slot should admit exactly one more')
+
+      // drain the rest: releasing a slot only lets the NEXT queued read start
+      // asynchronously (one microtask later), so keep releasing whatever's
+      // pending and yielding until all four have started
+      while (started.length < 4) {
+        while (releases.length > 0) {
+          releases.shift()!()
+        }
+        await new Promise(resolve => setImmediate(resolve))
+      }
+      while (releases.length > 0) {
+        releases.shift()!()
+      }
+
+      for (let i = 0; i < itts.length; i++) {
+        const pdu = await initiator.recv()
+        assert.ok(itts.includes(pdu.itt))
+      }
+
+      await initiator.logout()
+    } finally {
+      socket.destroy()
+      await target.close()
+    }
+  })
+})
+
+// Regression test: a failed lun.read() (backend hiccup, corrupt source block)
+// must fail only that command, not the whole connection — mirrors the write
+// path's existing per-command CHECK_CONDITION/MEDIUM_ERROR handling.
+describe('READ error isolation', () => {
+  it('fails only the bad read; the connection and subsequent reads stay healthy', async () => {
+    const lun: BlockDevice = {
+      getSize: () => LUN_SIZE,
+      getBlockSize: () => BLOCK_SIZE,
+      read: async offset => {
+        if (offset === 0) {
+          throw new Error('simulated backend failure')
+        }
+        return Buffer.alloc(BLOCK_SIZE, 0xcc)
+      },
+      write: async () => {
+        throw new Error('not used by this test')
+      },
+      flush: async () => {},
+      close: async () => {},
+    }
+
+    const target = new IscsiTarget({ iqn: IQN, host: '127.0.0.1', port: 0, lun })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+
+    const socket = connect(address.port, '127.0.0.1')
+    await once(socket, 'connect')
+    try {
+      const initiator = new MiniInitiator(socket)
+      await initiator.login('Normal')
+
+      // LBA 0 is the bad one: must fail with CHECK CONDITION, not drop the connection
+      const failed = await initiator.read(rwCdb(0x28, 0, 1), BLOCK_SIZE)
+      assert.equal(failed.status, ScsiStatus.CHECK_CONDITION)
+
+      // the connection must still be usable: a healthy read afterward succeeds normally
+      const healthy = await initiator.read(rwCdb(0x28, 1, 1), BLOCK_SIZE)
+      assert.equal(healthy.status, ScsiStatus.GOOD)
+      assert.deepEqual(healthy.data, Buffer.alloc(BLOCK_SIZE, 0xcc))
+
+      await initiator.logout()
+    } finally {
+      socket.destroy()
+      await target.close()
+    }
+  })
+})
+
+describe('connection replacement', () => {
+  it('a new connection replaces an existing one instead of being refused forever', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'vates-iscsi-'))
+    const backingPath = join(dir, 'lun.img')
+    await writeFile(backingPath, Buffer.alloc(0))
+    await truncate(backingPath, LUN_SIZE)
+
+    const target = new IscsiTarget({
+      iqn: IQN,
+      host: '127.0.0.1',
+      port: 0,
+      lun: new FileBlockDevice({ path: backingPath, blockSize: BLOCK_SIZE }),
+    })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+
+    try {
+      // First connection: logs in, then goes idle — standing in for an
+      // initiator that gave up on it (its own command timeout, against a slow
+      // backend) without ever actually closing the socket.
+      const socketA = connect(address.port, '127.0.0.1')
+      await once(socketA, 'connect')
+      const initiatorA = new MiniInitiator(socketA)
+      await initiatorA.login('Normal')
+      const closedA = once(socketA, 'close')
+
+      // A second connection must be accepted, not refused, even though the
+      // first is still technically open from the target's point of view.
+      const socketB = connect(address.port, '127.0.0.1')
+      await once(socketB, 'connect')
+      const initiatorB = new MiniInitiator(socketB)
+      await initiatorB.login('Normal')
+
+      // The target must have torn the first connection's socket down.
+      await closedA
+
+      // The new connection is fully usable, not left in some half-adopted state.
+      const result = await initiatorB.read(rwCdb(0x28, 0, 1), BLOCK_SIZE)
+      assert.equal(result.status, ScsiStatus.GOOD)
+      await initiatorB.logout()
+      socketB.destroy()
+    } finally {
+      await target.close()
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+// One loopback that exercises BOTH one-way CHAP roles at once: our target is the
+// authenticator (challenges + verifies) and our initiator is the responder
+// (answers the challenge). This is the same code path each production role uses
+// (target vs XCP-ng open-iscsi; initiator vs a Pure array).
+describe('iSCSI CHAP loopback (target authenticator + initiator responder)', () => {
+  const CHAP = { user: 'alice', secret: 's3cr3t' }
+  const pattern = (i: number) => (i * 13 + 7) & 0xff
+
+  let dir: string
+  let backingPath: string
+  let target: IscsiTarget
+  let port: number
+
+  before(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'vates-iscsi-chap-'))
+    backingPath = join(dir, 'lun.img')
+    // Pre-fill the LUN with a recognizable pattern so a plain read can verify it.
+    const image = Buffer.alloc(LUN_SIZE)
+    for (let i = 0; i < image.length; i++) {
+      image[i] = pattern(i)
+    }
+    await writeFile(backingPath, image)
+
+    target = new IscsiTarget({
+      iqn: IQN,
+      host: '127.0.0.1',
+      port: 0,
+      lun: new FileBlockDevice({ path: backingPath, blockSize: BLOCK_SIZE }),
+      chap: CHAP,
+    })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+    port = address.port
+  })
+
+  after(async () => {
+    await target?.close()
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('authenticates a correct secret and reads the LUN', async () => {
+    const initiator = new IscsiInitiator({ host: '127.0.0.1', port, targetIqn: IQN, chap: CHAP })
+    await initiator.connect()
+    try {
+      assert.equal(initiator.getSize(), LUN_SIZE)
+      const offset = 5 * BLOCK_SIZE
+      const length = 3 * BLOCK_SIZE
+      const data = await initiator.read(offset, length)
+      const expected = Buffer.alloc(length)
+      for (let i = 0; i < length; i++) {
+        expected[i] = pattern(offset + i)
+      }
+      assert.deepEqual(data, expected)
+    } finally {
+      await initiator.close()
+    }
+  })
+
+  it('exposes the authenticated LUN as a RandomAccessDisk', async () => {
+    const blockSize = 64 * 1024
+    const disk = new IscsiDisk({ host: '127.0.0.1', port, targetIqn: IQN, chap: CHAP }, { blockSize })
+    await disk.init()
+    try {
+      assert.equal(disk.getVirtualSize(), LUN_SIZE)
+      assert.equal(disk.getBlockIndexes().length, LUN_SIZE / blockSize)
+      assert.equal(disk.hasBlock(0), true)
+      const { index, data } = await disk.readBlock(2)
+      assert.equal(index, 2)
+      assert.equal(data.length, blockSize)
+      const expected = Buffer.alloc(blockSize)
+      for (let i = 0; i < blockSize; i++) {
+        expected[i] = pattern(2 * blockSize + i)
+      }
+      assert.deepEqual(data, expected)
+    } finally {
+      await disk.close()
+    }
+  })
+
+  it('rejects a wrong secret', async () => {
+    const initiator = new IscsiInitiator({
+      host: '127.0.0.1',
+      port,
+      targetIqn: IQN,
+      chap: { user: 'alice', secret: 'wrong' },
+    })
+    await assert.rejects(initiator.connect(), /login rejected/)
+  })
+
+  it('rejects an initiator that offers no credentials', async () => {
+    const initiator = new IscsiInitiator({ host: '127.0.0.1', port, targetIqn: IQN })
+    await assert.rejects(initiator.connect(), /login rejected/)
+  })
+})
+
+// --- serving a RandomAccessDisk as a LUN ------------------------------------
+//
+// The shape used to expose a backup's disk chain: a sparse source disk with big
+// blocks, read through the protocol at 512-byte granularity.
+
+describe('DiskBlockDevice loopback', () => {
+  const DISK_BLOCK_SIZE = 64 * 1024
+  const BLOCK_COUNT = 4
+  const DISK_SIZE = BLOCK_COUNT * DISK_BLOCK_SIZE
+  const bytePattern = (i: number) => (i * 31 + 11) & 0xff
+
+  // only blocks 0 and 2 are allocated, like a differencing VHD chain
+  const allocated = new Map<number, Buffer>()
+  for (const index of [0, 2]) {
+    const data = Buffer.alloc(DISK_BLOCK_SIZE)
+    for (let i = 0; i < data.length; i++) {
+      data[i] = bytePattern(index * DISK_BLOCK_SIZE + i)
+    }
+    allocated.set(index, data)
+  }
+
+  const expectedAt = (offset: number, length: number): Buffer => {
+    const expected = Buffer.alloc(length)
+    for (let i = 0; i < length; i++) {
+      const absolute = offset + i
+      if (allocated.has(Math.floor(absolute / DISK_BLOCK_SIZE))) {
+        expected[i] = bytePattern(absolute)
+      }
+    }
+    return expected
+  }
+
+  class SparseDisk extends RandomAccessDisk {
+    getBlockSize(): number {
+      return DISK_BLOCK_SIZE
+    }
+    getVirtualSize(): number {
+      return DISK_SIZE
+    }
+    isDifferencing(): boolean {
+      return false
+    }
+    getBlockIndexes(): Array<number> {
+      return [...allocated.keys()]
+    }
+    hasBlock(index: number): boolean {
+      return allocated.has(index)
+    }
+    async init(): Promise<void> {}
+    async close(): Promise<void> {}
+    async readBlock(index: number): Promise<DiskBlock> {
+      const data = allocated.get(index)
+      if (data === undefined) {
+        // what RemoteVhdDiskChain does, and what the adapter must never trigger
+        throw new Error(`Block ${index} not found in chain`)
+      }
+      return { index, data }
+    }
+  }
+
+  let target: IscsiTarget
+  let port: number
+
+  before(async () => {
+    target = new IscsiTarget({
+      iqn: IQN,
+      host: '127.0.0.1',
+      port: 0,
+      lun: new DiskBlockDevice({ disk: new SparseDisk(), blockSize: BLOCK_SIZE }),
+    })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+    port = address.port
+  })
+
+  after(async () => {
+    await target?.close()
+  })
+
+  it('serves the disk content, unallocated blocks reading as zeroes', async () => {
+    const initiator = new IscsiInitiator({ host: '127.0.0.1', port, targetIqn: IQN })
+    await initiator.connect()
+    try {
+      assert.equal(initiator.getSize(), DISK_SIZE)
+
+      // one sector inside an allocated block
+      const offset = DISK_BLOCK_SIZE * 2 + 3 * BLOCK_SIZE
+      assert.deepEqual(await initiator.read(offset, BLOCK_SIZE), expectedAt(offset, BLOCK_SIZE))
+
+      // a whole unallocated block
+      assert.deepEqual(await initiator.read(DISK_BLOCK_SIZE, DISK_BLOCK_SIZE), Buffer.alloc(DISK_BLOCK_SIZE))
+
+      // a range straddling allocated and unallocated blocks
+      const straddle = DISK_BLOCK_SIZE - BLOCK_SIZE
+      const length = DISK_BLOCK_SIZE + 2 * BLOCK_SIZE
+      assert.deepEqual(await initiator.read(straddle, length), expectedAt(straddle, length))
+
+      // the whole disk, in one go
+      assert.deepEqual(await initiator.read(0, DISK_SIZE), expectedAt(0, DISK_SIZE))
+    } finally {
+      await initiator.close()
+    }
+  })
+
+  it('fails a write instead of corrupting the source', async () => {
+    const socket = connect({ host: '127.0.0.1', port })
+    await once(socket, 'connect')
+    const initiator = new MiniInitiator(socket)
+    try {
+      await initiator.login('Normal')
+      const status = await initiator.write(rwCdb(0x2a, 0, 1), Buffer.alloc(BLOCK_SIZE, 0xff))
+      assert.equal(status, ScsiStatus.CHECK_CONDITION)
+      // the source is untouched
+      const readBack = await initiator.read(rwCdb(0x28, 0, 1), BLOCK_SIZE)
+      assert.equal(readBack.status, ScsiStatus.GOOD)
+      assert.deepEqual(readBack.data, expectedAt(0, BLOCK_SIZE))
+    } finally {
+      socket.destroy()
+    }
+  })
+
+  // --- the same source, but cached into a local store ----------------------
+  //
+  // The shape used for a backup mount with a cache VDI: reads materialize into
+  // the local store, and writes are accepted there.
+
+  describe('cached into a local store', () => {
+    let cache: FileBlockDevice
+    let cachedDir: string
+    let cachedPath: string
+    let cachedTarget: IscsiTarget
+    let cachedPort: number
+
+    before(async () => {
+      cachedDir = await mkdtemp(join(tmpdir(), 'vates-iscsi-cache-'))
+      cachedPath = join(cachedDir, 'cache.img')
+      await writeFile(cachedPath, '')
+      await truncate(cachedPath, DISK_SIZE)
+      cache = new FileBlockDevice({ path: cachedPath, blockSize: BLOCK_SIZE })
+      // the cache is opened by its owner, not by the LUN
+      await cache.open()
+
+      cachedTarget = new IscsiTarget({
+        iqn: IQN,
+        host: '127.0.0.1',
+        port: 0,
+        lun: new CachedDiskBlockDevice({ disk: new SparseDisk(), cache, blockSize: BLOCK_SIZE }),
+      })
+      await cachedTarget.listen()
+      const address = cachedTarget.address()
+      assert.ok(address !== undefined)
+      cachedPort = address.port
+    })
+
+    after(async () => {
+      await cachedTarget?.close()
+      await rm(cachedDir, { recursive: true, force: true })
+    })
+
+    it('serves the source and materializes it into the local store', async () => {
+      const initiator = new IscsiInitiator({ host: '127.0.0.1', port: cachedPort, targetIqn: IQN })
+      await initiator.connect()
+      try {
+        assert.deepEqual(await initiator.read(0, BLOCK_SIZE), expectedAt(0, BLOCK_SIZE))
+        // the whole source block landed in the store, not just the sector read
+        const onDisk = await readFile(cachedPath)
+        assert.deepEqual(onDisk.subarray(0, DISK_BLOCK_SIZE), expectedAt(0, DISK_BLOCK_SIZE))
+      } finally {
+        await initiator.close()
+      }
+    })
+
+    it('accepts a write and reads it back', async () => {
+      const socket = connect({ host: '127.0.0.1', port: cachedPort })
+      await once(socket, 'connect')
+      const initiator = new MiniInitiator(socket)
+      try {
+        await initiator.login('Normal')
+        const payload = Buffer.alloc(BLOCK_SIZE, 0xee)
+        // block 1 is a hole in the source: nothing to fetch, the write stands alone
+        const lba = DISK_BLOCK_SIZE / BLOCK_SIZE
+        assert.equal(await initiator.write(rwCdb(0x2a, lba, 1), payload), ScsiStatus.GOOD)
+
+        const readBack = await initiator.read(rwCdb(0x28, lba, 1), BLOCK_SIZE)
+        assert.equal(readBack.status, ScsiStatus.GOOD)
+        assert.deepEqual(readBack.data, payload)
+      } finally {
+        socket.destroy()
+      }
+    })
+  })
+})

@vates/iscsi/src/pdu.mts

@@ -0,0 +1,167 @@
+import type { Socket } from 'node:net'
+import type { Readable } from 'node:stream'
+import { readChunk, readChunkStrict } from '@vates/read-chunk'
+import { pTimeout } from 'promise-toolbox'
+import { createLogger, type Logger } from '@xen-orchestra/log'
+
+import { BHS_LENGTH, opcodeName, OPCODE_IMMEDIATE, OPCODE_MASK, FLAG_FINAL } from './constants.mjs'
+
+const EMPTY = Buffer.alloc(0)
+
+// Framing-level wire trace, shared by target and initiator. Enable with the
+// `vates:iscsi:pdu` debug namespace to see every PDU that crosses the socket —
+// the first thing to look at when a new initiator/target combination misbehaves.
+const log: Logger = createLogger('vates:iscsi:pdu')
+
+/** Round `n` up to the next multiple of 4 (iSCSI segments are 4-byte padded). */
+export function roundUp4(n: number): number {
+  return (n + 3) & ~3
+}
+
+/**
+ * A fully-received inbound PDU: the 48-byte Basic Header Segment, any Additional
+ * Header Segment, and the (unpadded) data segment. Field accessors read the BHS
+ * at the offsets defined by RFC 7143; callers pick the ones relevant to the
+ * opcode they are handling.
+ */
+export class IncomingPdu {
+  constructor(
+    readonly bhs: Buffer,
+    readonly ahs: Buffer,
+    readonly data: Buffer
+  ) {}
+
+  /** 6-bit opcode (immediate bit masked off). */
+  get opcode(): number {
+    return this.bhs[0] & OPCODE_MASK
+  }
+
+  /** Whether the immediate bit is set (initiator requests immediate processing). */
+  get immediate(): boolean {
+    return (this.bhs[0] & OPCODE_IMMEDIATE) !== 0
+  }
+
+  /** Raw opcode-specific flags byte (byte 1). */
+  get flags(): number {
+    return this.bhs[1]
+  }
+
+  get finalBit(): boolean {
+    return (this.bhs[1] & FLAG_FINAL) !== 0
+  }
+
+  readU8(offset: number): number {
+    return this.bhs.readUInt8(offset)
+  }
+
+  readU16(offset: number): number {
+    return this.bhs.readUInt16BE(offset)
+  }
+
+  readU32(offset: number): number {
+    return this.bhs.readUInt32BE(offset)
+  }
+
+  /** Initiator Task Tag (bytes 16-19), present in every initiator PDU we handle. */
+  get itt(): number {
+    return this.bhs.readUInt32BE(16)
+  }
+
+  /** CmdSN (bytes 24-27) — meaningful on command-carrying PDUs. */
+  get cmdSN(): number {
+    return this.bhs.readUInt32BE(24)
+  }
+
+  /** ExpStatSN (bytes 28-31). */
+  get expStatSN(): number {
+    return this.bhs.readUInt32BE(28)
+  }
+}
+
+/**
+ * Read exactly one PDU from `stream`, reassembling across TCP boundaries.
+ * Resolves to `null` on a clean EOF between PDUs; throws on a truncated PDU
+ * or read error. No header/data digest bytes: digests are pinned off.
+ *
+ * No per-read timeout, intentionally — a target may sit idle between commands
+ * indefinitely. Liveness is a transport concern (socket timeout / NOP
+ * keepalives), handled elsewhere.
+ */
+export async function readPdu(stream: Readable): Promise<IncomingPdu | null> {
+  const bhs = await readChunk(stream, BHS_LENGTH)
+  if (bhs === null) {
+    return null // clean EOF between PDUs
+  }
+  if (bhs.length !== BHS_LENGTH) {
+    throw new Error(`truncated iSCSI BHS (got ${bhs.length} of ${BHS_LENGTH} bytes)`)
+  }
+
+  const totalAhsLength = bhs.readUInt8(4)
+  const dataSegmentLength = bhs.readUIntBE(5, 3)
+  const ahsBytes = totalAhsLength * 4
+  const dataBytesPadded = roundUp4(dataSegmentLength)
+
+  let ahs = EMPTY
+  let data = EMPTY
+  if (ahsBytes + dataBytesPadded > 0) {
+    const rest = await readChunkStrict(stream, ahsBytes + dataBytesPadded)
+    if (ahsBytes > 0) {
+      ahs = rest.subarray(0, ahsBytes)
+    }
+    data = rest.subarray(ahsBytes, ahsBytes + dataSegmentLength) // strip 4-byte padding
+  }
+
+  const pdu = new IncomingPdu(bhs, ahs, data)
+  log.debug('rx', {
+    opcode: opcodeName(bhs[0]),
+    itt: pdu.itt,
+    flags: `0x${bhs[1].toString(16).padStart(2, '0')}`,
+    ahs: ahsBytes,
+    data: dataSegmentLength,
+  })
+  return pdu
+}
+
+/** Allocate a zeroed 48-byte BHS with byte 0 set to `opcode`. */
+export function allocBhs(opcode: number): Buffer {
+  const bhs = Buffer.alloc(BHS_LENGTH)
+  bhs[0] = opcode
+  return bhs
+}
+
+/** Write the 24-bit DataSegmentLength field (bytes 5-7) of a BHS. */
+export function setDataSegmentLength(bhs: Buffer, length: number): void {
+  bhs.writeUIntBE(length, 5, 3)
+}
+
+/**
+ * Assemble a complete PDU buffer from a 48-byte BHS and an optional data
+ * segment, setting DataSegmentLength and applying 4-byte padding.
+ */
+export function assemblePdu(bhs: Buffer, data?: Buffer): Buffer {
+  const length = data?.length ?? 0
+  setDataSegmentLength(bhs, length)
+  if (length === 0) {
+    return bhs
+  }
+  const padding = roundUp4(length) - length
+  return padding === 0 ? Buffer.concat([bhs, data!]) : Buffer.concat([bhs, data!, Buffer.alloc(padding)])
+}
+
+/**
+ * Write a PDU to the socket, resolving once the kernel has accepted it (honoring
+ * back-pressure via the write callback). Rejects if the write errors or does not
+ * drain within `timeoutMs` (0 disables the timeout).
+ */
+export function writePdu(socket: Socket, buffer: Buffer, timeoutMs: number): Promise<void> {
+  log.debug('tx', {
+    opcode: opcodeName(buffer[0]),
+    itt: buffer.readUInt32BE(16),
+    flags: `0x${buffer[1].toString(16).padStart(2, '0')}`,
+    length: buffer.length,
+  })
+  const promise = new Promise<void>((resolve, reject) => {
+    socket.write(buffer, error => (error ? reject(error) : resolve()))
+  })
+  return timeoutMs > 0 ? pTimeout.call(promise, timeoutMs) : promise
+}

@vates/iscsi/src/pdu.test.mts

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict'
+import { PassThrough } from 'node:stream'
+import { describe, it } from 'node:test'
+
+import { InitiatorOpcode } from './constants.mjs'
+import { allocBhs, assemblePdu, IncomingPdu, readPdu, roundUp4 } from './pdu.mjs'
+
+function buildScsiCommandPdu(itt: number, cmdSN: number, cdb: Buffer, data?: Buffer): Buffer {
+  const bhs = allocBhs(InitiatorOpcode.SCSI_COMMAND)
+  bhs[1] = 0x80 // Final
+  bhs.writeUInt32BE(itt, 16)
+  bhs.writeUInt32BE(0, 20) // EDTL
+  bhs.writeUInt32BE(cmdSN, 24)
+  cdb.copy(bhs, 32)
+  return assemblePdu(bhs, data)
+}
+
+async function readOne(buffer: Buffer): Promise<IncomingPdu> {
+  const stream = new PassThrough()
+  stream.end(buffer)
+  const pdu = await readPdu(stream)
+  assert.ok(pdu !== null)
+  return pdu
+}
+
+describe('roundUp4', () => {
+  it('rounds up to the next multiple of 4', () => {
+    assert.equal(roundUp4(0), 0)
+    assert.equal(roundUp4(1), 4)
+    assert.equal(roundUp4(4), 4)
+    assert.equal(roundUp4(5), 8)
+    assert.equal(roundUp4(15), 16)
+  })
+})
+
+describe('assemblePdu / readPdu round-trip', () => {
+  it('preserves opcode and header fields', async () => {
+    const cdb = Buffer.alloc(16)
+    cdb[0] = 0x28 // READ(10)
+    const pdu = await readOne(buildScsiCommandPdu(0xdeadbeef, 42, cdb))
+    assert.equal(pdu.opcode, InitiatorOpcode.SCSI_COMMAND)
+    assert.equal(pdu.immediate, false)
+    assert.equal(pdu.finalBit, true)
+    assert.equal(pdu.itt, 0xdeadbeef)
+    assert.equal(pdu.cmdSN, 42)
+    assert.equal(pdu.bhs.subarray(32, 48)[0], 0x28)
+  })
+
+  it('carries a data segment and strips its 4-byte padding', async () => {
+    const data = Buffer.from([1, 2, 3, 4, 5]) // 5 bytes -> padded to 8 on the wire
+    const wire = buildScsiCommandPdu(1, 1, Buffer.alloc(16), data)
+    assert.equal(wire.length, 48 + 8, 'data segment is padded to a 4-byte boundary')
+    const pdu = await readOne(wire)
+    assert.deepEqual(pdu.data, data, 'padding is stripped from the parsed data')
+  })
+})
+
+describe('readPdu framing', () => {
+  it('reassembles a PDU split across multiple TCP chunks', async () => {
+    const data = Buffer.from('hello world!!') // 13 bytes -> padded to 16
+    const wire = buildScsiCommandPdu(7, 7, Buffer.alloc(16), data)
+    const stream = new PassThrough()
+    const pduPromise = readPdu(stream)
+    // Feed the bytes in awkward fragments.
+    stream.write(wire.subarray(0, 10))
+    stream.write(wire.subarray(10, 48))
+    stream.write(wire.subarray(48, 55))
+    stream.end(wire.subarray(55))
+    const pdu = await pduPromise
+    assert.ok(pdu !== null)
+    assert.equal(pdu.itt, 7)
+    assert.deepEqual(pdu.data, data)
+  })
+
+  it('reads two PDUs coalesced into one chunk', async () => {
+    const first = buildScsiCommandPdu(1, 1, Buffer.alloc(16), Buffer.from([0xaa]))
+    const second = buildScsiCommandPdu(2, 2, Buffer.alloc(16), Buffer.from([0xbb, 0xcc]))
+    const stream = new PassThrough()
+    stream.end(Buffer.concat([first, second]))
+
+    const a = await readPdu(stream)
+    const b = await readPdu(stream)
+    assert.equal(a?.itt, 1)
+    assert.deepEqual(a?.data, Buffer.from([0xaa]))
+    assert.equal(b?.itt, 2)
+    assert.deepEqual(b?.data, Buffer.from([0xbb, 0xcc]))
+  })
+
+  it('returns null on a clean end-of-stream', async () => {
+    const stream = new PassThrough()
+    stream.end()
+    assert.equal(await readPdu(stream), null)
+  })
+
+  it('throws on a truncated BHS', async () => {
+    const stream = new PassThrough()
+    stream.end(Buffer.alloc(20)) // fewer than 48 bytes, then EOF
+    await assert.rejects(readPdu(stream), /truncated/)
+  })
+})

@vates/iscsi/src/scsi.mts

@@ -0,0 +1,255 @@
+import { createLogger, type Logger } from '@xen-orchestra/log'
+
+import { Asc, ScsiStatus, SenseKey } from './constants.mjs'
+import { decodeCdb, type CommandContext, type SenseInfo } from './types.mjs'
+
+// SCSI command trace. Enable `vates:iscsi:scsi` to see every decoded CDB the
+// target services — useful when an initiator issues a command we mishandle.
+const log: Logger = createLogger('vates:iscsi:scsi')
+
+/** SCSI INQUIRY identity strings advertised by the LUN. */
+export interface ScsiIdentity {
+  /** T10 vendor identification (≤ 8 ASCII chars). */
+  vendor: string
+  /** Product identification (≤ 16 ASCII chars). */
+  product: string
+  /** Product revision level (≤ 4 ASCII chars). */
+  revision: string
+  /** Unit serial number; also seeds the VPD 0x83 device identifier. */
+  serial: string
+}
+
+// --- low-level encoders -----------------------------------------------------
+
+function writeAscii(buffer: Buffer, offset: number, length: number, value: string): void {
+  buffer.fill(0x20, offset, offset + length) // space pad
+  buffer.write(value.slice(0, length), offset, 'ascii')
+}
+
+/** Standard INQUIRY data (36 bytes) for a direct-access block device. */
+export function buildStandardInquiry(identity: ScsiIdentity): Buffer {
+  const buffer = Buffer.alloc(36)
+  buffer[0] = 0x00 // peripheral qualifier 0, device type 0x00 (direct-access block device)
+  buffer[1] = 0x00 // not removable
+  buffer[2] = 0x05 // version: SPC-3
+  buffer[3] = 0x02 // response data format 2
+  buffer[4] = 31 // additional length (total 36 - 5)
+  writeAscii(buffer, 8, 8, identity.vendor)
+  writeAscii(buffer, 16, 16, identity.product)
+  writeAscii(buffer, 32, 4, identity.revision)
+  return buffer
+}
+
+const SUPPORTED_VPD_PAGES = [0x00, 0x80, 0x83]
+
+/**
+ * Build an INQUIRY EVPD page, or `undefined` for an unsupported page code (the
+ * caller then returns CHECK CONDITION / INVALID FIELD IN CDB).
+ */
+export function buildVpd(pageCode: number, identity: ScsiIdentity): Buffer | undefined {
+  switch (pageCode) {
+    case 0x00: {
+      // Supported VPD pages.
+      const buffer = Buffer.alloc(4 + SUPPORTED_VPD_PAGES.length)
+      buffer[1] = 0x00
+      buffer.writeUInt16BE(SUPPORTED_VPD_PAGES.length, 2)
+      SUPPORTED_VPD_PAGES.forEach((page, i) => {
+        buffer[4 + i] = page
+      })
+      return buffer
+    }
+    case 0x80: {
+      // Unit serial number.
+      const serial = Buffer.from(identity.serial, 'ascii')
+      const buffer = Buffer.alloc(4 + serial.length)
+      buffer[1] = 0x80
+      buffer.writeUInt16BE(serial.length, 2)
+      serial.copy(buffer, 4)
+      return buffer
+    }
+    case 0x83: {
+      // Device identification: one T10-vendor-ID-based designator (ASCII).
+      const designator = Buffer.alloc(8 + identity.serial.length)
+      writeAscii(designator, 0, 8, identity.vendor)
+      designator.write(identity.serial, 8, 'ascii')
+      const descriptor = Buffer.alloc(4 + designator.length)
+      descriptor[0] = 0x02 // code set: ASCII
+      descriptor[1] = 0x01 // association: logical unit, designator type: T10 vendor ID based
+      descriptor[3] = designator.length
+      designator.copy(descriptor, 4)
+      const buffer = Buffer.alloc(4 + descriptor.length)
+      buffer[1] = 0x83
+      buffer.writeUInt16BE(descriptor.length, 2)
+      descriptor.copy(buffer, 4)
+      return buffer
+    }
+    default:
+      return undefined
+  }
+}
+
+/** READ CAPACITY(10) parameter data (8 bytes). */
+export function buildReadCapacity10(blockCount: number, blockSize: number): Buffer {
+  const buffer = Buffer.alloc(8)
+  const maxLba = blockCount - 1
+  // If the capacity overflows 32 bits, return 0xffffffff to force the initiator
+  // to issue READ CAPACITY(16).
+  buffer.writeUInt32BE(maxLba > 0xffffffff ? 0xffffffff : maxLba, 0)
+  buffer.writeUInt32BE(blockSize, 4)
+  return buffer
+}
+
+/** READ CAPACITY(16) parameter data (32 bytes). */
+export function buildReadCapacity16(blockCount: number, blockSize: number): Buffer {
+  const buffer = Buffer.alloc(32)
+  buffer.writeBigUInt64BE(BigInt(blockCount - 1), 0)
+  buffer.writeUInt32BE(blockSize, 8)
+  return buffer
+}
+
+/** REPORT LUNS parameter data advertising a single LUN 0 (16 bytes). */
+export function buildReportLuns(): Buffer {
+  const buffer = Buffer.alloc(16)
+  buffer.writeUInt32BE(8, 0) // LUN list length: one 8-byte LUN entry
+  return buffer // bytes 8-15 are LUN 0 (all zero)
+}
+
+/** Fixed-format sense data (18 bytes). */
+export function buildFixedSense({ key, asc, ascq }: SenseInfo): Buffer {
+  const buffer = Buffer.alloc(18)
+  buffer[0] = 0x70 // response code: current error, fixed format
+  buffer[2] = key
+  buffer[7] = 10 // additional sense length (18 - 8)
+  buffer[12] = asc
+  buffer[13] = ascq
+  return buffer
+}
+
+/** Minimal MODE SENSE parameter data: a header with no block descriptor or pages. */
+export function buildModeSense(long: boolean): Buffer {
+  if (long) {
+    const buffer = Buffer.alloc(8)
+    buffer.writeUInt16BE(6, 0) // mode data length (8 - 2)
+    return buffer
+  }
+  const buffer = Buffer.alloc(4)
+  buffer[0] = 3 // mode data length (4 - 1)
+  return buffer
+}
+
+const ILLEGAL_REQUEST_INVALID_OPCODE: SenseInfo = {
+  key: SenseKey.ILLEGAL_REQUEST,
+  ...Asc.INVALID_COMMAND_OPERATION_CODE,
+}
+const ILLEGAL_REQUEST_INVALID_FIELD: SenseInfo = {
+  key: SenseKey.ILLEGAL_REQUEST,
+  ...Asc.INVALID_FIELD_IN_CDB,
+}
+const ILLEGAL_REQUEST_LBA_OUT_OF_RANGE: SenseInfo = {
+  key: SenseKey.ILLEGAL_REQUEST,
+  ...Asc.LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE,
+}
+const MEDIUM_ERROR_NO_ADDITIONAL_SENSE: SenseInfo = { key: SenseKey.MEDIUM_ERROR, ...Asc.NO_ADDITIONAL_SENSE }
+
+function checkCondition(ctx: CommandContext, itt: number, sense: SenseInfo): Promise<void> {
+  return ctx.sendScsiResponse(itt, ScsiStatus.CHECK_CONDITION, { sense: buildFixedSense(sense) })
+}
+
+/**
+ * Decode and execute one SCSI Command, driving completion through `ctx`.
+ *
+ * `cdb` is the 16-byte CDB from the SCSI Command PDU and `itt` its Initiator
+ * Task Tag. Read commands stream Data-In; WRITE solicits Data-Out via R2T;
+ * everything else returns status (with sense on error).
+ */
+export async function handleScsiCommand(
+  cdb: Buffer,
+  itt: number,
+  ctx: CommandContext,
+  identity: ScsiIdentity
+): Promise<void> {
+  const { lun } = ctx
+  const blockSize = lun.getBlockSize()
+  const blockCount = lun.getSize() / blockSize
+  const request = decodeCdb(cdb)
+  log.debug('scsi command', { itt, ...request })
+
+  switch (request.kind) {
+    case 'inquiry': {
+      if (!request.evpd) {
+        if (request.pageCode !== 0) {
+          // EVPD clear but a page code was given: invalid per SPC.
+          return checkCondition(ctx, itt, ILLEGAL_REQUEST_INVALID_FIELD)
+        }
+        return ctx.sendReadData(itt, buildStandardInquiry(identity), request.allocationLength)
+      }
+      const page = buildVpd(request.pageCode, identity)
+      if (page === undefined) {
+        return checkCondition(ctx, itt, ILLEGAL_REQUEST_INVALID_FIELD)
+      }
+      return ctx.sendReadData(itt, page, request.allocationLength)
+    }
+
+    case 'reportLuns':
+      return ctx.sendReadData(itt, buildReportLuns(), request.allocationLength)
+
+    case 'readCapacity10':
+      return ctx.sendReadData(itt, buildReadCapacity10(blockCount, blockSize), 8)
+
+    case 'readCapacity16':
+      return ctx.sendReadData(itt, buildReadCapacity16(blockCount, blockSize), request.allocationLength)
+
+    case 'read': {
+      if (request.lba + request.blocks > blockCount) {
+        return checkCondition(ctx, itt, ILLEGAL_REQUEST_LBA_OUT_OF_RANGE)
+      }
+      const byteLength = request.blocks * blockSize
+      if (byteLength === 0) {
+        return ctx.sendReadData(itt, Buffer.alloc(0), 0)
+      }
+      let data: Buffer
+      try {
+        data = await lun.read(request.lba * blockSize, byteLength)
+      } catch (error) {
+        // A single bad block (backend hiccup, corrupt source) must fail only
+        // this command, not the whole connection — mirrors how a failed
+        // lun.write() is handled in connection.mts's #handleDataOut.
+        log.warn('LUN read failed', error instanceof Error ? error : new Error(String(error)))
+        return checkCondition(ctx, itt, MEDIUM_ERROR_NO_ADDITIONAL_SENSE)
+      }
+      return ctx.sendReadData(itt, data, byteLength)
+    }
+
+    case 'write': {
+      if (request.lba + request.blocks > blockCount) {
+        return checkCondition(ctx, itt, ILLEGAL_REQUEST_LBA_OUT_OF_RANGE)
+      }
+      const byteLength = request.blocks * blockSize
+      if (byteLength === 0) {
+        return ctx.sendScsiResponse(itt, ScsiStatus.GOOD)
+      }
+      // Hand off to the connection: it solicits the data via R2T and sends the
+      // SCSI Response once the (possibly interleaved) Data-Out PDUs complete.
+      return ctx.beginWrite(itt, request.lba * blockSize, byteLength)
+    }
+
+    case 'testUnitReady':
+      return ctx.sendScsiResponse(itt, ScsiStatus.GOOD)
+
+    case 'requestSense': {
+      // No deferred error model in v1: always report NO SENSE.
+      const sense = buildFixedSense({ key: SenseKey.NO_SENSE, ...Asc.NO_ADDITIONAL_SENSE })
+      return ctx.sendReadData(itt, sense, request.allocationLength)
+    }
+
+    case 'modeSense':
+      return ctx.sendReadData(itt, buildModeSense(request.long), request.allocationLength)
+
+    case 'syncCache':
+      await lun.flush()
+      return ctx.sendScsiResponse(itt, ScsiStatus.GOOD)
+
+    case 'unsupported':
+      return checkCondition(ctx, itt, ILLEGAL_REQUEST_INVALID_OPCODE)
+  }
+}

@vates/iscsi/src/scsi.test.mts

@@ -0,0 +1,237 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import type { BlockDevice } from './backend.mjs'
+import { ScsiStatus, SenseKey } from './constants.mjs'
+import {
+  buildReadCapacity10,
+  buildReadCapacity16,
+  buildReportLuns,
+  buildStandardInquiry,
+  buildVpd,
+  handleScsiCommand,
+  type ScsiIdentity,
+} from './scsi.mjs'
+import { decodeCdb, type CommandContext, type ScsiResponseOptions } from './types.mjs'
+
+const IDENTITY: ScsiIdentity = { vendor: 'VATES', product: 'ISCSI LUN', revision: '0001', serial: 'unit-serial-1' }
+
+// --- a trivial in-memory LUN ------------------------------------------------
+
+class MemoryBlockDevice implements BlockDevice {
+  readonly #buffer: Buffer
+  readonly #blockSize: number
+
+  constructor(sizeBytes: number, blockSize = 512) {
+    this.#buffer = Buffer.alloc(sizeBytes)
+    this.#blockSize = blockSize
+  }
+
+  get buffer(): Buffer {
+    return this.#buffer
+  }
+
+  getSize(): number {
+    return this.#buffer.length
+  }
+  getBlockSize(): number {
+    return this.#blockSize
+  }
+  async read(offset: number, length: number): Promise<Buffer> {
+    return Buffer.from(this.#buffer.subarray(offset, offset + length))
+  }
+  async write(offset: number, data: Buffer): Promise<void> {
+    data.copy(this.#buffer, offset)
+  }
+  async flush(): Promise<void> {}
+  async close(): Promise<void> {}
+}
+
+class FakeContext implements CommandContext {
+  readonly reads: Array<{ data: Buffer; allocationLength: number }> = []
+  readonly responses: Array<{ status: number; options?: ScsiResponseOptions }> = []
+  readonly writes: Array<{ itt: number; lunOffset: number; totalLength: number }> = []
+
+  constructor(readonly lun: BlockDevice) {}
+
+  async sendReadData(_itt: number, data: Buffer, allocationLength: number): Promise<void> {
+    this.reads.push({ data, allocationLength })
+  }
+  async beginWrite(itt: number, lunOffset: number, totalLength: number): Promise<void> {
+    this.writes.push({ itt, lunOffset, totalLength })
+  }
+  async sendScsiResponse(_itt: number, status: number, options?: ScsiResponseOptions): Promise<void> {
+    this.responses.push({ status, options })
+  }
+}
+
+function cdb(...bytes: number[]): Buffer {
+  const buffer = Buffer.alloc(16)
+  Buffer.from(bytes).copy(buffer)
+  return buffer
+}
+
+describe('decodeCdb', () => {
+  it('decodes READ(10) LBA and transfer length', () => {
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x28
+    buffer.writeUInt32BE(0x01020304, 2)
+    buffer.writeUInt16BE(8, 7)
+    assert.deepEqual(decodeCdb(buffer), { kind: 'read', lba: 0x01020304, blocks: 8 })
+  })
+
+  it('decodes WRITE(16) LBA and transfer length', () => {
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x8a
+    buffer.writeBigUInt64BE(123456789n, 2)
+    buffer.writeUInt32BE(16, 10)
+    assert.deepEqual(decodeCdb(buffer), { kind: 'write', lba: 123456789, blocks: 16 })
+  })
+
+  it('decodes READ CAPACITY(16) only for the right service action', () => {
+    assert.equal(decodeCdb(cdb(0x9e, 0x10)).kind, 'readCapacity16')
+    assert.equal(decodeCdb(cdb(0x9e, 0x12)).kind, 'unsupported')
+  })
+
+  it('clamps an out-of-range 64-bit LBA instead of throwing', () => {
+    // Past 2^53 an LBA no longer fits a JS number — and is past any capacity we
+    // can serve, so it must come back as an unservable LBA the range check
+    // rejects, not as an error that would tear the connection down.
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x88
+    buffer.writeBigUInt64BE(0xffffffffffffffffn, 2)
+    buffer.writeUInt32BE(1, 10)
+    assert.deepEqual(decodeCdb(buffer), { kind: 'read', lba: Number.MAX_SAFE_INTEGER, blocks: 1 })
+  })
+
+  it('maps unknown opcodes to unsupported', () => {
+    assert.deepEqual(decodeCdb(cdb(0xff)), { kind: 'unsupported', opcode: 0xff })
+  })
+})
+
+describe('response encoders', () => {
+  it('builds 36-byte standard INQUIRY data for a block device', () => {
+    const data = buildStandardInquiry(IDENTITY)
+    assert.equal(data.length, 36)
+    assert.equal(data[0], 0x00) // direct-access block device
+    assert.equal(data[4], 31) // additional length
+    assert.equal(data.subarray(8, 16).toString('ascii').trim(), 'VATES')
+    assert.equal(data.subarray(16, 32).toString('ascii').trim(), 'ISCSI LUN')
+  })
+
+  it('builds READ CAPACITY(10) as (maxLba, blockSize)', () => {
+    const data = buildReadCapacity10(2048, 512)
+    assert.equal(data.readUInt32BE(0), 2047)
+    assert.equal(data.readUInt32BE(4), 512)
+  })
+
+  it('clamps READ CAPACITY(10) max LBA to force RC16 on large disks', () => {
+    const data = buildReadCapacity10(0x1_0000_0001, 512)
+    assert.equal(data.readUInt32BE(0), 0xffffffff)
+  })
+
+  it('builds READ CAPACITY(16) with a 64-bit max LBA', () => {
+    const data = buildReadCapacity16(0x1_0000_0001, 512)
+    assert.equal(data.readBigUInt64BE(0), 0x1_0000_0000n)
+    assert.equal(data.readUInt32BE(8), 512)
+  })
+
+  it('reports a single LUN 0', () => {
+    const data = buildReportLuns()
+    assert.equal(data.readUInt32BE(0), 8) // one 8-byte LUN entry
+    assert.deepEqual(data.subarray(8, 16), Buffer.alloc(8))
+  })
+
+  it('advertises supported VPD pages and rejects unknown ones', () => {
+    const page00 = buildVpd(0x00, IDENTITY)
+    assert.ok(page00 !== undefined)
+    assert.deepEqual([...page00.subarray(4)], [0x00, 0x80, 0x83])
+    assert.equal(buildVpd(0x55, IDENTITY), undefined)
+  })
+})
+
+describe('handleScsiCommand', () => {
+  it('INQUIRY returns standard data trimmed to the allocation length', async () => {
+    const ctx = new FakeContext(new MemoryBlockDevice(1024 * 1024))
+    await handleScsiCommand(cdb(0x12, 0x00, 0x00, 0x00, 36), 1, ctx, IDENTITY)
+    assert.equal(ctx.reads.length, 1)
+    assert.equal(ctx.reads[0].data.length, 36)
+    assert.equal(ctx.reads[0].allocationLength, 36)
+  })
+
+  it('READ(10) returns the backing bytes for the requested blocks', async () => {
+    const lun = new MemoryBlockDevice(4096)
+    lun.buffer.fill(0xab, 512, 1024) // block 1
+    const ctx = new FakeContext(lun)
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x28
+    buffer.writeUInt32BE(1, 2) // LBA 1
+    buffer.writeUInt16BE(1, 7) // 1 block
+    await handleScsiCommand(buffer, 1, ctx, IDENTITY)
+    assert.equal(ctx.reads.length, 1)
+    assert.deepEqual(ctx.reads[0].data, Buffer.alloc(512, 0xab))
+  })
+
+  it('WRITE(10) begins a solicited write at the right LUN offset and length', async () => {
+    const ctx = new FakeContext(new MemoryBlockDevice(4096))
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x2a
+    buffer.writeUInt32BE(2, 2) // LBA 2
+    buffer.writeUInt16BE(3, 7) // 3 blocks
+    await handleScsiCommand(buffer, 7, ctx, IDENTITY)
+    // The data transfer + GOOD response are completed later by the connection.
+    assert.deepEqual(ctx.writes, [{ itt: 7, lunOffset: 2 * 512, totalLength: 3 * 512 }])
+    assert.equal(ctx.responses.length, 0)
+  })
+
+  it('WRITE(10) of zero blocks returns GOOD immediately with no transfer', async () => {
+    const ctx = new FakeContext(new MemoryBlockDevice(4096))
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x2a // LBA 0, 0 blocks
+    await handleScsiCommand(buffer, 1, ctx, IDENTITY)
+    assert.equal(ctx.writes.length, 0)
+    assert.deepEqual(ctx.responses, [{ status: ScsiStatus.GOOD, options: undefined }])
+  })
+
+  it('rejects an out-of-range READ with CHECK CONDITION', async () => {
+    const ctx = new FakeContext(new MemoryBlockDevice(4096)) // 8 blocks
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x28
+    buffer.writeUInt32BE(7, 2) // LBA 7
+    buffer.writeUInt16BE(4, 7) // 4 blocks -> past end
+    await handleScsiCommand(buffer, 1, ctx, IDENTITY)
+    assert.equal(ctx.responses.length, 1)
+    assert.equal(ctx.responses[0].status, ScsiStatus.CHECK_CONDITION)
+    assert.equal(ctx.responses[0].options?.sense?.[2], SenseKey.ILLEGAL_REQUEST)
+  })
+
+  it('reports a failed lun.read() as CHECK CONDITION / MEDIUM ERROR, not an uncaught throw', async () => {
+    const lun: BlockDevice = {
+      getSize: () => 4096,
+      getBlockSize: () => 512,
+      read: async () => {
+        throw new Error('backend read failed')
+      },
+      write: async () => {},
+      flush: async () => {},
+      close: async () => {},
+    }
+    const ctx = new FakeContext(lun)
+    const buffer = Buffer.alloc(16)
+    buffer[0] = 0x28
+    buffer.writeUInt32BE(1, 2) // LBA 1
+    buffer.writeUInt16BE(1, 7) // 1 block
+    await handleScsiCommand(buffer, 1, ctx, IDENTITY)
+    assert.equal(ctx.responses.length, 1)
+    assert.equal(ctx.responses[0].status, ScsiStatus.CHECK_CONDITION)
+    assert.equal(ctx.responses[0].options?.sense?.[2], SenseKey.MEDIUM_ERROR)
+    assert.equal(ctx.reads.length, 0) // sendReadData was never reached
+  })
+
+  it('returns CHECK CONDITION for an unsupported opcode', async () => {
+    const ctx = new FakeContext(new MemoryBlockDevice(4096))
+    await handleScsiCommand(cdb(0xff), 1, ctx, IDENTITY)
+    assert.equal(ctx.responses[0].status, ScsiStatus.CHECK_CONDITION)
+    assert.equal(ctx.responses[0].options?.sense?.[12], 0x20) // INVALID COMMAND OPERATION CODE
+  })
+})

@vates/iscsi/src/semaphore.mts

@@ -0,0 +1,33 @@
+/**
+ * A minimal counting semaphore: bounds how many `run()`-wrapped tasks execute
+ * at once, queueing the rest in FIFO order until a slot frees up.
+ */
+export class Semaphore {
+  #available: number
+  readonly #waiters: Array<() => void> = []
+
+  constructor(concurrency: number) {
+    if (!Number.isInteger(concurrency) || concurrency <= 0) {
+      throw new Error(`concurrency must be a positive integer, got ${concurrency}`)
+    }
+    this.#available = concurrency
+  }
+
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.#available > 0) {
+      this.#available--
+    } else {
+      await new Promise<void>(resolve => this.#waiters.push(resolve))
+    }
+    try {
+      return await fn()
+    } finally {
+      const next = this.#waiters.shift()
+      if (next !== undefined) {
+        next()
+      } else {
+        this.#available++
+      }
+    }
+  }
+}

@vates/iscsi/src/semaphore.test.mts

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { Semaphore } from './semaphore.mjs'
+
+describe('Semaphore', () => {
+  it('rejects a non-positive-integer concurrency', () => {
+    assert.throws(() => new Semaphore(0), /positive integer/)
+    assert.throws(() => new Semaphore(-1), /positive integer/)
+    assert.throws(() => new Semaphore(1.5), /positive integer/)
+  })
+
+  it('runs tasks immediately while under the limit', async () => {
+    const semaphore = new Semaphore(2)
+    const started: Array<number> = []
+    await Promise.all(
+      [0, 1].map(i =>
+        semaphore.run(async () => {
+          started.push(i)
+        })
+      )
+    )
+    assert.deepEqual(started.sort(), [0, 1])
+  })
+
+  it('caps concurrency and admits the next task as soon as a slot frees', async () => {
+    const semaphore = new Semaphore(2)
+    let inFlight = 0
+    let maxInFlight = 0
+    const releases: Array<() => void> = []
+
+    const run = () =>
+      semaphore.run(async () => {
+        inFlight++
+        maxInFlight = Math.max(maxInFlight, inFlight)
+        await new Promise<void>(resolve => releases.push(resolve))
+        inFlight--
+      })
+
+    const tasks = [run(), run(), run(), run()]
+    // let the first batch (2, the concurrency limit) start
+    await new Promise(resolve => setImmediate(resolve))
+    assert.equal(inFlight, 2)
+    assert.equal(releases.length, 2)
+
+    while (releases.length > 0) {
+      releases.shift()!()
+      await new Promise(resolve => setImmediate(resolve))
+    }
+    await Promise.all(tasks)
+
+    assert.equal(maxInFlight, 2)
+  })
+
+  it('propagates a task failure without leaking its slot', async () => {
+    const semaphore = new Semaphore(1)
+    await assert.rejects(
+      semaphore.run(async () => {
+        throw new Error('boom')
+      }),
+      /boom/
+    )
+    // the slot must have been released despite the failure
+    let ran = false
+    await semaphore.run(async () => {
+      ran = true
+    })
+    assert.equal(ran, true)
+  })
+})

@vates/iscsi/src/sequencing.test.mts

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { addSerial, incrementSerial, SERIAL_MODULO } from './connection.mjs'
+
+describe('iSCSI serial-number arithmetic', () => {
+  it('increments within range', () => {
+    assert.equal(incrementSerial(0), 1)
+    assert.equal(incrementSerial(41), 42)
+  })
+
+  it('wraps at 2^32', () => {
+    assert.equal(SERIAL_MODULO, 0x1_0000_0000)
+    assert.equal(incrementSerial(0xffffffff), 0)
+    assert.equal(addSerial(0xfffffffe, 5), 3)
+    assert.equal(addSerial(0xffffffff, 1), 0)
+  })
+
+  it('advertises a command window above the next expected CmdSN, wrapping cleanly', () => {
+    const expCmdSN = 0xfffffff0
+    const window = 64
+    assert.equal(addSerial(expCmdSN, window), (0xfffffff0 + 64) % SERIAL_MODULO)
+  })
+})

@vates/iscsi/src/target.integ.mts

@@ -0,0 +1,240 @@
+import assert from 'node:assert/strict'
+import { execFile, execFileSync } from 'node:child_process'
+import { mkdtemp, open as openFile, readFile, rm, truncate, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { promisify } from 'node:util'
+import { after, before, describe, it } from 'node:test'
+
+import { FileBlockDevice, IscsiTarget } from './index.mjs'
+
+const execFileP = promisify(execFile)
+
+const IQN = 'iqn.2024-01.tech.vates:integ'
+const LUN_SIZE = 8 * 1024 * 1024 // 8 MiB
+const BLOCK_SIZE = 512
+
+/**
+ * Determine why the open-iscsi interop test cannot run here (or `false` if it
+ * can). It needs root (to manage iSCSI sessions and flush block buffers) and the
+ * open-iscsi initiator — the exact software XCP-ng uses. As a lighter, root-free
+ * local alternative, the `libiscsi` userspace tools (`iscsi-inq`, `iscsi-ls`)
+ * can smoke-test discovery/INQUIRY without touching the kernel initiator.
+ */
+function skipReason(): string | false {
+  if (process.getuid === undefined || process.getuid() !== 0) {
+    return 'requires root to manage iSCSI sessions'
+  }
+  try {
+    execFileSync('iscsiadm', ['--version'], { stdio: 'ignore' })
+  } catch {
+    return 'requires open-iscsi (iscsiadm not found)'
+  }
+  return false
+}
+
+async function iscsiadm(args: string[]): Promise<string> {
+  const { stdout } = await execFileP('iscsiadm', args)
+  return stdout
+}
+
+/** Parse `iscsiadm -m session -P 3` for the attached SCSI disk's name (e.g. `sdb`) of our target. */
+function parseAttachedDisk(sessionOutput: string): string | undefined {
+  const lines = sessionOutput.split('\n')
+  const targetLine = lines.findIndex(line => line.includes(IQN))
+  if (targetLine === -1) {
+    return undefined
+  }
+  for (let i = targetLine; i < lines.length; i++) {
+    const match = lines[i].match(/Attached scsi disk (sd\w+)/)
+    if (match !== null) {
+      return match[1]
+    }
+  }
+  return undefined
+}
+
+/**
+ * `stat()`ing the device node only proves udev created it, not that the SCSI
+ * layer has finished attaching it — `open()` right after can still fail with
+ * ENXIO. `/sys/class/block/<name>/size` reporting nonzero is what actually
+ * means ready, the same check `_cache.mjs`'s `openLocalDevice` uses for the
+ * same reason on XAPI-plugged devices.
+ */
+async function isDeviceReady(name: string): Promise<boolean> {
+  try {
+    return Number.parseInt(await readFile(`/sys/class/block/${name}/size`, 'utf8'), 10) > 0
+  } catch {
+    return false
+  }
+}
+
+async function waitForDevice(): Promise<string> {
+  for (let attempt = 0; attempt < 40; attempt++) {
+    const session = await iscsiadm(['-m', 'session', '-P', '3']).catch(() => '')
+    const name = parseAttachedDisk(session)
+    if (name !== undefined && (await isDeviceReady(name))) {
+      return `/dev/${name}`
+    }
+    await delay(250)
+  }
+  throw new Error('iSCSI block device did not appear')
+}
+
+describe('open-iscsi interop', { skip: skipReason() }, () => {
+  let dir: string
+  let backingPath: string
+  let target: IscsiTarget
+  let portal: string
+
+  before(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'vates-iscsi-integ-'))
+    backingPath = join(dir, 'lun.img')
+    await writeFile(backingPath, Buffer.alloc(0))
+    await truncate(backingPath, LUN_SIZE)
+
+    target = new IscsiTarget({
+      iqn: IQN,
+      host: '127.0.0.1',
+      port: 0,
+      lun: new FileBlockDevice({ path: backingPath, blockSize: BLOCK_SIZE }),
+    })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+    portal = `127.0.0.1:${address.port}`
+  })
+
+  after(async () => {
+    // Best-effort teardown: logout + drop the node record so the host is clean.
+    await iscsiadm(['-m', 'node', '-T', IQN, '-p', portal, '--logout']).catch(() => {})
+    await iscsiadm(['-m', 'node', '-o', 'delete', '-T', IQN, '-p', portal]).catch(() => {})
+    await target?.close()
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('discovers, logs in, writes and reads back a LUN', async () => {
+    const discovery = await iscsiadm(['-m', 'discovery', '-t', 'sendtargets', '-p', portal])
+    assert.match(discovery, new RegExp(IQN), 'SendTargets discovery should list our IQN')
+
+    await iscsiadm(['-m', 'node', '-T', IQN, '-p', portal, '--login'])
+    const device = await waitForDevice()
+
+    // Write a recognizable pattern at block 10 through the kernel initiator.
+    const lba = 10
+    const offset = lba * BLOCK_SIZE
+    const pattern = Buffer.alloc(BLOCK_SIZE)
+    for (let i = 0; i < pattern.length; i++) {
+      pattern[i] = (i * 3 + 5) & 0xff
+    }
+    const writeHandle = await openFile(device, 'r+')
+    try {
+      await writeHandle.write(pattern, 0, pattern.length, offset)
+      await writeHandle.sync()
+    } finally {
+      await writeHandle.close()
+    }
+
+    // The WRITE path must have landed the bytes in the backing file.
+    const onDisk = await readFile(backingPath)
+    assert.deepEqual(onDisk.subarray(offset, offset + BLOCK_SIZE), pattern, 'backing file updated by WRITE')
+
+    // Drop the page cache so the read traverses the target (READ path).
+    await execFileP('blockdev', ['--flushbufs', device]).catch(() => {})
+    const readHandle = await openFile(device, 'r')
+    try {
+      const buffer = Buffer.alloc(BLOCK_SIZE)
+      await readHandle.read(buffer, 0, BLOCK_SIZE, offset)
+      assert.deepEqual(buffer, pattern, 'data read back through the target matches')
+    } finally {
+      await readHandle.close()
+    }
+  })
+})
+
+// The target as CHAP authenticator against the real open-iscsi initiator (the
+// XCP-ng interop role). Credentials go into the node record's node.session.auth
+// keys, exactly as XCP-ng's `device-config:chapuser`/`chappassword` do.
+describe('open-iscsi CHAP interop', { skip: skipReason() }, () => {
+  // open-iscsi requires the initiator (outgoing) secret to be 12-16 characters.
+  const CHAP = { user: 'alice', secret: 'supersecret1234' }
+  let dir: string
+  let backingPath: string
+  let target: IscsiTarget
+  let portal: string
+
+  async function configureAuth(user: string, secret: string): Promise<void> {
+    const set = (name: string, value: string) =>
+      iscsiadm(['-m', 'node', '-T', IQN, '-p', portal, '-o', 'update', '-n', name, '-v', value])
+    await set('node.session.auth.authmethod', 'CHAP')
+    await set('node.session.auth.username', user)
+    await set('node.session.auth.password', secret)
+  }
+
+  before(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'vates-iscsi-chap-integ-'))
+    backingPath = join(dir, 'lun.img')
+    await writeFile(backingPath, Buffer.alloc(0))
+    await truncate(backingPath, LUN_SIZE)
+
+    target = new IscsiTarget({
+      iqn: IQN,
+      host: '127.0.0.1',
+      port: 0,
+      lun: new FileBlockDevice({ path: backingPath, blockSize: BLOCK_SIZE }),
+      chap: CHAP,
+    })
+    await target.listen()
+    const address = target.address()
+    assert.ok(address !== undefined)
+    portal = `127.0.0.1:${address.port}`
+    // Discovery creates the node record we then attach auth to.
+    await iscsiadm(['-m', 'discovery', '-t', 'sendtargets', '-p', portal])
+  })
+
+  after(async () => {
+    await iscsiadm(['-m', 'node', '-T', IQN, '-p', portal, '--logout']).catch(() => {})
+    await iscsiadm(['-m', 'node', '-o', 'delete', '-T', IQN, '-p', portal]).catch(() => {})
+    await target?.close()
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('rejects login with a wrong secret', async () => {
+    await configureAuth(CHAP.user, 'wrongsecret12345')
+    await assert.rejects(
+      iscsiadm(['-m', 'node', '-T', IQN, '-p', portal, '--login']),
+      'open-iscsi login must fail when the CHAP secret is wrong'
+    )
+  })
+
+  it('authenticates with the right secret and does IO', async () => {
+    await configureAuth(CHAP.user, CHAP.secret)
+    await iscsiadm(['-m', 'node', '-T', IQN, '-p', portal, '--login'])
+    const device = await waitForDevice()
+
+    const lba = 7
+    const offset = lba * BLOCK_SIZE
+    const pattern = Buffer.alloc(BLOCK_SIZE)
+    for (let i = 0; i < pattern.length; i++) {
+      pattern[i] = (i * 5 + 9) & 0xff
+    }
+    const writeHandle = await openFile(device, 'r+')
+    try {
+      await writeHandle.write(pattern, 0, pattern.length, offset)
+      await writeHandle.sync()
+    } finally {
+      await writeHandle.close()
+    }
+
+    await execFileP('blockdev', ['--flushbufs', device]).catch(() => {})
+    const readHandle = await openFile(device, 'r')
+    try {
+      const buffer = Buffer.alloc(BLOCK_SIZE)
+      await readHandle.read(buffer, 0, BLOCK_SIZE, offset)
+      assert.deepEqual(buffer, pattern, 'data read back over an authenticated session matches')
+    } finally {
+      await readHandle.close()
+    }
+  })
+})

@vates/iscsi/src/types.mts

@@ -0,0 +1,149 @@
+import type { BlockDevice } from './backend.mjs'
+import { ScsiOpcode, SERVICE_ACTION_READ_CAPACITY_16 } from './constants.mjs'
+
+// --- Decoded SCSI requests --------------------------------------------------
+
+/** A SCSI command we recognize, decoded from its CDB. */
+export type ScsiRequest =
+  | { kind: 'inquiry'; evpd: boolean; pageCode: number; allocationLength: number }
+  | { kind: 'reportLuns'; allocationLength: number }
+  | { kind: 'readCapacity10' }
+  | { kind: 'readCapacity16'; allocationLength: number }
+  | { kind: 'read'; lba: number; blocks: number }
+  | { kind: 'write'; lba: number; blocks: number }
+  | { kind: 'testUnitReady' }
+  | { kind: 'requestSense'; allocationLength: number }
+  | { kind: 'modeSense'; long: boolean; pageCode: number; allocationLength: number }
+  | { kind: 'syncCache' }
+  | { kind: 'unsupported'; opcode: number }
+
+/** Largest LBA representable as a safe JS integer; guards 64-bit CDB decoding. */
+const MAX_SAFE_LBA = Number.MAX_SAFE_INTEGER
+
+/**
+ * Read a 64-bit LBA, clamped to what a JS number holds exactly.
+ *
+ * An LBA above that is past the capacity of any device we can serve, so the
+ * clamp cannot collide with an addressable block: the caller's
+ * `lba + blocks > blockCount` check rejects it with LBA OUT OF RANGE, which is
+ * the answer SCSI wants anyway. Throwing here instead would take the whole
+ * connection down (the error unwinds to `serve()`, which destroys the socket)
+ * over a single bogus CDB.
+ */
+function readLba64(cdb: Buffer, offset: number): number {
+  const lba = cdb.readBigUInt64BE(offset)
+  return lba > BigInt(MAX_SAFE_LBA) ? MAX_SAFE_LBA : Number(lba)
+}
+
+/**
+ * Decode a SCSI CDB into a {@link ScsiRequest}. Unknown opcodes (and READ
+ * CAPACITY(16)'s sibling service actions we do not implement) map to
+ * `{ kind: 'unsupported' }` so the caller can return CHECK CONDITION. Never
+ * throws: every 16-byte CDB decodes to something the caller can answer.
+ */
+export function decodeCdb(cdb: Buffer): ScsiRequest {
+  const opcode = cdb[0]
+  switch (opcode) {
+    case ScsiOpcode.INQUIRY:
+      return {
+        kind: 'inquiry',
+        evpd: (cdb[1] & 0x01) !== 0,
+        pageCode: cdb[2],
+        allocationLength: cdb.readUInt16BE(3),
+      }
+    case ScsiOpcode.REPORT_LUNS:
+      return { kind: 'reportLuns', allocationLength: cdb.readUInt32BE(6) }
+    case ScsiOpcode.READ_CAPACITY_10:
+      return { kind: 'readCapacity10' }
+    case ScsiOpcode.SERVICE_ACTION_IN_16:
+      if ((cdb[1] & 0x1f) === SERVICE_ACTION_READ_CAPACITY_16) {
+        return { kind: 'readCapacity16', allocationLength: cdb.readUInt32BE(10) }
+      }
+      return { kind: 'unsupported', opcode }
+    case ScsiOpcode.READ_10:
+      return { kind: 'read', lba: cdb.readUInt32BE(2), blocks: cdb.readUInt16BE(7) }
+    case ScsiOpcode.WRITE_10:
+      return { kind: 'write', lba: cdb.readUInt32BE(2), blocks: cdb.readUInt16BE(7) }
+    case ScsiOpcode.READ_16:
+      return { kind: 'read', lba: readLba64(cdb, 2), blocks: cdb.readUInt32BE(10) }
+    case ScsiOpcode.WRITE_16:
+      return { kind: 'write', lba: readLba64(cdb, 2), blocks: cdb.readUInt32BE(10) }
+    case ScsiOpcode.TEST_UNIT_READY:
+      return { kind: 'testUnitReady' }
+    case ScsiOpcode.REQUEST_SENSE:
+      return { kind: 'requestSense', allocationLength: cdb[4] }
+    case ScsiOpcode.MODE_SENSE_6:
+      return { kind: 'modeSense', long: false, pageCode: cdb[2] & 0x3f, allocationLength: cdb[4] }
+    case ScsiOpcode.MODE_SENSE_10:
+      return { kind: 'modeSense', long: true, pageCode: cdb[2] & 0x3f, allocationLength: cdb.readUInt16BE(7) }
+    case ScsiOpcode.SYNCHRONIZE_CACHE_10:
+    case ScsiOpcode.SYNCHRONIZE_CACHE_16:
+      return { kind: 'syncCache' }
+    default:
+      return { kind: 'unsupported', opcode }
+  }
+}
+
+// --- Session / connection state shared across modules -----------------------
+
+/** Operational parameters fixed during login that the SCSI layer depends on. */
+export interface NegotiatedParams {
+  /** Initiator's MaxRecvDataSegmentLength — the cap on each Data-In PDU we send. */
+  initiatorMaxRecvDataSegmentLength: number
+  /** Max bytes solicited per R2T. */
+  maxBurstLength: number
+}
+
+export type SessionType = 'Discovery' | 'Normal'
+
+/**
+ * A single one-way CHAP credential. On the target it is the incoming credential
+ * an initiator must present; on the initiator it is the credential presented to
+ * the target when challenged. Mutual (two-way) CHAP is not yet supported.
+ */
+export interface ChapCredentials {
+  /** CHAP username (`CHAP_N`). */
+  readonly user: string
+  /** CHAP shared secret. */
+  readonly secret: string
+}
+
+/** Sense data to attach to a CHECK CONDITION response. */
+export interface SenseInfo {
+  key: number
+  asc: number
+  ascq: number
+}
+
+export interface ScsiResponseOptions {
+  /** Fixed-format sense data buffer (already serialized). */
+  sense?: Buffer
+  /** Residual byte counts for under/overflow reporting. */
+  residualOverflow?: number
+  residualUnderflow?: number
+}
+
+/**
+ * The capabilities the SCSI command handler needs from its connection: the LUN
+ * backend plus the three ways a command can complete (stream read data, begin a
+ * solicited write, or just return status). The connection implements this;
+ * keeping it an interface avoids a dependency cycle between `scsi` and
+ * `connection`.
+ */
+export interface CommandContext {
+  readonly lun: BlockDevice
+  /**
+   * Send `data` as Data-In PDU(s) with GOOD status piggybacked on the last,
+   * trimmed/residual-reported against `allocationLength`.
+   */
+  sendReadData(itt: number, data: Buffer, allocationLength: number): Promise<void>
+  /**
+   * Begin a solicited write of `totalLength` bytes landing at `lunOffset`: the
+   * connection registers the transfer and sends the first R2T, then returns. The
+   * write executes and its SCSI Response is sent once the Data-Out PDUs arrive
+   * (which may be interleaved with other commands).
+   */
+  beginWrite(itt: number, lunOffset: number, totalLength: number): Promise<void>
+  /** Send a standalone SCSI Response carrying `status` (+ optional sense/residual). */
+  sendScsiResponse(itt: number, status: number, options?: ScsiResponseOptions): Promise<void>
+}

@vates/iscsi/src/writePath.mts

@@ -0,0 +1,151 @@
+import { FLAG_FINAL, TargetOpcode } from './constants.mjs'
+import { allocBhs, assemblePdu } from './pdu.mjs'
+
+/** Sequence numbers stamped into an outbound R2T (which does not advance StatSN). */
+export interface SequenceSnapshot {
+  statSN: number
+  expCmdSN: number
+  maxCmdSN: number
+}
+
+/**
+ * Build a Ready To Transfer (R2T) PDU soliciting `desiredLength` bytes of write
+ * data starting at `bufferOffset`.
+ */
+export function buildR2t(
+  params: {
+    itt: number
+    r2tSN: number
+    targetTransferTag: number
+    bufferOffset: number
+    desiredLength: number
+  },
+  sequence: SequenceSnapshot
+): Buffer {
+  const bhs = allocBhs(TargetOpcode.R2T)
+  bhs[1] = FLAG_FINAL // R2T always has the Final bit set
+  bhs.writeUInt32BE(params.itt, 16)
+  bhs.writeUInt32BE(params.targetTransferTag, 20)
+  bhs.writeUInt32BE(sequence.statSN, 24)
+  bhs.writeUInt32BE(sequence.expCmdSN, 28)
+  bhs.writeUInt32BE(sequence.maxCmdSN, 32)
+  bhs.writeUInt32BE(params.r2tSN, 36)
+  bhs.writeUInt32BE(params.bufferOffset, 40)
+  bhs.writeUInt32BE(params.desiredLength, 44)
+  return assemblePdu(bhs)
+}
+
+/**
+ * State of one in-progress WRITE: data is solicited one burst at a time (we pin
+ * MaxOutstandingR2T=1) and accumulated as Data-Out PDUs arrive, interleaved with
+ * any other commands on the connection.
+ */
+export interface PendingWrite {
+  /** Initiator Task Tag of the WRITE command; Data-Out PDUs are routed by it. */
+  readonly itt: number
+  /** Target Transfer Tag echoed in this command's R2Ts / Data-Out PDUs. */
+  readonly targetTransferTag: number
+  /** Byte offset within the LUN where the data must land. */
+  readonly lunOffset: number
+  /** Assembled write payload. */
+  readonly buffer: Buffer
+  /** Total bytes expected. */
+  readonly totalLength: number
+  /**
+   * Bytes of {@link buffer} filled, counted from offset 0 and contiguous by
+   * construction — see {@link receiveDataOut}. Never a plain count of bytes
+   * received off the wire, which is not the same thing.
+   */
+  contiguousReceived: number
+  /** Bytes solicited so far (one burst ahead of `contiguousReceived`). */
+  solicited: number
+  /** Next R2TSN to emit. */
+  r2tSN: number
+}
+
+/** One inbound Data-Out PDU, reduced to what the write path needs from it. */
+export interface DataOutSegment {
+  /** Target Transfer Tag echoed by the initiator (BHS bytes 20-23). */
+  readonly targetTransferTag: number
+  /** Where these bytes belong, relative to the start of the command's data (BHS bytes 40-43). */
+  readonly bufferOffset: number
+  readonly data: Buffer
+}
+
+/** The PDU was placed in the staging buffer. */
+export interface PlacedDataOut {
+  readonly ok: true
+  /** Every byte of the command has landed: the write can be committed to the LUN. */
+  readonly complete: boolean
+  /** The solicited burst is fully received: the next one can be solicited. */
+  readonly burstComplete: boolean
+}
+
+/** The PDU cannot be placed; the command must be aborted rather than committed. */
+export interface RefusedDataOut {
+  readonly ok: false
+  /** Why, for the log line accompanying the Reject. */
+  readonly reason: string
+}
+
+export type DataOutOutcome = PlacedDataOut | RefusedDataOut
+
+/**
+ * Validate one Data-Out PDU against its pending write and, only if it belongs
+ * exactly where the buffer is still unfilled, copy it in. Validation and copy
+ * live together on purpose: the checks are what make the copy in-bounds, so a
+ * caller must not be able to do one without the other.
+ *
+ * A Data-Out must start exactly where the previous one ended. That strictness
+ * is what makes `contiguousReceived` mean "bytes of the buffer filled" — and
+ * only that meaning makes the completion test sound. Counting bytes as they
+ * arrive off the wire does not work, because `Buffer.copy` silently clamps:
+ *
+ *  - 512 bytes at BufferOffset 512 of a 512-byte write copies *nothing*,
+ *  - 512 bytes at BufferOffset 256 of a 512-byte write copies only 256,
+ *  - the same 256 bytes sent twice copies 256 bytes over themselves.
+ *
+ * Each of those reaches `totalLength` bytes received with part of the buffer
+ * never written, so the target would commit a partly-applied write and answer
+ * GOOD — an acknowledged write silently losing data, which is worse than
+ * failing it. Before this was a contiguity check the staging buffer was also
+ * `allocUnsafe`, so the unwritten part leaked recycled heap to the initiator.
+ *
+ * Requiring contiguity is legitimate only because of what login declares in
+ * `#negotiateOperational`: `InitialR2T=Yes` (no unsolicited data, so every
+ * Data-Out is covered by an R2T and its TTT must match), `DataPDUInOrder=Yes`
+ * (RFC 7143: within a sequence, Data-Out PDUs MUST be in increasing
+ * BufferOffset order) and `MaxOutstandingR2T=1` (only one burst is ever
+ * solicited, so no other range can legitimately be in flight). Each of those
+ * is the winning side of its negotiation rule, so an initiator cannot talk us
+ * out of them. Should any of the three ever change, this must become per-burst
+ * range accounting instead of a single high-water mark.
+ */
+export function receiveDataOut(pending: PendingWrite, segment: DataOutSegment): DataOutOutcome {
+  const { targetTransferTag, bufferOffset, data } = segment
+  if (targetTransferTag !== pending.targetTransferTag) {
+    return {
+      ok: false,
+      reason: `Target Transfer Tag ${targetTransferTag} is not this command's ${pending.targetTransferTag}`,
+    }
+  }
+  if (bufferOffset !== pending.contiguousReceived) {
+    return { ok: false, reason: `BufferOffset ${bufferOffset} is not the expected ${pending.contiguousReceived}` }
+  }
+  // `solicited` only ever grows to at most `totalLength`, so bounding by it also
+  // keeps the copy inside the buffer — no clamping, no silent short copy.
+  if (bufferOffset + data.length > pending.solicited) {
+    return {
+      ok: false,
+      reason: `${data.length} bytes at ${bufferOffset} exceed the ${pending.solicited} bytes solicited`,
+    }
+  }
+
+  data.copy(pending.buffer, bufferOffset)
+  pending.contiguousReceived += data.length
+  return {
+    ok: true,
+    complete: pending.contiguousReceived === pending.totalLength,
+    burstComplete: pending.contiguousReceived === pending.solicited,
+  }
+}

@vates/iscsi/src/writePath.test.mts

@@ -0,0 +1,168 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { FLAG_FINAL, TargetOpcode } from './constants.mjs'
+import { buildR2t, receiveDataOut, type PendingWrite } from './writePath.mjs'
+
+const TTT = 7
+const BLOCK = 512
+
+/**
+ * A pending WRITE with its first burst already solicited, as `beginWrite`
+ * leaves it. `solicited` defaults to the whole command (one burst), which is
+ * what a write below MaxBurstLength gets.
+ */
+const pending = ({
+  totalLength = BLOCK,
+  solicited = totalLength,
+}: { totalLength?: number; solicited?: number } = {}): PendingWrite => ({
+  itt: 1,
+  targetTransferTag: TTT,
+  lunOffset: 0,
+  buffer: Buffer.alloc(totalLength),
+  totalLength,
+  contiguousReceived: 0,
+  solicited,
+  r2tSN: 1,
+})
+
+const dataOut = (bufferOffset: number, length: number, fill = 0xab) => ({
+  targetTransferTag: TTT,
+  bufferOffset,
+  data: Buffer.alloc(length, fill),
+})
+
+describe('buildR2t', () => {
+  it('solicits the requested range, always with the final bit set', () => {
+    const r2t = buildR2t(
+      { itt: 42, r2tSN: 3, targetTransferTag: TTT, bufferOffset: 1024, desiredLength: 512 },
+      { statSN: 9, expCmdSN: 10, maxCmdSN: 74 }
+    )
+
+    assert.equal(r2t[0], TargetOpcode.R2T)
+    assert.equal(r2t[1], FLAG_FINAL)
+    assert.equal(r2t.readUInt32BE(16), 42)
+    assert.equal(r2t.readUInt32BE(20), TTT)
+    assert.equal(r2t.readUInt32BE(36), 3)
+    assert.equal(r2t.readUInt32BE(40), 1024)
+    assert.equal(r2t.readUInt32BE(44), 512)
+  })
+})
+
+describe('receiveDataOut', () => {
+  it('places a burst delivered in one PDU and reports it complete', () => {
+    const write = pending()
+
+    const outcome = receiveDataOut(write, dataOut(0, BLOCK))
+
+    assert.deepEqual(outcome, { ok: true, complete: true, burstComplete: true })
+    assert.equal(write.contiguousReceived, BLOCK)
+    assert.deepEqual(write.buffer, Buffer.alloc(BLOCK, 0xab))
+  })
+
+  it('places consecutive PDUs of one burst, completing only on the last', () => {
+    const write = pending({ totalLength: 3 * BLOCK })
+
+    const first = receiveDataOut(write, dataOut(0, BLOCK, 0x11))
+    const second = receiveDataOut(write, dataOut(BLOCK, BLOCK, 0x22))
+    const third = receiveDataOut(write, dataOut(2 * BLOCK, BLOCK, 0x33))
+
+    assert.deepEqual(first, { ok: true, complete: false, burstComplete: false })
+    assert.deepEqual(second, { ok: true, complete: false, burstComplete: false })
+    assert.deepEqual(third, { ok: true, complete: true, burstComplete: true })
+    assert.deepEqual(
+      write.buffer,
+      Buffer.concat([Buffer.alloc(BLOCK, 0x11), Buffer.alloc(BLOCK, 0x22), Buffer.alloc(BLOCK, 0x33)])
+    )
+  })
+
+  it('reports the burst complete, but not the command, when more remains to solicit', () => {
+    const write = pending({ totalLength: 2 * BLOCK, solicited: BLOCK })
+
+    const outcome = receiveDataOut(write, dataOut(0, BLOCK))
+
+    assert.deepEqual(outcome, { ok: true, complete: false, burstComplete: true })
+  })
+
+  // The three ways a plain count of received bytes reached `totalLength` with
+  // part of the staging buffer never written — each one an acknowledged write
+  // that silently lost data, since `Buffer.copy` clamps instead of throwing.
+  describe('refuses a PDU that would leave a hole in the buffer', () => {
+    it('past the end of the buffer, where the copy would land nothing', () => {
+      const write = pending()
+
+      const outcome = receiveDataOut(write, dataOut(BLOCK, BLOCK))
+
+      assert.equal(outcome.ok, false)
+      assert.equal(write.contiguousReceived, 0)
+      assert.deepEqual(write.buffer, Buffer.alloc(BLOCK))
+    })
+
+    it('straddling the end, where the copy would be silently short', () => {
+      const write = pending()
+
+      const outcome = receiveDataOut(write, dataOut(BLOCK / 2, BLOCK))
+
+      assert.equal(outcome.ok, false)
+      assert.equal(write.contiguousReceived, 0)
+    })
+
+    it('repeating a range already received, which would never fill the rest', () => {
+      const write = pending()
+      assert.equal(receiveDataOut(write, dataOut(0, BLOCK / 2, 0x11)).ok, true)
+
+      const outcome = receiveDataOut(write, dataOut(0, BLOCK / 2, 0x22))
+
+      assert.equal(outcome.ok, false)
+      // the first PDU's bytes are still there, and the rest is still unfilled
+      assert.equal(write.contiguousReceived, BLOCK / 2)
+      assert.deepEqual(write.buffer, Buffer.concat([Buffer.alloc(BLOCK / 2, 0x11), Buffer.alloc(BLOCK / 2)]))
+    })
+
+    it('skipping ahead, leaving a gap before it', () => {
+      const write = pending({ totalLength: 2 * BLOCK })
+
+      const outcome = receiveDataOut(write, dataOut(BLOCK, BLOCK))
+
+      assert.equal(outcome.ok, false)
+      assert.equal(write.contiguousReceived, 0)
+    })
+  })
+
+  it('refuses bytes beyond the current burst, even when the buffer could hold them', () => {
+    // 2 blocks solicited of a 4-block write: the last 2 are only legitimate
+    // after the next R2T, so accepting them now would break burst accounting
+    const write = pending({ totalLength: 4 * BLOCK, solicited: 2 * BLOCK })
+
+    const outcome = receiveDataOut(write, dataOut(0, 3 * BLOCK))
+
+    assert.equal(outcome.ok, false)
+    assert.equal(write.contiguousReceived, 0)
+  })
+
+  it("refuses a PDU carrying another command's Target Transfer Tag", () => {
+    const write = pending()
+
+    const outcome = receiveDataOut(write, { ...dataOut(0, BLOCK), targetTransferTag: TTT + 1 })
+
+    assert.equal(outcome.ok, false)
+    assert.equal(write.contiguousReceived, 0)
+  })
+
+  it('explains why it refused, for the log line next to the Reject', () => {
+    const outcome = receiveDataOut(pending(), dataOut(BLOCK, BLOCK))
+
+    assert.equal(outcome.ok, false)
+    assert.match(outcome.ok === false ? outcome.reason : '', /BufferOffset/)
+  })
+
+  it('accepts a zero-length PDU without disturbing the coverage it has', () => {
+    const write = pending()
+    receiveDataOut(write, dataOut(0, BLOCK / 2, 0x11))
+
+    const outcome = receiveDataOut(write, dataOut(BLOCK / 2, 0))
+
+    assert.deepEqual(outcome, { ok: true, complete: false, burstComplete: false })
+    assert.equal(write.contiguousReceived, BLOCK / 2)
+  })
+})

@vates/iscsi/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "ESNext",
+    "types": ["node"], // Only use types from Node.js and packages that are explicitly imported
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true, // Skip type-checking dependency .d.ts (e.g. @xen-orchestra/disk-transform), as it does itself
+    "declaration": true, // Generates `.d.ts` files for type safety
+    "outDir": "dist" // Outputs compiled code to the `dist` directory
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

@vates/nbd-client/.USAGE.md

@@ -1,6 +1,12 @@
-### `new NdbClient({address, exportname, secure = true, port = 10809})`
+This package provides a NBD client, in two flavors sharing the same protocol
+implementation (`AbstractNbdClient`): over the network, or over the standard
+streams of a NBD server run as a child process.
 
-create a new nbd client
+### `new NbdClient({address, exportname, cert, port = 10809})`
+
+Create a new nbd client connecting to a server over TCP.
+
+`NbdClient` is also exported as `NbdTcpClient`.
 
 ```js
 import NbdClient from '@vates/nbd-client'
@@ -14,3 +20,55 @@ await client.connect()
 const block = await client.readBlock(blockIndex, BlockSize)
 await client.disconnect()
 ```
+
+### `new NbdStdioClient({command, args, exportname})`
+
+Create a new nbd client talking to a server through its standard streams, like
+`nbdkit --single` or any server reading its queries on stdin and writing its
+answers on stdout.
+
+The process is spawned by `connect()` and stopped by `disconnect()`.
+
+```js
+import { NbdStdioClient } from '@vates/nbd-client'
+const client = new NbdStdioClient({
+  command: 'nbdkit',
+  args: ['--single', '--exit-with-parent', '--read-only', 'file', '/path/to/disk.raw'],
+  exportname: '', // optional, the default export of the server
+})
+
+await client.connect()
+const block = await client.readBlock(blockIndex, BlockSize)
+await client.disconnect()
+```
+
+There is no TLS here: the transport is a pair of pipes, there is nothing to
+encrypt.
+
+`readBlock()` retries on error, and a retry reconnects: with this client that
+means killing the server and spawning a new one, so the command must be
+restartable and must serve the same content on each run.
+
+`getMap()` is not implemented, since `nbdinfo` needs either an URI or a server
+supporting systemd socket activation: compute the map on the caller side and
+pass it explicitly, for example `new NbdDisk(infos, blockSize, { dataMap })`.
+
+The tail of the server stderr is available as `client.stderr` and attached to
+the errors raised when the server dies unexpectedly.
+
+### Writing another client
+
+Subclass `AbstractNbdClient` and implement the transport:
+
+- `_openTransport()`: **required**, returns `{ readable, writable }`, called on
+  every (re)connection.
+- `_secureTransport(transport)`: optional, called during the handshake, the only
+  place where the transport can be upgraded (`NBD_OPT_STARTTLS`).
+- `_closeTransport(transport, lastMessage)`: optional, must hand over
+  `lastMessage` (`NBD_CMD_DISC`) before closing.
+- `_destroyTransport(transport)`: optional, forceful cleanup, must not throw.
+- `getMap(signal)`: optional, the base implementation rejects with the code
+  `NBD_MAP_UNSUPPORTED`.
+
+Any extra property set on the transport object is passed back to
+`_closeTransport()` and `_destroyTransport()`.

@vates/nbd-client/AbstractNbdClient.mjs

@@ -0,0 +1,572 @@
+import assert from 'node:assert'
+import { pRetry, pDelay, pTimeout, pFromCallback } from 'promise-toolbox'
+import { readChunkStrict } from '@vates/read-chunk'
+import { createLogger } from '@xen-orchestra/log'
+import {
+  INIT_PASSWD,
+  NBD_CMD_DISC,
+  NBD_CMD_READ,
+  NBD_DEFAULT_BLOCK_SIZE,
+  NBD_FLAG_FIXED_NEWSTYLE,
+  NBD_FLAG_HAS_FLAGS,
+  NBD_OPT_EXPORT_NAME,
+  NBD_OPT_REPLY_MAGIC,
+  NBD_REPLY_ACK,
+  NBD_REPLY_MAGIC,
+  NBD_REQUEST_MAGIC,
+  OPTS_MAGIC,
+} from './constants.mjs'
+
+const { debug, warn } = createLogger('vates:nbd-client')
+
+// documentation is here : https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
+
+/**
+ * A pair of streams carrying the NBD protocol.
+ *
+ * For a TCP client both are the same socket, for a client talking to a server
+ * through its standard streams they are the two ends of two different pipes.
+ *
+ * @typedef {object} NbdTransport
+ * @property {import('node:stream').Readable} readable - where the server answers are read from
+ * @property {import('node:stream').Writable} writable - where the client queries are written to
+ */
+
+/**
+ * Transport agnostic NBD client: it implements the handshake and the
+ * transmission phases, and delegates the opening/closing of the underlying
+ * streams to its subclasses.
+ *
+ * Subclasses MUST implement `_openTransport()` and MAY override
+ * `_secureTransport()`, `_closeTransport()`, `_destroyTransport()` and `getMap()`.
+ *
+ * @abstract
+ */
+export default class AbstractNbdClient {
+  #exportName
+  #exportSize
+
+  /** @type {NbdTransport|undefined} */
+  #transport
+
+  // incremented on each connection attempt: an attempt which is not the last
+  // one anymore has been superseded (its caller timed out on it) and must not
+  // publish itself
+  #connectGeneration = 0
+
+  #waitBeforeReconnect
+  #readBlockRetries
+  #reconnectRetry
+  #connectTimeout
+  #messageTimeout
+
+  // AFAIK, there is no guaranty the server answers in the same order as the queries
+  // so we handle a backlog of command waiting for response and handle concurrency manually
+
+  #waitingForResponse // there is already a listener waiting for a response
+  #nextCommandQueryId = BigInt(0)
+  // map of command waiting for a response queryId => { size/*in byte*/, resolve, reject}
+  #commandQueryBacklog = new Map()
+  #connected = false
+
+  #reconnectingPromise
+
+  /**
+   * @param {object} settings
+   * @param {string} [settings.exportname] - the NBD export to open, empty for the default one
+   * @param {object} [options]
+   * @param {number} [options.connectTimeout]
+   * @param {number} [options.messageTimeout]
+   * @param {number} [options.waitBeforeReconnect]
+   * @param {number} [options.readBlockRetries]
+   * @param {number} [options.reconnectRetry]
+   */
+  constructor(
+    { exportname = '' },
+    {
+      connectTimeout = 6e4,
+      messageTimeout = 6e4,
+      waitBeforeReconnect = 1e3,
+      readBlockRetries = 5,
+      reconnectRetry = 5,
+    } = {}
+  ) {
+    this.#exportName = exportname
+    this.#waitBeforeReconnect = waitBeforeReconnect
+    this.#readBlockRetries = readBlockRetries
+    this.#reconnectRetry = reconnectRetry
+    this.#connectTimeout = connectTimeout
+    this.#messageTimeout = messageTimeout
+  }
+
+  get exportSize() {
+    return this.#exportSize
+  }
+
+  get exportName() {
+    return this.#exportName
+  }
+
+  get connected() {
+    return this.#connected
+  }
+
+  /* ---------------------------------------------------------------------------
+   * transport, to be implemented by the subclasses
+   * ------------------------------------------------------------------------- */
+
+  /**
+   * Open the streams used to talk to the NBD server.
+   *
+   * Called on every (re)connection: it must be able to open a brand new
+   * transport each time it is called.
+   *
+   * @abstract
+   * @returns {Promise<NbdTransport>}
+   */
+  async _openTransport() {
+    throw new Error(`${this.constructor.name} must implement _openTransport()`)
+  }
+
+  /**
+   * Hook called during the handshake, after the client flags have been sent and
+   * before the export is selected: this is the only moment where the transport
+   * can be upgraded (NBD_OPT_STARTTLS).
+   *
+   * Returning another transport than the one received replaces it, returning
+   * the same one is a no-op.
+   *
+   * @param {NbdTransport} transport
+   * @returns {Promise<NbdTransport>}
+   */
+  async _secureTransport(transport) {
+    return transport
+  }
+
+  /**
+   * Gracefully close the transport.
+   *
+   * `lastMessage` is a ready to send NBD_CMD_DISC: implementations must hand it
+   * over to the server (it is the only clean way to tell it we're done) before
+   * closing their side.
+   *
+   * Failing or timing out here is not fatal: `_destroyTransport()` will be
+   * called as a fallback.
+   *
+   * @param {NbdTransport} transport
+   * @param {Buffer} lastMessage
+   * @returns {Promise<void>}
+   */
+  async _closeTransport(transport, lastMessage) {
+    await pFromCallback(cb => transport.writable.end(lastMessage, cb))
+  }
+
+  /**
+   * Forcefully release the transport and everything backing it.
+   *
+   * Must be idempotent, and must not throw.
+   *
+   * @param {NbdTransport} transport
+   * @returns {void}
+   */
+  _destroyTransport(transport) {
+    transport.readable.destroy()
+    if (transport.writable !== transport.readable) {
+      transport.writable.destroy()
+    }
+  }
+
+  /**
+   * Returns the map of the file with holes, zeros and data, useful to handle
+   * efficiently sparse sources.
+   *
+   * The base implementation is unable to compute it: subclasses able to do so
+   * must override this method.
+   *
+   * To implement this here: use structured replies if the server supports them,
+   * and then ask for BLOCK_STATUS.
+   *
+   * @returns {Promise<{ offset: number, length: number, type: number }[]>}
+   * A promise that resolves to an array where each object represents a segment:
+   * - `offset` — The byte offset from the start.
+   * - `length` — The size of the segment in bytes.
+   * - `type` — A numeric code indicating the segment type ( 0 means data).
+   */
+  async getMap() {
+    const error = new Error(`${this.constructor.name} does not support getMap()`)
+    error.code = 'NBD_MAP_UNSUPPORTED'
+    throw error
+  }
+
+  /* ---------------------------------------------------------------------------
+   * connection
+   * ------------------------------------------------------------------------- */
+
+  #onTransportError = error => {
+    // without this listener an error on the transport would be thrown as an
+    // uncaught exception, and pending reads would only fail on message timeout
+    //
+    // an error outside of the connected window is expected (the other end can
+    // be gone already while we're closing), and always reported to the caller
+    // through the connect()/readBlock() rejection
+    const log = this.#connected ? warn : debug
+    log('error on the nbd transport', { error })
+    this.#rejectAll(error)
+  }
+
+  #watchTransport(transport) {
+    transport.readable.on('error', this.#onTransportError)
+    if (transport.writable !== transport.readable) {
+      transport.writable.on('error', this.#onTransportError)
+    }
+  }
+
+  async #connect() {
+    const generation = ++this.#connectGeneration
+    // the transport is kept local until the client is connected: connect() does
+    // not cancel on timeout, so a superseded attempt must not be able to use,
+    // replace or destroy the transport of the attempt which replaced it
+    let transport = await this._openTransport()
+    this.#watchTransport(transport)
+    try {
+      // the transport can be replaced during the handshake (TLS upgrade)
+      transport = await this.#handshake(transport)
+
+      if (generation !== this.#connectGeneration) {
+        const error = new Error('this connection has been superseded by a newer one')
+        error.code = 'NBD_CONNECT_SUPERSEDED'
+        throw error
+      }
+    } catch (error) {
+      // don't leak the transport (a socket, a child process, ...): disconnect()
+      // is a no-op as long as we're not connected, so nobody else will close it
+      this.#destroyTransport(transport)
+      throw error
+    }
+    this.#transport = transport
+    this.#connected = true
+    // reset internal state if we reconnected a nbd client
+    this.#commandQueryBacklog = new Map()
+    this.#waitingForResponse = false
+  }
+
+  async connect() {
+    const promise = this.#connect()
+    try {
+      return await pTimeout.call(promise, this.#connectTimeout)
+    } catch (error) {
+      // pTimeout does not cancel: #connect() may still be running and end up
+      // with an opened transport nobody owns anymore
+      promise.then(
+        () =>
+          this.disconnect().catch(cleanupError => warn('error while cleaning up a late connection', { cleanupError })),
+        () => {} // the failure is already reported through `error`
+      )
+      throw error
+    }
+  }
+
+  async disconnect() {
+    if (!this.#connected) {
+      return
+    }
+    this.#connected = false
+    const transport = this.#transport
+    this.#transport = undefined
+    if (transport === undefined) {
+      return
+    }
+
+    const queryId = this.#nextCommandQueryId
+    this.#nextCommandQueryId++
+
+    const buffer = Buffer.alloc(28)
+    buffer.writeInt32BE(NBD_REQUEST_MAGIC, 0) // it is a nbd request
+    buffer.writeInt16BE(0, 4) // no command flags for a disconnect
+    buffer.writeInt16BE(NBD_CMD_DISC, 6) // we want to disconnect from nbd server
+    buffer.writeBigUInt64BE(queryId, 8)
+    buffer.writeBigUInt64BE(0n, 16)
+    buffer.writeInt32BE(0, 24)
+
+    try {
+      await pTimeout.call(this._closeTransport(transport, buffer), this.#messageTimeout)
+    } catch (error) {
+      // expected when the other end is already gone, nothing actionable: the
+      // transport is destroyed instead of being closed gracefully
+      debug('error while closing the nbd transport, destroying it', { error })
+      this.#destroyTransport(transport)
+    }
+  }
+
+  #destroyTransport(transport) {
+    try {
+      this._destroyTransport(transport)
+    } catch (error) {
+      warn('error while destroying the nbd transport', { error })
+    }
+  }
+
+  #clearReconnectPromise = () => {
+    this.#reconnectingPromise = undefined
+  }
+
+  async #reconnect() {
+    await this.disconnect().catch(() => {})
+    await pDelay(this.#waitBeforeReconnect) // need to let the xapi clean things on its side
+    await this.connect()
+  }
+
+  async reconnect() {
+    // we need to ensure reconnections do not occur in parallel
+    if (this.#reconnectingPromise === undefined) {
+      this.#reconnectingPromise = pRetry(() => this.#reconnect(), {
+        tries: this.#reconnectRetry,
+      })
+      this.#reconnectingPromise.then(this.#clearReconnectPromise, this.#clearReconnectPromise)
+    }
+
+    return this.#reconnectingPromise
+  }
+
+  /* ---------------------------------------------------------------------------
+   * handshake
+   * ------------------------------------------------------------------------- */
+
+  /**
+   * Send an option to the server and check it acknowledged it.
+   *
+   * We can use individual read/write from the transport here since there is no
+   * concurrency during the handshake.
+   *
+   * The transport is passed explicitly since the client is not connected yet:
+   * it is only published once the handshake succeeded.
+   *
+   * protected: subclasses need it to negotiate their own options (NBD_OPT_STARTTLS)
+   *
+   * @param {NbdTransport} transport
+   * @param {number} option
+   * @param {Buffer} [buffer] - the payload of the option
+   */
+  async _sendOption(transport, option, buffer = Buffer.alloc(0)) {
+    await this.#write(transport, OPTS_MAGIC)
+    await this.#writeInt32(transport, option)
+    await this.#writeInt32(transport, buffer.length)
+    await this.#write(transport, buffer)
+    assert.strictEqual(await this.#readInt64(transport), NBD_OPT_REPLY_MAGIC) // magic number everywhere
+    assert.strictEqual(await this.#readInt32(transport), option) // the option passed
+    assert.strictEqual(await this.#readInt32(transport), NBD_REPLY_ACK) // ACK
+    const length = await this.#readInt32(transport)
+    assert.strictEqual(length, 0) // length
+  }
+
+  // we can use individual read/write from the transport here since there is only one handshake at once, no concurrency
+  //
+  // it works on the transport it is given and returns the one to use for the
+  // transmission phase, which is not necessarily the same (TLS upgrade)
+  //
+  /**
+   * @param {NbdTransport} transport
+   * @returns {Promise<NbdTransport>}
+   */
+  async #handshake(transport) {
+    assert((await this.#read(transport, 8)).equals(INIT_PASSWD))
+    assert((await this.#read(transport, 8)).equals(OPTS_MAGIC))
+    const flagsBuffer = await this.#read(transport, 2)
+    const flags = flagsBuffer.readInt16BE(0)
+    assert.strictEqual(flags & NBD_FLAG_FIXED_NEWSTYLE, NBD_FLAG_FIXED_NEWSTYLE) // only FIXED_NEWSTYLE one is supported from the server options
+    await this.#writeInt32(transport, NBD_FLAG_FIXED_NEWSTYLE) // client also support  NBD_FLAG_C_FIXED_NEWSTYLE
+
+    // let the subclass upgrade the transport if it needs to (TLS)
+    const secured = await this._secureTransport(transport)
+    if (secured !== transport) {
+      this.#watchTransport(secured)
+      transport = secured
+    }
+
+    // send export name we want to access.
+    // it's implicitly closing the negotiation phase.
+    await this.#write(transport, OPTS_MAGIC)
+    await this.#writeInt32(transport, NBD_OPT_EXPORT_NAME)
+    const exportNameBuffer = Buffer.from(this.#exportName)
+    await this.#writeInt32(transport, exportNameBuffer.length)
+    await this.#write(transport, exportNameBuffer)
+
+    // 8 (export size ) + 2 (flags) + 124 zero = 134
+    // must read all to ensure nothing stays in the  buffer
+    const answer = await this.#read(transport, 134)
+    this.#exportSize = answer.readBigUInt64BE(0)
+    const transmissionFlags = answer.readInt16BE(8)
+    assert.strictEqual(transmissionFlags & NBD_FLAG_HAS_FLAGS, NBD_FLAG_HAS_FLAGS, 'NBD_FLAG_HAS_FLAGS') // must always be 1 by the norm
+
+    // note : xapi server always send NBD_FLAG_READ_ONLY (3) as a flag
+
+    return transport
+  }
+
+  /* ---------------------------------------------------------------------------
+   * raw read/write
+   * ------------------------------------------------------------------------- */
+
+  #getTransport() {
+    const transport = this.#transport
+    if (transport === undefined) {
+      const error = new Error('the nbd client is not connected')
+      error.code = 'NBD_NOT_CONNECTED'
+      throw error
+    }
+    return transport
+  }
+
+  #read(transport, length) {
+    const promise = readChunkStrict(transport.readable, length)
+    return pTimeout.call(promise, this.#messageTimeout)
+  }
+
+  #write(transport, buffer) {
+    let timeout
+    const messageTimeout = this.#messageTimeout
+    const { writable } = transport
+    return Promise.race([
+      new Promise((resolve, reject) => {
+        timeout = setTimeout(() => {
+          reject(new Error('timeout'))
+        }, messageTimeout)
+      }),
+      new Promise(resolve =>
+        writable.write(buffer, () => {
+          clearTimeout(timeout)
+          resolve()
+        })
+      ),
+    ])
+  }
+
+  async #readInt32(transport) {
+    const buffer = await this.#read(transport, 4)
+    return buffer.readInt32BE(0)
+  }
+
+  async #readInt64(transport) {
+    const buffer = await this.#read(transport, 8)
+    return buffer.readBigUInt64BE(0)
+  }
+
+  #writeInt32(transport, int) {
+    const buffer = Buffer.alloc(4)
+    buffer.writeInt32BE(int)
+    return this.#write(transport, buffer)
+  }
+
+  /* ---------------------------------------------------------------------------
+   * transmission
+   * ------------------------------------------------------------------------- */
+
+  // when one read fail ,stop everything
+  // (sync: it must be usable from an event handler without leaving a floating promise)
+  #rejectAll(error) {
+    this.#commandQueryBacklog.forEach(({ reject }) => {
+      reject(error)
+    })
+  }
+
+  async #readBlockResponse() {
+    // ensure at most one read occur in parallel
+    if (this.#waitingForResponse) {
+      return
+    }
+    try {
+      this.#waitingForResponse = true
+      const transport = this.#getTransport()
+      const buffer = await this.#read(transport, 16)
+      const magic = buffer.readInt32BE(0)
+
+      if (magic !== NBD_REPLY_MAGIC) {
+        throw new Error(`magic number for block answer is wrong : ${magic} ${NBD_REPLY_MAGIC}`)
+      }
+
+      const error = buffer.readInt32BE(4)
+      if (error !== 0) {
+        // @todo use error code from constants.mjs
+        throw new Error(`GOT ERROR CODE  : ${error}`)
+      }
+
+      const blockQueryId = buffer.readBigUInt64BE(8)
+      const query = this.#commandQueryBacklog.get(blockQueryId)
+      if (!query) {
+        throw new Error(` no query associated with id ${blockQueryId}`)
+      }
+      this.#commandQueryBacklog.delete(blockQueryId)
+      const data = await this.#read(transport, query.size)
+      query.resolve(data)
+      this.#waitingForResponse = false
+      if (this.#commandQueryBacklog.size > 0) {
+        // it doesn't throw directly but will throw all relevant promise on failure
+        this.#readBlockResponse()
+      }
+    } catch (error) {
+      // reject all the promises
+      // we don't need to call readBlockResponse on failure
+      // since we will empty the backlog
+      this.#rejectAll(error)
+    }
+  }
+
+  async #readBlock(index, size) {
+    // we don't want to add anything in backlog while reconnecting
+    if (this.#reconnectingPromise) {
+      await this.#reconnectingPromise
+    }
+
+    const queryId = this.#nextCommandQueryId
+    this.#nextCommandQueryId++
+
+    // create and send  command at once to ensure there is no concurrency issue
+    const buffer = Buffer.alloc(28)
+    buffer.writeInt32BE(NBD_REQUEST_MAGIC, 0) // it is a nbd request
+    buffer.writeInt16BE(0, 4) // no command flags for a simple block read
+    buffer.writeInt16BE(NBD_CMD_READ, 6) // we want to read a data block
+    buffer.writeBigUInt64BE(queryId, 8)
+    // byte offset in the raw disk
+    const offset = BigInt(index) * BigInt(size)
+    const remaining = this.#exportSize - offset
+    if (remaining < BigInt(size)) {
+      size = Number(remaining)
+    }
+
+    buffer.writeBigUInt64BE(offset, 16)
+    buffer.writeInt32BE(size, 24)
+
+    return new Promise((resolve, reject) => {
+      function decoratedReject(error) {
+        error.index = index
+        error.size = size
+        reject(error)
+      }
+
+      // this will handle one block response, but it can be another block
+      // since server does not guaranty to handle query in order
+      this.#commandQueryBacklog.set(queryId, {
+        size,
+        resolve,
+        reject: decoratedReject,
+      })
+      // really send the command to the server
+      this.#write(this.#getTransport(), buffer).catch(decoratedReject)
+
+      // #readBlockResponse never throws directly
+      // but if it fails it will reject all the promises in the backlog
+      this.#readBlockResponse()
+    })
+  }
+
+  async readBlock(index, size = NBD_DEFAULT_BLOCK_SIZE) {
+    return pRetry(() => this.#readBlock(index, size), {
+      tries: this.#readBlockRetries,
+      when: error => error.code !== 'ERR_ABORTED',
+      onRetry: async err => {
+        warn('will retry reading block ', index, err)
+        await this.reconnect()
+      },
+    })
+  }
+}

@vates/nbd-client/AbstractNbdClient.test.mjs

@@ -0,0 +1,177 @@
+import assert from 'node:assert/strict'
+import { PassThrough } from 'node:stream'
+import { setTimeout as pSleep } from 'node:timers/promises'
+import { describe, it } from 'node:test'
+
+import AbstractNbdClient from './AbstractNbdClient.mjs'
+import { serveNbd } from './tests/fake-nbd-server.mjs'
+
+const BLOCK_SIZE = 512
+// non aligned size, to check the truncated last block
+const DATA = Buffer.alloc(BLOCK_SIZE * 3 + 100)
+for (let i = 0; i < DATA.length; i += 4) {
+  DATA.writeUInt32BE(i, i)
+}
+
+// exercises AbstractNbdClient without any I/O: the fake server runs in the same
+// process, on the other end of two in-memory streams
+class InMemoryNbdClient extends AbstractNbdClient {
+  #serverOptions
+
+  /** @type {Array<object>} */
+  transports = []
+  /** @type {Array<object>} */
+  destroyedTransports = []
+  secureTransportCalls = 0
+
+  constructor({ exportname, ...serverOptions } = {}, options) {
+    super({ exportname }, options)
+    this.#serverOptions = serverOptions
+  }
+
+  async _openTransport() {
+    const toServer = new PassThrough()
+    const toClient = new PassThrough()
+    const transport = { readable: toClient, writable: toServer }
+    this.transports.push(transport)
+
+    // the server runs alongside the client, a failure on its side is reported
+    // to the client the same way a network error would be
+    serveNbd({ readable: toServer, writable: toClient, data: DATA, ...this.#serverOptions }).catch(error =>
+      toClient.destroy(error)
+    )
+
+    return transport
+  }
+
+  async _secureTransport(transport) {
+    this.secureTransportCalls++
+    return super._secureTransport(transport)
+  }
+
+  _destroyTransport(transport) {
+    this.destroyedTransports.push(transport)
+    super._destroyTransport(transport)
+  }
+}
+
+// the first connection is opened on a transport nobody ever answers on: its
+// handshake stalls until the message timeout, well after connect() gave up
+class StallingFirstConnectClient extends InMemoryNbdClient {
+  #openCalls = 0
+
+  async _openTransport() {
+    if (this.#openCalls++ === 0) {
+      const transport = { readable: new PassThrough(), writable: new PassThrough() }
+      this.transports.push(transport)
+      return transport
+    }
+    return super._openTransport()
+  }
+}
+
+describe('AbstractNbdClient', () => {
+  it('handshakes and reads blocks', async () => {
+    const client = new InMemoryNbdClient()
+    await client.connect()
+    try {
+      assert.equal(client.exportSize, BigInt(DATA.length))
+      assert.equal(client.connected, true)
+
+      const block = await client.readBlock(1, BLOCK_SIZE)
+      assert.ok(block.equals(DATA.subarray(BLOCK_SIZE, 2 * BLOCK_SIZE)))
+    } finally {
+      await client.disconnect()
+    }
+    assert.equal(client.connected, false)
+  })
+
+  it('truncates the last block of a non aligned export', async () => {
+    const client = new InMemoryNbdClient()
+    await client.connect()
+    try {
+      const block = await client.readBlock(3, BLOCK_SIZE)
+      assert.equal(block.length, DATA.length - 3 * BLOCK_SIZE)
+      assert.ok(block.equals(DATA.subarray(3 * BLOCK_SIZE)))
+    } finally {
+      await client.disconnect()
+    }
+  })
+
+  it('handles answers coming out of order', async () => {
+    const client = new InMemoryNbdClient({ answerInReverse: true })
+    await client.connect()
+    try {
+      const [first, second] = await Promise.all([client.readBlock(0, BLOCK_SIZE), client.readBlock(1, BLOCK_SIZE)])
+      assert.ok(first.equals(DATA.subarray(0, BLOCK_SIZE)))
+      assert.ok(second.equals(DATA.subarray(BLOCK_SIZE, 2 * BLOCK_SIZE)))
+    } finally {
+      await client.disconnect()
+    }
+  })
+
+  it('calls _secureTransport during the handshake', async () => {
+    const client = new InMemoryNbdClient()
+    await client.connect()
+    assert.equal(client.secureTransportCalls, 1)
+    await client.disconnect()
+  })
+
+  it('does not leak the transport when the handshake fails', async () => {
+    // the server expects another export name, and fails the handshake
+    const client = new InMemoryNbdClient({ exportname: 'wrong', exportName: 'expected' })
+    await assert.rejects(client.connect())
+
+    assert.equal(client.connected, false)
+    assert.equal(client.transports.length, 1)
+    assert.deepEqual(client.destroyedTransports, client.transports)
+    assert.equal(client.transports[0].writable.destroyed, true)
+  })
+
+  it('reports the errors answered by the server, after having retried', async () => {
+    const client = new InMemoryNbdClient(
+      { errorCode: () => 5 /* EIO */ },
+      { readBlockRetries: 2, reconnectRetry: 1, waitBeforeReconnect: 0 }
+    )
+    await client.connect()
+    try {
+      await assert.rejects(client.readBlock(0, BLOCK_SIZE), /ERROR CODE/)
+      // one transport for the initial connection, one for the retry
+      assert.equal(client.transports.length, 2)
+    } finally {
+      await client.disconnect()
+    }
+  })
+
+  it('does not let a connection which timed out disturb the next one', async () => {
+    const client = new StallingFirstConnectClient({}, { connectTimeout: 50, messageTimeout: 150 })
+    await assert.rejects(client.connect())
+
+    // the previous attempt is still running: it must not publish itself, nor
+    // touch the transport of this one
+    await client.connect()
+    try {
+      // let the stalled handshake reach its message timeout
+      await pSleep(250)
+
+      assert.equal(client.connected, true)
+      assert.equal(client.transports.length, 2)
+      // only the stalled transport has been destroyed
+      assert.deepEqual(client.destroyedTransports, [client.transports[0]])
+
+      const block = await client.readBlock(0, BLOCK_SIZE)
+      assert.ok(block.equals(DATA.subarray(0, BLOCK_SIZE)))
+    } finally {
+      await client.disconnect()
+    }
+  })
+
+  it('does not support getMap()', async () => {
+    const client = new InMemoryNbdClient()
+    await assert.rejects(client.getMap(), ({ code }) => code === 'NBD_MAP_UNSUPPORTED')
+  })
+
+  it('can be disconnected without being connected', async () => {
+    await new InMemoryNbdClient().disconnect()
+  })
+})

@vates/nbd-client/NbdDisk.mjs

@@ -5,12 +5,18 @@ import NbdClient from '@vates/nbd-client'
  * @typedef {{ offset: number, length: number }} DataRange
  */
 
+/**
+ * any NBD client, whatever transport it uses
+ *
+ * @typedef {import('@vates/nbd-client').AbstractNbdClient} AbstractNbdClient
+ */
+
 /**
  * @extends {RandomAccessDisk}
  */
 export class NbdDisk extends RandomAccessDisk {
   #nbdInfos
-  /** @type {NbdClient|undefined} */
+  /** @type {AbstractNbdClient|undefined} */
   #nbdClient
 
   /** @type {Array<DataRange> | undefined} */
@@ -25,10 +31,21 @@ export class NbdDisk extends RandomAccessDisk {
   /** @type {number | undefined} */
   #hasBlockPreviousIndex
 
-  constructor(nbdInfos, blockSize, { dataMap } = {}) {
+  /** @type {typeof AbstractNbdClient} */
+  #ClientClass
+
+  /**
+   * @param {object} nbdInfos - the settings of the client, depends on `ClientClass`
+   * @param {number} blockSize
+   * @param {object} [options]
+   * @param {Array<{offset: number, length: number, type: number}>} [options.dataMap] - computed through `getMap()` when not provided
+   * @param {typeof AbstractNbdClient} [options.ClientClass] - to talk to a NBD server through another transport
+   */
+  constructor(nbdInfos, blockSize, { dataMap, ClientClass = NbdClient } = {}) {
     super()
     this.#blockSize = blockSize
     this.#nbdInfos = nbdInfos
+    this.#ClientClass = ClientClass
     this.#dataMap = dataMap && this.#processDatamap(dataMap)
   }
 
@@ -111,7 +128,7 @@ export class NbdDisk extends RandomAccessDisk {
    * @returns {Promise<void>}
    */
   async init() {
-    this.#nbdClient = new NbdClient(this.#nbdInfos)
+    this.#nbdClient = new this.#ClientClass(this.#nbdInfos)
     await this.#nbdClient.connect()
     if (this.#dataMap === undefined) {
       this.#dataMap = this.#processDatamap(await this.#nbdClient.getMap())

@vates/nbd-client/NbdStdioClient.mjs

@@ -0,0 +1,157 @@
+import assert from 'node:assert'
+import { spawn } from 'node:child_process'
+import { pFromCallback } from 'promise-toolbox'
+import { createLogger } from '@xen-orchestra/log'
+import AbstractNbdClient from './AbstractNbdClient.mjs'
+
+const { warn } = createLogger('vates:nbd-client:stdio')
+
+// only the tail is kept: it's the part describing why the server died
+const STDERR_MAX_LENGTH = 4096
+
+/**
+ * NBD client talking to a server through its standard streams, like
+ * `nbdkit -s` or `qemu-nbd` in `--fd` mode: the queries are written to the
+ * server stdin and its answers are read from its stdout.
+ *
+ * The process is spawned on `connect()` and killed on `disconnect()`, and
+ * `reconnect()` (used by `readBlock()` retries) spawns a brand new one: the
+ * server must be restartable, and must serve the same content on each run.
+ *
+ * There is no TLS here: the transport is a pair of pipes, nothing to encrypt.
+ *
+ * @extends {AbstractNbdClient}
+ */
+export default class NbdStdioClient extends AbstractNbdClient {
+  #args
+  #command
+  #cwd
+  #env
+
+  /** @type {{ child: import('node:child_process').ChildProcess, closing: boolean, stderr: string }|undefined} */
+  #state
+
+  /**
+   * @param {object} settings
+   * @param {string} settings.command - the NBD server to run
+   * @param {ReadonlyArray<string>} [settings.args] - its arguments
+   * @param {string} [settings.exportname] - empty (the default export) for most single connection servers
+   * @param {NodeJS.ProcessEnv} [settings.env]
+   * @param {string} [settings.cwd]
+   * @param {object} [options] - see {@link AbstractNbdClient}
+   */
+  constructor({ command, args = [], exportname, env, cwd }, options) {
+    super({ exportname }, options)
+    assert.strictEqual(typeof command, 'string', 'command must be a string')
+    this.#command = command
+    this.#args = args
+    this.#env = env
+    this.#cwd = cwd
+  }
+
+  /**
+   * the tail of what the server wrote on stderr since it was spawned, useful to
+   * report why it failed
+   *
+   * @returns {string}
+   */
+  get stderr() {
+    return this.#state?.stderr ?? ''
+  }
+
+  /**
+   * the pid of the current server process, undefined if it's not running
+   *
+   * @returns {number|undefined}
+   */
+  get pid() {
+    return this.#state?.child.pid
+  }
+
+  async _openTransport() {
+    const child = spawn(this.#command, this.#args, {
+      cwd: this.#cwd,
+      env: this.#env,
+      // the protocol goes through stdin/stdout, stderr is only used for diagnostics
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    const state = { child, closing: false, stderr: '' }
+    this.#state = state
+
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', chunk => {
+      state.stderr = (state.stderr + chunk).slice(-STDERR_MAX_LENGTH)
+    })
+
+    // spawn failures (ENOENT, EACCES, ...) are reported asynchronously
+    await new Promise((resolve, reject) => {
+      const onError = error => {
+        error.command = this.#command
+        reject(error)
+      }
+      child.once('error', onError)
+      child.once('spawn', () => {
+        child.removeListener('error', onError)
+        // from now on, an error on the process itself (a failed kill for
+        // example) must not be thrown as an uncaught exception
+        child.on('error', error => warn('error on the nbd server process', { error, command: this.#command }))
+        resolve()
+      })
+    })
+
+    child.once('exit', (code, signal) => {
+      if (state.closing) {
+        // expected: disconnect() asked it to quit and is waiting for this
+        return
+      }
+      const error = new Error(`the nbd server process exited (code: ${code}, signal: ${signal})`)
+      error.code = 'NBD_SERVER_EXITED'
+      error.exitCode = code
+      error.signal = signal
+      error.command = this.#command
+      error.stderr = state.stderr
+      warn('the nbd server process exited unexpectedly', { error })
+      // make the pending and future reads fail with this error instead of
+      // waiting for the message timeout on a stream that will never answer
+      child.stdout.destroy(error)
+      child.stdin.destroy()
+    })
+
+    return { readable: child.stdout, writable: child.stdin, state }
+  }
+
+  async _closeTransport(transport, lastMessage) {
+    const { state } = transport
+    state.closing = true
+
+    // hand over NBD_CMD_DISC, then close stdin: that's how the server knows
+    // it can quit
+    await pFromCallback(cb => transport.writable.end(lastMessage, cb))
+
+    // don't let the server block on a write while we wait for its exit
+    transport.readable.resume()
+
+    const { child } = state
+    if (child.exitCode === null && child.signalCode === null) {
+      await new Promise(resolve => child.once('exit', () => resolve()))
+    }
+  }
+
+  _destroyTransport(transport) {
+    const { state } = transport
+    const { child } = state
+    // we're the one tearing it down: the exit that follows is expected, not a
+    // crash, and destroying the streams can be enough to make the server quit
+    state.closing = true
+    transport.readable.destroy()
+    transport.writable.destroy()
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGKILL')
+    }
+  }
+
+  // getMap() is not implemented: `nbdinfo` needs an URI or a server supporting
+  // systemd socket activation, and this one only speaks through its standard
+  // streams. Compute the map on the caller side and pass it explicitly (
+  // `new NbdDisk(infos, blockSize, { dataMap })`).
+}

@vates/nbd-client/NbdTcpClient.mjs

@@ -0,0 +1,106 @@
+import { Socket } from 'node:net'
+import { connect } from 'node:tls'
+import { spawn } from 'node:child_process'
+import AbstractNbdClient from './AbstractNbdClient.mjs'
+import { NBD_DEFAULT_PORT, NBD_OPT_STARTTLS } from './constants.mjs'
+
+/**
+ * NBD client talking to a server over TCP, optionally upgrading the connection
+ * to TLS during the handshake.
+ *
+ * @extends {AbstractNbdClient}
+ */
+export default class NbdTcpClient extends AbstractNbdClient {
+  #serverAddress
+  #serverCert
+  #serverPort
+
+  /**
+   * @param {object} settings
+   * @param {string} settings.address
+   * @param {number} [settings.port]
+   * @param {string} [settings.exportname]
+   * @param {string} [settings.cert] - PEM certificate, enables TLS when set
+   * @param {object} [options] - see {@link AbstractNbdClient}
+   */
+  constructor({ address, port = NBD_DEFAULT_PORT, exportname, cert }, options) {
+    super({ exportname }, options)
+    this.#serverAddress = address
+    this.#serverPort = port
+    this.#serverCert = cert
+  }
+
+  // mandatory , at least to start the handshake: the connection always starts
+  // unsecured, and is upgraded to TLS during the handshake
+  async _openTransport() {
+    const socket = new Socket()
+    await new Promise((resolve, reject) => {
+      socket.connect(this.#serverPort, this.#serverAddress)
+      socket.once('error', reject)
+      socket.once('connect', () => {
+        socket.removeListener('error', reject)
+        resolve()
+      })
+    })
+    return { readable: socket, writable: socket }
+  }
+
+  async _secureTransport(transport) {
+    if (this.#serverCert === undefined) {
+      return transport
+    }
+    await this._sendOption(transport, NBD_OPT_STARTTLS)
+    const secured = await new Promise((resolve, reject) => {
+      const socket = connect({
+        socket: transport.writable,
+        rejectUnauthorized: false,
+        cert: this.#serverCert,
+      })
+      socket.once('error', reject)
+      socket.once('secureConnect', () => {
+        socket.removeListener('error', reject)
+        resolve(socket)
+      })
+    })
+    return { readable: secured, writable: secured }
+  }
+
+  /**
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<{ offset: number, length: number, type: number }[]>}
+   */
+  /* async */ getMap(signal) {
+    return new Promise((resolve, reject) => {
+      const process = spawn('nbdinfo', [
+        '--json',
+        '--map',
+        `nbd://${this.#serverAddress}:${this.#serverPort}/${encodeURIComponent(this.exportName)}`,
+      ])
+      let text = ''
+      let errText = ''
+      process.stdout.on('data', data => (text += data))
+      process.stderr.on('data', data => (errText += data))
+      const onAbort = () => {
+        process.kill()
+        reject(signal.reason)
+      }
+      signal?.addEventListener('abort', onAbort, { once: true })
+      process.on('error', err => {
+        signal?.removeEventListener('abort', onAbort)
+        reject(err)
+      })
+      process.on('close', code => {
+        signal?.removeEventListener('abort', onAbort)
+        if (code !== 0) {
+          return reject(new Error(`Error during getMap (code: ${code}): ${errText}`))
+        }
+        try {
+          const json = JSON.parse(text)
+          resolve(json)
+        } catch (error) {
+          reject(new Error(`${error} ${text}`))
+        }
+      })
+    })
+  }
+}

@vates/nbd-client/README.md

@@ -14,9 +14,15 @@ npm install --save @vates/nbd-client
 
 ## Usage
 
-### `new NdbClient({address, exportname, secure = true, port = 10809})`
+This package provides a NBD client, in two flavors sharing the same protocol
+implementation (`AbstractNbdClient`): over the network, or over the standard
+streams of a NBD server run as a child process.
 
-create a new nbd client
+### `new NbdClient({address, exportname, cert, port = 10809})`
+
+Create a new nbd client connecting to a server over TCP.
+
+`NbdClient` is also exported as `NbdTcpClient`.
 
 ```js
 import NbdClient from '@vates/nbd-client'
@@ -31,6 +37,58 @@ const block = await client.readBlock(blockIndex, BlockSize)
 await client.disconnect()
 ```
 
+### `new NbdStdioClient({command, args, exportname})`
+
+Create a new nbd client talking to a server through its standard streams, like
+`nbdkit --single` or any server reading its queries on stdin and writing its
+answers on stdout.
+
+The process is spawned by `connect()` and stopped by `disconnect()`.
+
+```js
+import { NbdStdioClient } from '@vates/nbd-client'
+const client = new NbdStdioClient({
+  command: 'nbdkit',
+  args: ['--single', '--exit-with-parent', '--read-only', 'file', '/path/to/disk.raw'],
+  exportname: '', // optional, the default export of the server
+})
+
+await client.connect()
+const block = await client.readBlock(blockIndex, BlockSize)
+await client.disconnect()
+```
+
+There is no TLS here: the transport is a pair of pipes, there is nothing to
+encrypt.
+
+`readBlock()` retries on error, and a retry reconnects: with this client that
+means killing the server and spawning a new one, so the command must be
+restartable and must serve the same content on each run.
+
+`getMap()` is not implemented, since `nbdinfo` needs either an URI or a server
+supporting systemd socket activation: compute the map on the caller side and
+pass it explicitly, for example `new NbdDisk(infos, blockSize, { dataMap })`.
+
+The tail of the server stderr is available as `client.stderr` and attached to
+the errors raised when the server dies unexpectedly.
+
+### Writing another client
+
+Subclass `AbstractNbdClient` and implement the transport:
+
+- `_openTransport()`: **required**, returns `{ readable, writable }`, called on
+  every (re)connection.
+- `_secureTransport(transport)`: optional, called during the handshake, the only
+  place where the transport can be upgraded (`NBD_OPT_STARTTLS`).
+- `_closeTransport(transport, lastMessage)`: optional, must hand over
+  `lastMessage` (`NBD_CMD_DISC`) before closing.
+- `_destroyTransport(transport)`: optional, forceful cleanup, must not throw.
+- `getMap(signal)`: optional, the base implementation rejects with the code
+  `NBD_MAP_UNSUPPORTED`.
+
+Any extra property set on the transport object is passed back to
+`_closeTransport()` and `_destroyTransport()`.
+
 ## Contributions
 
 Contributions are _very_ welcomed, either on the documentation or on

@vates/nbd-client/index.mjs

@@ -1,408 +1,6 @@
-import assert from 'node:assert'
-import { Socket } from 'node:net'
-import { connect } from 'node:tls'
-import { pRetry, pDelay, pTimeout, pFromCallback } from 'promise-toolbox'
-import { readChunkStrict } from '@vates/read-chunk'
-import { createLogger } from '@xen-orchestra/log'
-import {
-  INIT_PASSWD,
-  NBD_CMD_READ,
-  NBD_DEFAULT_BLOCK_SIZE,
-  NBD_DEFAULT_PORT,
-  NBD_FLAG_FIXED_NEWSTYLE,
-  NBD_FLAG_HAS_FLAGS,
-  NBD_OPT_EXPORT_NAME,
-  NBD_OPT_REPLY_MAGIC,
-  NBD_OPT_STARTTLS,
-  NBD_REPLY_ACK,
-  NBD_REPLY_MAGIC,
-  NBD_REQUEST_MAGIC,
-  OPTS_MAGIC,
-  NBD_CMD_DISC,
-} from './constants.mjs'
-import { spawn } from 'node:child_process'
+// the TCP client is the historical default export of this package
+export { default } from './NbdTcpClient.mjs'
 
-const { warn } = createLogger('vates:nbd-client')
-
-// documentation is here : https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
-
-export default class NbdClient {
-  #serverAddress
-  #serverCert
-  #serverPort
-  #serverSocket
-
-  #exportName
-  #exportSize
-
-  #waitBeforeReconnect
-  #readBlockRetries
-  #reconnectRetry
-  #connectTimeout
-  #messageTimeout
-
-  // AFAIK, there is no guaranty the server answers in the same order as the queries
-  // so we handle a backlog of command waiting for response and handle concurrency manually
-
-  #waitingForResponse // there is already a listener waiting for a response
-  #nextCommandQueryId = BigInt(0)
-  #commandQueryBacklog // map of command waiting for a response queryId => { size/*in byte*/, resolve, reject}
-  #connected = false
-
-  #reconnectingPromise
-  constructor(
-    { address, port = NBD_DEFAULT_PORT, exportname, cert },
-    {
-      connectTimeout = 6e4,
-      messageTimeout = 6e4,
-      waitBeforeReconnect = 1e3,
-      readBlockRetries = 5,
-      reconnectRetry = 5,
-    } = {}
-  ) {
-    this.#serverAddress = address
-    this.#serverPort = port
-    this.#exportName = exportname
-    this.#serverCert = cert
-    this.#waitBeforeReconnect = waitBeforeReconnect
-    this.#readBlockRetries = readBlockRetries
-    this.#reconnectRetry = reconnectRetry
-    this.#connectTimeout = connectTimeout
-    this.#messageTimeout = messageTimeout
-  }
-
-  get exportSize() {
-    return this.#exportSize
-  }
-
-  async #tlsConnect() {
-    return new Promise((resolve, reject) => {
-      this.#serverSocket = connect({
-        socket: this.#serverSocket,
-        rejectUnauthorized: false,
-        cert: this.#serverCert,
-      })
-      this.#serverSocket.once('error', reject)
-      this.#serverSocket.once('secureConnect', () => {
-        this.#serverSocket.removeListener('error', reject)
-        resolve()
-      })
-    })
-  }
-
-  // mandatory , at least to start the handshake
-  async #unsecureConnect() {
-    this.#serverSocket = new Socket()
-    return new Promise((resolve, reject) => {
-      this.#serverSocket.connect(this.#serverPort, this.#serverAddress)
-      this.#serverSocket.once('error', reject)
-      this.#serverSocket.once('connect', () => {
-        this.#serverSocket.removeListener('error', reject)
-        resolve()
-      })
-    })
-  }
-
-  async #connect() {
-    // first we connect to the server without tls, and then we upgrade the connection
-    // to tls during the handshake
-    await this.#unsecureConnect()
-    await this.#handshake()
-    this.#connected = true
-    // reset internal state if we reconnected a nbd client
-    this.#commandQueryBacklog = new Map()
-    this.#waitingForResponse = false
-  }
-  async connect() {
-    return pTimeout.call(this.#connect(), this.#connectTimeout)
-  }
-
-  async disconnect() {
-    if (!this.#connected) {
-      return
-    }
-    this.#connected = false
-    const socket = this.#serverSocket
-
-    const queryId = this.#nextCommandQueryId
-    this.#nextCommandQueryId++
-
-    const buffer = Buffer.alloc(28)
-    buffer.writeInt32BE(NBD_REQUEST_MAGIC, 0) // it is a nbd request
-    buffer.writeInt16BE(0, 4) // no command flags for a disconnect
-    buffer.writeInt16BE(NBD_CMD_DISC, 6) // we want to disconnect from nbd server
-    buffer.writeBigUInt64BE(queryId, 8)
-    buffer.writeBigUInt64BE(0n, 16)
-    buffer.writeInt32BE(0, 24)
-    const promise = pFromCallback(cb => {
-      socket.end(buffer, 'utf8', cb)
-    })
-    try {
-      await pTimeout.call(promise, this.#messageTimeout)
-    } catch (error) {
-      socket.destroy()
-    }
-    this.#serverSocket = undefined
-    this.#connected = false
-  }
-
-  #clearReconnectPromise = () => {
-    this.#reconnectingPromise = undefined
-  }
-
-  async #reconnect() {
-    await this.disconnect().catch(() => {})
-    await pDelay(this.#waitBeforeReconnect) // need to let the xapi clean things on its side
-    await this.connect()
-  }
-
-  async reconnect() {
-    // we need to ensure reconnections do not occur in parallel
-    if (this.#reconnectingPromise === undefined) {
-      this.#reconnectingPromise = pRetry(() => this.#reconnect(), {
-        tries: this.#reconnectRetry,
-      })
-      this.#reconnectingPromise.then(this.#clearReconnectPromise, this.#clearReconnectPromise)
-    }
-
-    return this.#reconnectingPromise
-  }
-
-  // we can use individual read/write from the socket here since there is no concurrency
-  async #sendOption(option, buffer = Buffer.alloc(0)) {
-    await this.#write(OPTS_MAGIC)
-    await this.#writeInt32(option)
-    await this.#writeInt32(buffer.length)
-    await this.#write(buffer)
-    assert.strictEqual(await this.#readInt64(), NBD_OPT_REPLY_MAGIC) // magic number everywhere
-    assert.strictEqual(await this.#readInt32(), option) // the option passed
-    assert.strictEqual(await this.#readInt32(), NBD_REPLY_ACK) // ACK
-    const length = await this.#readInt32()
-    assert.strictEqual(length, 0) // length
-  }
-
-  // we can use individual read/write from the socket here since there is only one handshake at once, no concurrency
-  async #handshake() {
-    assert((await this.#read(8)).equals(INIT_PASSWD))
-    assert((await this.#read(8)).equals(OPTS_MAGIC))
-    const flagsBuffer = await this.#read(2)
-    const flags = flagsBuffer.readInt16BE(0)
-    assert.strictEqual(flags & NBD_FLAG_FIXED_NEWSTYLE, NBD_FLAG_FIXED_NEWSTYLE) // only FIXED_NEWSTYLE one is supported from the server options
-    await this.#writeInt32(NBD_FLAG_FIXED_NEWSTYLE) // client also support  NBD_FLAG_C_FIXED_NEWSTYLE
-
-    if (this.#serverCert !== undefined) {
-      // upgrade socket to TLS if needed
-      await this.#sendOption(NBD_OPT_STARTTLS)
-      await this.#tlsConnect()
-    }
-
-    // send export name we want to access.
-    // it's implicitly closing the negotiation phase.
-    await this.#write(OPTS_MAGIC)
-    await this.#writeInt32(NBD_OPT_EXPORT_NAME)
-    const exportNameBuffer = Buffer.from(this.#exportName)
-    await this.#writeInt32(exportNameBuffer.length)
-    await this.#write(exportNameBuffer)
-
-    // 8 (export size ) + 2 (flags) + 124 zero = 134
-    // must read all to ensure nothing stays in the  buffer
-    const answer = await this.#read(134)
-    this.#exportSize = answer.readBigUInt64BE(0)
-    const transmissionFlags = answer.readInt16BE(8)
-    assert.strictEqual(transmissionFlags & NBD_FLAG_HAS_FLAGS, NBD_FLAG_HAS_FLAGS, 'NBD_FLAG_HAS_FLAGS') // must always be 1 by the norm
-
-    // note : xapi server always send NBD_FLAG_READ_ONLY (3) as a flag
-  }
-
-  #read(length) {
-    const promise = readChunkStrict(this.#serverSocket, length)
-    return pTimeout.call(promise, this.#messageTimeout)
-  }
-
-  #write(buffer) {
-    let timeout
-    const messageTimeout = this.#messageTimeout
-    const socket = this.#serverSocket
-    return Promise.race([
-      new Promise((resolve, reject) => {
-        timeout = setTimeout(() => {
-          reject(new Error('timeout'))
-        }, messageTimeout)
-      }),
-      new Promise(resolve =>
-        socket.write(buffer, () => {
-          clearTimeout(timeout)
-          resolve()
-        })
-      ),
-    ])
-  }
-
-  async #readInt32() {
-    const buffer = await this.#read(4)
-    return buffer.readInt32BE(0)
-  }
-
-  async #readInt64() {
-    const buffer = await this.#read(8)
-    return buffer.readBigUInt64BE(0)
-  }
-
-  #writeInt32(int) {
-    const buffer = Buffer.alloc(4)
-    buffer.writeInt32BE(int)
-    return this.#write(buffer)
-  }
-
-  // when one read fail ,stop everything
-  async #rejectAll(error) {
-    this.#commandQueryBacklog.forEach(({ reject }) => {
-      reject(error)
-    })
-  }
-
-  async #readBlockResponse() {
-    // ensure at most one read occur in parallel
-    if (this.#waitingForResponse) {
-      return
-    }
-    try {
-      this.#waitingForResponse = true
-      const buffer = await this.#read(16)
-      const magic = buffer.readInt32BE(0)
-
-      if (magic !== NBD_REPLY_MAGIC) {
-        throw new Error(`magic number for block answer is wrong : ${magic} ${NBD_REPLY_MAGIC}`)
-      }
-
-      const error = buffer.readInt32BE(4)
-      if (error !== 0) {
-        // @todo use error code from constants.mjs
-        throw new Error(`GOT ERROR CODE  : ${error}`)
-      }
-
-      const blockQueryId = buffer.readBigUInt64BE(8)
-      const query = this.#commandQueryBacklog.get(blockQueryId)
-      if (!query) {
-        throw new Error(` no query associated with id ${blockQueryId}`)
-      }
-      this.#commandQueryBacklog.delete(blockQueryId)
-      const data = await this.#read(query.size)
-      query.resolve(data)
-      this.#waitingForResponse = false
-      if (this.#commandQueryBacklog.size > 0) {
-        // it doesn't throw directly but will throw all relevant promise on failure
-        this.#readBlockResponse()
-      }
-    } catch (error) {
-      // reject all the promises
-      // we don't need to call readBlockResponse on failure
-      // since we will empty the backlog
-      await this.#rejectAll(error)
-    }
-  }
-
-  async #readBlock(index, size) {
-    // we don't want to add anything in backlog while reconnecting
-    if (this.#reconnectingPromise) {
-      await this.#reconnectingPromise
-    }
-
-    const queryId = this.#nextCommandQueryId
-    this.#nextCommandQueryId++
-
-    // create and send  command at once to ensure there is no concurrency issue
-    const buffer = Buffer.alloc(28)
-    buffer.writeInt32BE(NBD_REQUEST_MAGIC, 0) // it is a nbd request
-    buffer.writeInt16BE(0, 4) // no command flags for a simple block read
-    buffer.writeInt16BE(NBD_CMD_READ, 6) // we want to read a data block
-    buffer.writeBigUInt64BE(queryId, 8)
-    // byte offset in the raw disk
-    const offset = BigInt(index) * BigInt(size)
-    const remaining = this.#exportSize - offset
-    if (remaining < BigInt(size)) {
-      size = Number(remaining)
-    }
-
-    buffer.writeBigUInt64BE(offset, 16)
-    buffer.writeInt32BE(size, 24)
-
-    return new Promise((resolve, reject) => {
-      function decoratedReject(error) {
-        error.index = index
-        error.size = size
-        reject(error)
-      }
-
-      // this will handle one block response, but it can be another block
-      // since server does not guaranty to handle query in order
-      this.#commandQueryBacklog.set(queryId, {
-        size,
-        resolve,
-        reject: decoratedReject,
-      })
-      // really send the command to the server
-      this.#write(buffer).catch(decoratedReject)
-
-      // #readBlockResponse never throws directly
-      // but if it fails it will reject all the promises in the backlog
-      this.#readBlockResponse()
-    })
-  }
-
-  async readBlock(index, size = NBD_DEFAULT_BLOCK_SIZE) {
-    return pRetry(() => this.#readBlock(index, size), {
-      tries: this.#readBlockRetries,
-      when: error => error.code !== 'ERR_ABORTED',
-      onRetry: async err => {
-        warn('will retry reading block ', index, err)
-        await this.reconnect()
-      },
-    })
-  }
-
-  /**
-   *  returns the map of the file with holes, zeros and data, useful to handle efficiently sparse source
-   * to implement this internally: use structure response if the server supports it, and then ask for BLOCK_STATUS   *
-   *
-   * @returns {Promise<{ offset: number, length: number, type: number }[]>}
-   * A promise that resolves to an array where each object represents a segment:
-   * - `offset` — The byte offset from the start.
-   * - `length` — The size of the segment in bytes.
-   * - `type` — A numeric code indicating the segment type ( 0 means data).
-   */
-  /* async */ getMap(signal) {
-    return new Promise((resolve, reject) => {
-      const process = spawn('nbdinfo', [
-        '--json',
-        '--map',
-        `nbd://${this.#serverAddress}:${this.#serverPort}/${encodeURIComponent(this.#exportName)}`,
-      ])
-      let text = ''
-      let errText = ''
-      process.stdout.on('data', data => (text += data))
-      process.stderr.on('data', data => (errText += data))
-      const onAbort = () => {
-        process.kill()
-        reject(signal.reason)
-      }
-      signal?.addEventListener('abort', onAbort, { once: true })
-      process.on('error', err => {
-        signal?.removeEventListener('abort', onAbort)
-        reject(err)
-      })
-      process.on('close', code => {
-        signal?.removeEventListener('abort', onAbort)
-        if (code !== 0) {
-          return reject(new Error(`Error during getMap (code: ${code}): ${errText}`))
-        }
-        try {
-          const json = JSON.parse(text)
-          resolve(json)
-        } catch (error) {
-          reject(new Error(`${error} ${text}`))
-        }
-      })
-    })
-  }
-}
+export { default as AbstractNbdClient } from './AbstractNbdClient.mjs'
+export { default as NbdStdioClient } from './NbdStdioClient.mjs'
+export { default as NbdTcpClient } from './NbdTcpClient.mjs'

@vates/nbd-client/multi.mjs

@@ -7,6 +7,7 @@ const { warn } = createLogger('vates:nbd-client:multi')
 export default class MultiNbdClient {
   #clients = []
   #nbdConcurrency
+  #nextClient = 0
   #options
   #readAhead
   #settings
@@ -97,8 +98,31 @@ export default class MultiNbdClient {
    * @returns {Promise<Buffer>}
    */
   async readBlock(index, size = NBD_DEFAULT_BLOCK_SIZE) {
-    const clientId = index % this.#clients.length
-    return this.#clients[clientId].readBlock(index, size)
+    const clientId = this.#nextClient++ % this.#clients.length
+    const client = this.#clients[clientId]
+    try {
+      return await client.readBlock(index, size)
+    } catch (err) {
+      // client.readBlock() already exhausted its own retries/reconnects: this connection is dead.
+      // Evict it so future reads stop being routed to it, and retry this read on a surviving
+      // client, since the data is usually still reachable through the others.
+      this.#evict(client)
+      if (this.#clients.length === 0) {
+        throw err
+      }
+      warn(`evicted a dead nbd client, retrying block ${index} on a remaining client`, { err })
+      return this.readBlock(index, size)
+    }
+  }
+
+  // no-op if `client` was already evicted by a concurrent failed read on the same client
+  #evict(client) {
+    const i = this.#clients.indexOf(client)
+    if (i === -1) {
+      return
+    }
+    this.#clients.splice(i, 1)
+    client.disconnect().catch(() => {})
   }
 
   /**

@vates/nbd-client/multi.test.mjs

@@ -0,0 +1,130 @@
+import { describe, it, mock } from 'node:test'
+import assert from 'node:assert'
+
+// MultiNbdClient instantiates NbdClient itself (`import NbdClient from './index.mjs'`), so the
+// only way to control individual connections from a unit test is to replace that module with a
+// fake before importing multi.mjs.
+const created = []
+class FakeNbdClient {
+  constructor(nbdInfo) {
+    this.nbdInfo = nbdInfo
+    this.disconnected = false
+    // overridden per-test after connect() to script this instance's behavior
+    this.readBlock = async () => {
+      throw new Error('readBlock not configured for this fake client')
+    }
+    created.push(this)
+  }
+
+  async connect() {}
+
+  async disconnect() {
+    this.disconnected = true
+  }
+
+  async getMap() {
+    return []
+  }
+}
+
+mock.module('./index.mjs', {
+  defaultExport: FakeNbdClient,
+})
+
+const { default: MultiNbdClient } = await import('./multi.mjs')
+
+// a single settings entry is enough: connect() reuses candidates across concurrent slots, so
+// nbdConcurrency still yields that many distinct FakeNbdClient instances
+async function connectWithFakes(nbdConcurrency) {
+  created.length = 0
+  const client = new MultiNbdClient({ address: 'fake-host' }, { nbdConcurrency })
+  await client.connect()
+  return { client, fakes: created.slice() }
+}
+
+describe('MultiNbdClient.readBlock eviction', () => {
+  it('evicts a client whose readBlock rejects and retries on a surviving client', async () => {
+    const { client, fakes } = await connectWithFakes(2)
+    const [dead, alive] = fakes
+    dead.readBlock = async () => {
+      throw new Error('connection is dead')
+    }
+    alive.readBlock = async index => Buffer.from([index])
+
+    // index 0 initially routes to `dead` (0 % 2 === 0)
+    const data = await client.readBlock(0)
+
+    assert.deepStrictEqual(data, Buffer.from([0]))
+    assert.strictEqual(dead.disconnected, true, 'the dead client should have been disconnected')
+
+    // future reads must no longer be routed to the evicted client: with only `alive` left,
+    // every index should now succeed through it
+    alive.readBlock = async index => Buffer.from([index])
+    const data2 = await client.readBlock(1)
+    assert.deepStrictEqual(data2, Buffer.from([1]))
+  })
+
+  it('rejects once every client has been evicted, instead of retrying forever', async () => {
+    const { client, fakes } = await connectWithFakes(2)
+    const boom = new Error('connection is dead')
+    for (const fake of fakes) {
+      fake.readBlock = async () => {
+        throw boom
+      }
+    }
+
+    await assert.rejects(() => client.readBlock(0), boom)
+    assert.ok(
+      fakes.every(fake => fake.disconnected),
+      'every client should have been evicted (and disconnected) before giving up'
+    )
+  })
+
+  it('evicting the same dead client from concurrent failed reads is idempotent', async () => {
+    const { client, fakes } = await connectWithFakes(2)
+    const [dead, alive] = fakes
+    dead.readBlock = async () => {
+      throw new Error('connection is dead')
+    }
+    alive.readBlock = async index => Buffer.from([index])
+
+    let disconnectCalls = 0
+    dead.disconnect = async () => {
+      disconnectCalls++
+      dead.disconnected = true
+    }
+
+    // routing is round-robin by call order (0, 1, 0) over a 2-client pool: the 1st and 3rd
+    // calls both land on `dead` before either failure has been handled, so they race to evict
+    // the same client. The exact interleaving isn't guaranteed, only that eviction is safe
+    // either way and every read still completes.
+    const [data0, data1, data2] = await Promise.all([client.readBlock(10), client.readBlock(11), client.readBlock(12)])
+
+    assert.deepStrictEqual(data0, Buffer.from([10]))
+    assert.deepStrictEqual(data1, Buffer.from([11]))
+    assert.deepStrictEqual(data2, Buffer.from([12]))
+    assert.strictEqual(disconnectCalls, 1, 'the dead client must only be evicted/disconnected once')
+  })
+})
+
+describe('MultiNbdClient.readBlock routing', () => {
+  it('distributes reads round-robin by call order, not by index residue', async () => {
+    const { client, fakes } = await connectWithFakes(4)
+    const readsPerClient = fakes.map(() => 0)
+    fakes.forEach((fake, i) => {
+      fake.readBlock = async index => {
+        readsPerClient[i]++
+        return Buffer.from([index])
+      }
+    })
+
+    // a CBT-style changed-block set striding by exactly `nbdConcurrency`: under the old
+    // `index % clients.length` routing this would collapse entirely onto a single client
+    const stridedIndexes = Array.from({ length: 20 }, (_, i) => i * 4)
+    for (const index of stridedIndexes) {
+      await client.readBlock(index)
+    }
+
+    assert.deepStrictEqual(readsPerClient, [5, 5, 5, 5])
+  })
+})

@vates/nbd-client/package.json

@@ -13,7 +13,7 @@
     "url": "https://vates.fr"
   },
   "license": "ISC",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "engines": {
     "node": ">=14.0"
   },
@@ -21,11 +21,11 @@
   "dependencies": {
     "@vates/async-each": "^1.0.3",
     "@vates/read-chunk": "^1.2.1",
-    "@xen-orchestra/async-map": "^0.1.3",
+    "@xen-orchestra/async-map": "^0.1.5",
     "@xen-orchestra/disk-transform": "^1.3.3",
     "@xen-orchestra/log": "^0.7.2",
     "promise-toolbox": "^0.21.0",
-    "xen-api": "^4.8.0"
+    "xen-api": "^5.0.1"
   },
   "devDependencies": {
     "tap": "^18.7.0",
@@ -33,6 +33,7 @@
   },
   "scripts": {
     "postversion": "npm publish --access public",
-    "test-integration": "tap --allow-incomplete-coverage"
+    "test": "node --experimental-test-module-mocks --test",
+    "test-integration": "tap --allow-incomplete-coverage tests/*.integ.mjs"
   }
 }

@vates/nbd-client/tests/fake-nbd-server.mjs

@@ -0,0 +1,132 @@
+import assert from 'node:assert'
+import { pFromCallback } from 'promise-toolbox'
+import { readChunk, readChunkStrict } from '@vates/read-chunk'
+import {
+  INIT_PASSWD,
+  NBD_CMD_DISC,
+  NBD_CMD_READ,
+  NBD_FLAG_FIXED_NEWSTYLE,
+  NBD_FLAG_HAS_FLAGS,
+  NBD_FLAG_READ_ONLY,
+  NBD_OPT_EXPORT_NAME,
+  NBD_OPT_REPLY_MAGIC,
+  NBD_REPLY_ACK,
+  NBD_REPLY_MAGIC,
+  NBD_REQUEST_MAGIC,
+  OPTS_MAGIC,
+} from '../constants.mjs'
+
+const NBD_EINVAL = 22
+
+/**
+ * Minimal read-only newstyle NBD server, used by the tests only.
+ *
+ * It is transport agnostic on purpose: the unit tests drive it through two
+ * in-memory `PassThrough`, the integration tests through the standard streams
+ * of a real process.
+ *
+ * @param {object} options
+ * @param {import('node:stream').Readable} options.readable - where the client queries are read from
+ * @param {import('node:stream').Writable} options.writable - where the answers are written to
+ * @param {Buffer} options.data - the content of the export
+ * @param {string} [options.exportName] - the export name the client must ask for
+ * @param {boolean} [options.answerInReverse] - answer by pairs, in reverse order, to check the client handles out of order answers
+ * @param {(request: {offset: bigint, length: number, index: number}) => number} [options.errorCode] - non zero to answer an error to this read
+ * @returns {Promise<void>} resolves when the client disconnected or closed the connection
+ */
+export async function serveNbd({ readable, writable, data, exportName = '', answerInReverse = false, errorCode }) {
+  const write = buffer => pFromCallback(cb => writable.write(buffer, cb))
+
+  // handshake: server flags
+  await write(INIT_PASSWD)
+  await write(OPTS_MAGIC)
+  const serverFlags = Buffer.alloc(2)
+  serverFlags.writeInt16BE(NBD_FLAG_FIXED_NEWSTYLE)
+  await write(serverFlags)
+
+  // client flags
+  await readChunkStrict(readable, 4)
+
+  // options, until the client selects an export
+  let selected = false
+  do {
+    assert.ok((await readChunkStrict(readable, 8)).equals(OPTS_MAGIC), 'option magic')
+    const option = (await readChunkStrict(readable, 4)).readInt32BE(0)
+    const length = (await readChunkStrict(readable, 4)).readInt32BE(0)
+    const payload = length > 0 ? await readChunkStrict(readable, length) : Buffer.alloc(0)
+
+    if (option === NBD_OPT_EXPORT_NAME) {
+      assert.strictEqual(payload.toString(), exportName, 'export name')
+      // 8 (size) + 2 (transmission flags) + 124 zeroes
+      const answer = Buffer.alloc(134)
+      answer.writeBigUInt64BE(BigInt(data.length), 0)
+      answer.writeInt16BE(NBD_FLAG_HAS_FLAGS | NBD_FLAG_READ_ONLY, 8)
+      await write(answer)
+      selected = true
+    } else {
+      // ack everything else
+      const answer = Buffer.alloc(20)
+      answer.writeBigUInt64BE(NBD_OPT_REPLY_MAGIC, 0)
+      answer.writeInt32BE(option, 8)
+      answer.writeInt32BE(NBD_REPLY_ACK, 12)
+      answer.writeInt32BE(0, 16)
+      await write(answer)
+    }
+  } while (!selected)
+
+  // transmission
+  let index = 0
+  let pending = []
+
+  const answer = async ({ handle, offset, length, index }, forcedCode) => {
+    const code = forcedCode ?? errorCode?.({ handle, offset, length, index }) ?? 0
+    const header = Buffer.alloc(16)
+    header.writeInt32BE(NBD_REPLY_MAGIC, 0)
+    header.writeInt32BE(code, 4)
+    header.writeBigUInt64BE(handle, 8)
+    await write(header)
+    if (code === 0) {
+      await write(data.subarray(Number(offset), Number(offset) + length))
+    }
+  }
+
+  const flush = async () => {
+    const requests = pending
+    pending = []
+    for (const request of requests.reverse()) {
+      await answer(request)
+    }
+  }
+
+  while (true) {
+    const request = await readChunk(readable, 28)
+    if (request === null || request.length < 28) {
+      // the client closed the connection without a NBD_CMD_DISC
+      break
+    }
+    assert.strictEqual(request.readInt32BE(0), NBD_REQUEST_MAGIC, 'request magic')
+    const type = request.readInt16BE(6)
+    const handle = request.readBigUInt64BE(8)
+
+    if (type === NBD_CMD_DISC) {
+      await flush()
+      break
+    }
+
+    if (type !== NBD_CMD_READ) {
+      await answer({ handle, offset: 0n, length: 0, index: index++ }, NBD_EINVAL)
+      continue
+    }
+
+    const read = {
+      handle,
+      offset: request.readBigUInt64BE(16),
+      length: request.readInt32BE(24),
+      index: index++,
+    }
+    pending.push(read)
+    if (!answerInReverse || pending.length === 2) {
+      await flush()
+    }
+  }
+}

@vates/nbd-client/tests/nbdclient.integ.mjs

@@ -153,7 +153,13 @@ CYu1Xn/FVPx1HoRgWc7E8wFhDcA/P3SJtfIQWHB9FzSaBflKGR4t8WCE2eE8+cTB
       nbdServer = await spawnNbdKit(path)
     }
   }
-  assert.rejects(() => client.readBlock(100, CHUNK_SIZE))
+  // reading past the end of the export must reject: a single client so the failure isn't
+  // multiplied by nbdConcurrency evicting and retrying on every other (equally healthy, equally
+  // unable to satisfy this out-of-range request) client
+  const singleClient = new MultiNbdClient(connectionSettings, { nbdConcurrency: 1, readAhead: 2 })
+  await singleClient.connect()
+  await assert.rejects(() => singleClient.readBlock(100, CHUNK_SIZE))
+  await singleClient.disconnect()
 
   await client.disconnect()
   // double disconnection shouldn't pose any problem

@vates/nbd-client/tests/nbdstdio.integ.mjs

@@ -0,0 +1,114 @@
+import assert from 'node:assert'
+import fs from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { pFromCallback } from 'promise-toolbox'
+import { test } from 'tap'
+import tmp from 'tmp'
+
+import NbdStdioClient from '../NbdStdioClient.mjs'
+
+// nbdkit in single connection mode: the real thing this client targets
+const NBDKIT = path => ({
+  command: 'nbdkit',
+  args: ['--single', '--exit-with-parent', '--read-only', 'file', path],
+})
+
+// a tiny NBD server we can ask to die in the middle of the transfer, which
+// nbdkit won't do
+const FLAKY_SERVER = fileURLToPath(new URL('./stdio-nbd-server.mjs', import.meta.url))
+
+const CHUNK_SIZE = 64 * 1024
+const FILE_SIZE = CHUNK_SIZE * 8 + 1232 // non aligned file size
+
+async function createTempFile(size) {
+  const tmpPath = await pFromCallback(cb => tmp.file(cb))
+  const data = Buffer.alloc(size)
+  for (let i = 0; i < size; i += 4) {
+    data.writeUInt32BE(i, i)
+  }
+  await fs.writeFile(tmpPath, data)
+  return tmpPath
+}
+
+function checkBlock(tap, block, index) {
+  tap.equal(block.length, Math.min(CHUNK_SIZE, FILE_SIZE - index * CHUNK_SIZE), `block ${index} length`)
+  let ok = true
+  for (let i = 0; i < block.length; i += 4) {
+    ok = ok && block.readUInt32BE(i) === index * CHUNK_SIZE + i
+  }
+  tap.ok(ok, `block ${index} content`)
+}
+
+async function readWholeExport(tap, client) {
+  for (let index = 0; index < Math.ceil(FILE_SIZE / CHUNK_SIZE); index++) {
+    checkBlock(tap, await client.readBlock(index, CHUNK_SIZE), index)
+  }
+}
+
+const isAlive = pid => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return false
+  }
+}
+
+test('it reads an export served by nbdkit on stdin/stdout', async tap => {
+  const path = await createTempFile(FILE_SIZE)
+  const client = new NbdStdioClient(NBDKIT(path))
+
+  await client.connect()
+  const { pid } = client
+  tap.equal(client.exportSize, BigInt(FILE_SIZE))
+
+  await readWholeExport(tap, client)
+
+  await client.disconnect()
+  tap.notOk(isAlive(pid), 'the server process is stopped after disconnect')
+
+  // double disconnection shouldn't pose any problem
+  await client.disconnect()
+  await fs.unlink(path)
+})
+
+test('it fails when the server does not serve the requested export', async tap => {
+  const path = await createTempFile(CHUNK_SIZE)
+  // the file plugin of nbdkit ignores the export name, so use our own server here
+  const client = new NbdStdioClient(
+    {
+      command: process.execPath,
+      args: [FLAKY_SERVER, path, '--export-name=MY_SECRET_EXPORT'],
+      exportname: 'NOPE',
+    },
+    { connectTimeout: 5e3 }
+  )
+  await assert.rejects(client.connect())
+  tap.match(client.stderr, /NOPE/, 'the stderr of the server is captured')
+  await fs.unlink(path)
+})
+
+test('it recovers from a server dying in the middle of the transfer', async tap => {
+  const path = await createTempFile(FILE_SIZE)
+  const client = new NbdStdioClient(
+    { command: process.execPath, args: [FLAKY_SERVER, path, '--die-after=3'] },
+    { waitBeforeReconnect: 100 }
+  )
+
+  await client.connect()
+  await readWholeExport(tap, client)
+  await client.disconnect()
+  await fs.unlink(path)
+})
+
+test('it fails cleanly when the server cannot be spawned', async () => {
+  const client = new NbdStdioClient({ command: '/does/not/exist' })
+  await assert.rejects(client.connect(), ({ code, command }) => code === 'ENOENT' && command === '/does/not/exist')
+  // nothing to disconnect from
+  await client.disconnect()
+})
+
+test('it does not implement getMap', async () => {
+  const client = new NbdStdioClient({ command: 'nbdkit' })
+  await assert.rejects(client.getMap(), ({ code }) => code === 'NBD_MAP_UNSUPPORTED')
+})

@vates/nbd-client/tests/stdio-nbd-server.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// Read-only NBD server serving a file through its standard streams, à la
+// `nbdkit -s`. Used by nbdstdio.integ.mjs, since nbdkit is not necessarily
+// installed on the test machine.
+//
+// Usage: stdio-nbd-server.mjs <file> [--export-name=NAME] [--die-after=N]
+//
+// --die-after=N exits with a failure after having answered N read requests, to
+// exercise the reconnection path of the client.
+
+import fs from 'node:fs/promises'
+import { serveNbd } from './fake-nbd-server.mjs'
+
+const args = process.argv.slice(2)
+const path = args.find(arg => !arg.startsWith('--'))
+if (path === undefined) {
+  console.error('usage: stdio-nbd-server.mjs <file> [--export-name=NAME] [--die-after=N]')
+  process.exit(64)
+}
+
+const getOption = (name, defaultValue) => {
+  const prefix = `--${name}=`
+  const arg = args.find(arg => arg.startsWith(prefix))
+  return arg === undefined ? defaultValue : arg.slice(prefix.length)
+}
+
+const exportName = getOption('export-name', '')
+const dieAfter = Number(getOption('die-after', Infinity))
+
+const data = await fs.readFile(path)
+
+let answered = 0
+
+try {
+  await serveNbd({
+    readable: process.stdin,
+    writable: process.stdout,
+    data,
+    exportName,
+    errorCode: () => {
+      if (++answered > dieAfter) {
+        console.error(`stdio-nbd-server: dying after ${dieAfter} read(s)`)
+        process.exit(1)
+      }
+      return 0
+    },
+  })
+} catch (error) {
+  console.error('stdio-nbd-server:', error)
+  process.exit(1)
+}

@vates/node-vsphere-soap/lib/_parseFault.mjs

@@ -0,0 +1,102 @@
+const XML_ENTITIES = {
+  '&': '&',
+  ''': "'",
+  '>': '>',
+  '&lt;': '<',
+  '&quot;': '"',
+}
+
+const unescapeXml = text => text.replace(/&(?:amp|apos|gt|lt|quot);/g, entity => XML_ENTITIES[entity])
+
+// node-soap wraps text nodes either as a plain string or as `{ $value }` depending on
+// whether the element carries attributes
+const valueOf = node => {
+  if (typeof node === 'string') {
+    return node
+  }
+  if (node !== null && typeof node === 'object' && typeof node.$value === 'string') {
+    return node.$value
+  }
+}
+
+const faultTypeOfElementName = name => name.replace(/^.*:/, '').replace(/Fault$/, '')
+
+// SOAP 1.1 requires the children of `Fault` to be unqualified, and that is what ESXi and vCenter
+// send, but the raw body is only read when node-soap failed to parse the response: it can then be
+// anything, e.g. an error emitted by a reverse proxy in front of vCenter. Hence the tolerance to a
+// namespace prefix and to attributes on the element
+const textOfElement = name =>
+  new RegExp(`<(?:[\\w.-]+:)?${name}(?:\\s[^>]*)?>([\\s\\S]*?)</(?:[\\w.-]+:)?${name}>`, 'i')
+
+const FAULTCODE_RE = textOfElement('faultcode')
+const FAULTSTRING_RE = textOfElement('faultstring')
+const LOCALIZED_MESSAGE_RE = textOfElement('localizedMessage')
+const DETAIL_CHILD_RE = /<(?:[\w.-]+:)?detail(?:\s[^>]*)?>\s*<([^\s/>]+)/i
+
+/**
+ * Extracts the vim25 fault of a failed SOAP call.
+ *
+ * The fault type (`FileLocked`, `InvalidDeviceSpec`, `ManagedObjectNotFound`, ...) is the only part
+ * a caller can branch on: `faultstring` and `localizedMessage` are meant for humans and change with
+ * the locale of the server.
+ *
+ * Two sources are used, in order of reliability:
+ * 1. `rawError.root`, the envelope parsed by node-soap ( see `wsdl.xmlToObject`, which throws on a
+ *    fault and whose error is stored there by node-soap)
+ * 2. the raw response body, when the parsing itself failed
+ *
+ * @param {unknown} rawError - the error passed by node-soap to its callback
+ * @returns {{ code?: string, faultcode?: string, faultstring?: string, localizedMessage?: string, body?: string }}
+ */
+export function parseFault(rawError) {
+  const fault = rawError?.root?.Envelope?.Body?.Fault
+  const rawBody = rawError?.response?.data ?? rawError?.body
+  const body = typeof rawBody === 'string' && rawBody !== '<stream>' ? rawBody : undefined
+
+  let code, localizedMessage
+  let faultcode = valueOf(fault?.faultcode)
+  let faultstring = valueOf(fault?.faultstring)
+
+  const detail = fault?.detail
+  if (detail !== null && typeof detail === 'object') {
+    // the single child of `detail` names the fault, e.g.
+    // `<InvalidDeviceSpecFault xsi:type="InvalidDeviceSpec">`
+    for (const [name, value] of Object.entries(detail)) {
+      if (name === 'attributes') {
+        continue
+      }
+      code = value?.attributes?.['xsi:type'] ?? faultTypeOfElementName(name)
+      localizedMessage = valueOf(value?.localizedMessage)
+      break
+    }
+  }
+
+  if (body !== undefined) {
+    if (faultstring === undefined) {
+      const matches = body.match(FAULTSTRING_RE)
+      if (matches !== null) {
+        faultstring = unescapeXml(matches[1])
+      }
+    }
+    if (faultcode === undefined) {
+      const matches = body.match(FAULTCODE_RE)
+      if (matches !== null) {
+        faultcode = unescapeXml(matches[1])
+      }
+    }
+    if (code === undefined) {
+      const matches = body.match(DETAIL_CHILD_RE)
+      if (matches !== null) {
+        code = faultTypeOfElementName(matches[1])
+      }
+    }
+    if (localizedMessage === undefined) {
+      const matches = body.match(LOCALIZED_MESSAGE_RE)
+      if (matches !== null) {
+        localizedMessage = unescapeXml(matches[1])
+      }
+    }
+  }
+
+  return { code, faultcode, faultstring, localizedMessage, body }
+}

@vates/node-vsphere-soap/lib/_parseFault.test.mjs

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { parseFault } from './_parseFault.mjs'
+
+// captured from an ESXi 8 host
+const MANAGED_OBJECT_NOT_FOUND = `<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+<soapenv:Body>
+<soapenv:Fault><faultcode>ServerFaultCode</faultcode><faultstring>The object &apos;vim.VirtualMachine:vm-42&apos; has already been deleted or has not been completely created</faultstring><detail><ManagedObjectNotFoundFault xmlns="urn:vim25" xsi:type="ManagedObjectNotFound"><obj type="VirtualMachine">vm-42</obj></ManagedObjectNotFoundFault></detail></soapenv:Fault>
+</soapenv:Body>
+</soapenv:Envelope>`
+
+// not what a vSphere host sends — SOAP 1.1 requires these children to be unqualified — but a body
+// which node-soap failed to parse can come from anything sitting in front of vCenter
+const NAMESPACE_PREFIXED = `<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vim25="urn:vim25" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+<soapenv:Body>
+<soapenv:Fault><soapenv:faultcode>ServerFaultCode</soapenv:faultcode><soapenv:faultstring>Unable to access file since it is locked</soapenv:faultstring><soapenv:detail xmlns="urn:vim25"><vim25:FileLockedFault xsi:type="FileLocked"><vim25:localizedMessage>Unable to access file [ds1] vm/vm.vmdk since it is locked</vim25:localizedMessage></vim25:FileLockedFault></soapenv:detail></soapenv:Fault>
+</soapenv:Body>
+</soapenv:Envelope>`
+
+describe('parseFault', function () {
+  it('reads the fault from the envelope parsed by node-soap', function () {
+    const { code, faultcode, faultstring, localizedMessage } = parseFault({
+      root: {
+        Envelope: {
+          Body: {
+            Fault: {
+              faultcode: 'ServerFaultCode',
+              faultstring: 'Unable to access file since it is locked',
+              detail: {
+                FileLockedFault: {
+                  attributes: { 'xsi:type': 'FileLocked' },
+                  localizedMessage: 'Unable to access file [ds1] vm/vm.vmdk since it is locked',
+                },
+              },
+            },
+          },
+        },
+      },
+    })
+
+    assert.equal(code, 'FileLocked')
+    assert.equal(faultcode, 'ServerFaultCode')
+    assert.equal(faultstring, 'Unable to access file since it is locked')
+    assert.equal(localizedMessage, 'Unable to access file [ds1] vm/vm.vmdk since it is locked')
+  })
+
+  it('falls back to the element name when xsi:type is absent', function () {
+    const { code } = parseFault({
+      root: { Envelope: { Body: { Fault: { detail: { InvalidDeviceSpecFault: {} } } } } },
+    })
+
+    assert.equal(code, 'InvalidDeviceSpec')
+  })
+
+  it('falls back to the raw body when the envelope could not be parsed', function () {
+    const { code, faultcode, faultstring, body } = parseFault({
+      message: 'Request failed with status code 500',
+      response: { data: MANAGED_OBJECT_NOT_FOUND },
+    })
+
+    assert.equal(code, 'ManagedObjectNotFound')
+    assert.equal(faultcode, 'ServerFaultCode')
+    // entities are decoded
+    assert.match(faultstring, /^The object 'vim\.VirtualMachine:vm-42' has already been deleted/)
+    assert.equal(body, MANAGED_OBJECT_NOT_FOUND)
+  })
+
+  it('reads a namespace prefixed fault from the raw body', function () {
+    const { code, faultcode, faultstring, localizedMessage } = parseFault({
+      response: { data: NAMESPACE_PREFIXED },
+    })
+
+    assert.equal(code, 'FileLocked')
+    assert.equal(faultcode, 'ServerFaultCode')
+    assert.equal(faultstring, 'Unable to access file since it is locked')
+    assert.equal(localizedMessage, 'Unable to access file [ds1] vm/vm.vmdk since it is locked')
+  })
+
+  it('handles a `$value` wrapped text node', function () {
+    const { faultstring } = parseFault({
+      root: { Envelope: { Body: { Fault: { faultstring: { $value: 'boom' } } } } },
+    })
+
+    assert.equal(faultstring, 'boom')
+  })
+
+  it('does not throw on an error without any fault', function () {
+    assert.deepEqual(parseFault(new Error('socket hang up')), {
+      code: undefined,
+      faultcode: undefined,
+      faultstring: undefined,
+      localizedMessage: undefined,
+      body: undefined,
+    })
+    assert.deepEqual(parseFault(undefined).code, undefined)
+  })
+
+  it('ignores the placeholder body used by node-soap for streamed responses', function () {
+    assert.equal(parseFault({ body: '<stream>' }).body, undefined)
+  })
+})

@vates/node-vsphere-soap/lib/client.mjs

@@ -19,16 +19,29 @@ import soap from 'soap'
 import Cookie from 'soap-cookie' // required for session persistence
 import { createLogger } from '@xen-orchestra/log'
 
+import { parseFault } from './_parseFault.mjs'
+
+// exposed for the consumers talking to the host outside of the WSDL, e.g. `Fetch`
+export { parseFault } from './_parseFault.mjs'
+
 const { warn } = createLogger('xo:node-vsphere-soap:client')
 class VmwareError extends Error {
   constructor(rawError) {
-    super(rawError.body)
-    const matches = rawError.body?.match(/<faultstring[^>]*>(.*)<\/faultstring>/im)
-    this.message = matches?.[1] ?? rawError.message
+    const { code, faultcode, faultstring, localizedMessage, body } = parseFault(rawError)
+    super(localizedMessage ?? faultstring ?? rawError?.message ?? 'unknown SOAP error')
     this.name = 'VmwareError'
-    this.stack = rawError.stack
-    // not putting the cause since the error failed to be stringified correctly down the road
-    warn(rawError)
+    // the vim25 fault type, the only part of a fault a caller can branch on
+    this.code = code
+    this.faultcode = faultcode
+    this.faultstring = faultstring
+    this.localizedMessage = localizedMessage
+    this.body = body
+    if (rawError?.stack !== undefined) {
+      this.stack = rawError.stack
+    }
+    // legacy constraint: not putting the cause since the error failed to be stringified correctly
+    // down the road, the fault is exposed through own properties instead
+    warn('SOAP call failed', { code, faultcode, faultstring, localizedMessage })
   }
 }
 // Client class
@@ -38,6 +51,7 @@ class VmwareError extends Error {
 export function Client(vCenterHostname, username, password, sslVerify) {
   this.status = 'disconnected'
   this.reconnectCount = 0
+  this._exitHook = undefined
 
   sslVerify = typeof sslVerify !== 'undefined' ? sslVerify : false
 
@@ -90,44 +104,49 @@ util.inherits(Client, EventEmitter)
 
 Client.prototype.runCommand = function (command, args) {
   const self = this
-  let cmdargs
-  if (!args || args === null) {
-    cmdargs = {}
-  } else {
-    cmdargs = args
-  }
+  const cmdargs = args ?? {}
 
   const emitter = new EventEmitter()
 
+  const onResponse = function (err, result, raw, soapHeader) {
+    if (err) {
+      // an error and a result are mutually exclusive: emitting both makes every caller listening
+      // for 'result' believe the call succeeded, with `result` undefined
+      _soapErrorHandler(self, emitter, command, cmdargs, err)
+      return
+    }
+    if (command === 'Logout') {
+      self.status = 'disconnected'
+      self._unregisterExitHook()
+    }
+    emitter.emit('result', result, raw, soapHeader)
+  }
+
+  const send = function () {
+    self.client.VimService.VimPort[command](cmdargs, onResponse)
+  }
+
   // check if client has successfully connected
   if (self.status === 'ready' || self.status === 'connecting') {
-    self.client.VimService.VimPort[command](cmdargs, function (err, result, raw, soapHeader) {
-      if (err) {
-        _soapErrorHandler(self, emitter, command, cmdargs, err)
-      }
-      if (command === 'Logout') {
-        self.status = 'disconnected'
-        process.removeAllListeners('beforeExit')
-      }
-      emitter.emit('result', result, raw, soapHeader)
-    })
+    send()
   } else {
     // if connection not ready or connecting, reconnect to instance
     if (self.status === 'disconnected') {
       self.emit('connect')
     }
-    self.once('ready', function () {
-      self.client.VimService.VimPort[command](cmdargs, function (err, result, raw, soapHeader) {
-        if (err) {
-          _soapErrorHandler(self, emitter, command, cmdargs, err)
-        }
-        if (command === 'Logout') {
-          self.status = 'disconnected'
-          process.removeAllListeners('beforeExit')
-        }
-        emitter.emit('result', result, raw, soapHeader)
-      })
-    })
+
+    // a failed connection would otherwise leave this listener registered for ever, and the next
+    // successful one would replay every command whose caller has long given up
+    const onConnectionError = error => {
+      self.off('ready', onReady)
+      emitter.emit('error', error)
+    }
+    const onReady = () => {
+      self.off('error', onConnectionError)
+      send()
+    }
+    self.once('ready', onReady)
+    self.once('error', onConnectionError)
   }
 
   return emitter
@@ -153,9 +172,11 @@ Client.prototype._connect = function () {
     self.clientopts,
     function (err, client) {
       if (err) {
-        const vErr = new VmwareError(err)
-        self.emit('error', vErr)
-        throw vErr
+        self.status = 'disconnected'
+        // throwing here would be an uncaught exception: we are in an async callback, not in the
+        // stack of the caller
+        self.emit('error', new VmwareError(err))
+        return
       }
 
       self.client = client // save client for later use
@@ -186,7 +207,7 @@ Client.prototype._connect = function () {
 
               self.status = 'ready'
               self.emit('ready')
-              process.once('beforeExit', self._close)
+              self._registerExitHook()
             })
             .once('error', function (err) {
               self.status = 'disconnected'
@@ -202,9 +223,36 @@ Client.prototype._connect = function () {
   )
 }
 
+// Logs out on process exit, so that a session is not left open on the server until it expires.
+//
+// The hook must be stored: passing `self._close` directly would call it with `this === process`,
+// and removing it with `process.removeAllListeners('beforeExit')` would drop the hooks of every
+// other module of the process.
+Client.prototype._registerExitHook = function () {
+  const self = this
+
+  if (self._exitHook === undefined) {
+    self._exitHook = function () {
+      self._close()
+    }
+    process.once('beforeExit', self._exitHook)
+  }
+}
+
+Client.prototype._unregisterExitHook = function () {
+  const self = this
+
+  if (self._exitHook !== undefined) {
+    process.off('beforeExit', self._exitHook)
+    self._exitHook = undefined
+  }
+}
+
 Client.prototype._close = function () {
   const self = this
 
+  self._unregisterExitHook()
+
   if (self.status === 'ready') {
     self
       .runCommand('Logout', { _this: self.sessionManager })
@@ -220,34 +268,64 @@ Client.prototype._close = function () {
   }
 }
 
-function _soapErrorHandler(self, emitter, command, args, err) {
+// Errors are only emitted on `emitter`, the emitter of the failed call: throwing from here would
+// be an uncaught exception since we are always in an async callback, and emitting on the client
+// would reject unrelated concurrent calls.
+//
+// Exported for the unit tests: building a `Client` connects to a host.
+export function _soapErrorHandler(self, emitter, command, args, err) {
   err = err || { body: 'general error' }
 
-  if (err.body?.match(/session is not authenticated/)) {
-    self.status = 'disconnected'
-    process.removeAllListeners('beforeExit')
+  const vErr = new VmwareError(err)
 
-    if (self.reconnectCount < 10) {
-      self.reconnectCount += 1
-      self
-        .runCommand(command, args)
-        .once('result', function (result, raw, soapHeader) {
-          emitter.emit('result', result, raw, soapHeader)
-        })
-        .once('error', function (err) {
-          const vErr = new VmwareError(err)
-          emitter.emit('error', vErr)
-          throw vErr
-        })
-    } else {
-      const vErr = new VmwareError(err)
-      emitter.emit('error', vErr)
-      throw vErr
-    }
-  } else {
-    const vErr = new VmwareError(err)
+  // `NotAuthenticated` is raised when the session expired: log in again and replay the call.
+  //
+  // The fault type is used instead of the previous `err.body?.match(...)`: node-soap only fills
+  // `body` for streamed responses, so the string test never matched and the session was never
+  // renewed
+  const isSessionExpired =
+    vErr.code === 'NotAuthenticated' || /session is not authenticated/i.test(vErr.faultstring ?? vErr.message)
+
+  if (!isSessionExpired || self.reconnectCount >= 10) {
     emitter.emit('error', vErr)
-    throw vErr
+    return
+  }
+
+  // The call is replayed only once a new session is ready. Handing it straight to `runCommand`
+  // would send it right away while the status is 'connecting' — i.e. on the very session which
+  // just expired — and the failure of that replay would land back here.
+  const onConnectionError = function (error) {
+    self.off('ready', onReady)
+    emitter.emit('error', error)
+  }
+  const onReady = function () {
+    self.off('error', onConnectionError)
+    self
+      .runCommand(command, args)
+      .once('result', function (result, raw, soapHeader) {
+        emitter.emit('result', result, raw, soapHeader)
+      })
+      .once('error', function (retryError) {
+        emitter.emit('error', retryError)
+      })
+  }
+  self.once('ready', onReady)
+  self.once('error', onConnectionError)
+
+  // A whole wave of calls can fail on the same expired session, e.g. during an import. Only the
+  // first one to notice drops it and pays for a retry: the others ride the reconnect it started,
+  // instead of each burning one of the 10 and of resetting the status under a `_connect` already
+  // in flight — which used to start a second `soap.createClient` and replace `self.client` under
+  // the first one.
+  if (self.status === 'ready') {
+    self.status = 'disconnected'
+    self._unregisterExitHook()
+    self.reconnectCount += 1
+  }
+  if (self.status === 'disconnected') {
+    // no reconnect in flight: either this call is the first to notice, or the previous attempt
+    // already failed
+    self.emit('connect')
   }
 }
 

@vates/node-vsphere-soap/lib/client.test.mjs

@@ -0,0 +1,219 @@
+import assert from 'node:assert/strict'
+import { EventEmitter } from 'node:events'
+import { describe, it } from 'node:test'
+
+import { _soapErrorHandler } from './client.mjs'
+
+// what a host answers to any call made on a session which expired
+const NOT_AUTHENTICATED = {
+  root: {
+    Envelope: {
+      Body: {
+        Fault: {
+          faultcode: 'ServerFaultCode',
+          faultstring: 'The session is not authenticated.',
+          detail: { NotAuthenticatedFault: { attributes: { 'xsi:type': 'NotAuthenticated' } } },
+        },
+      },
+    },
+  },
+}
+
+const FILE_LOCKED = {
+  root: {
+    Envelope: {
+      Body: {
+        Fault: {
+          faultcode: 'ServerFaultCode',
+          faultstring: 'Unable to access file since it is locked',
+          detail: { FileLockedFault: { attributes: { 'xsi:type': 'FileLocked' } } },
+        },
+      },
+    },
+  },
+}
+
+/**
+ * A stand-in for a connected `Client`, reduced to what `_soapErrorHandler` touches: building a real
+ * one talks to a host.
+ *
+ * `connect` reproduces `_connect`, which only starts connecting from 'disconnected'.
+ */
+function fakeClient() {
+  const self = new EventEmitter()
+
+  self.status = 'ready'
+  self.reconnectCount = 0
+  self.unregisterExitHookCalls = 0
+  self._unregisterExitHook = () => {
+    self.unregisterExitHookCalls += 1
+  }
+
+  // the calls handed to `runCommand`, i.e. the ones actually sent to the host
+  self.sent = []
+  self.runCommand = (command, args) => {
+    const emitter = new EventEmitter()
+    self.sent.push({ args, command, emitter, statusWhenSent: self.status })
+    return emitter
+  }
+
+  self.connectCalls = 0
+  self.on('connect', () => {
+    self.connectCalls += 1
+    if (self.status === 'disconnected') {
+      self.status = 'connecting'
+    }
+  })
+
+  return self
+}
+
+// makes one in-flight call fail, and reports what its own emitter received
+function failingCall(self, command, rawError = NOT_AUTHENTICATED) {
+  const emitter = new EventEmitter()
+  const outcome = {}
+  emitter.once('result', result => {
+    outcome.result = result
+  })
+  emitter.once('error', error => {
+    outcome.error = error
+  })
+
+  _soapErrorHandler(self, emitter, command, { _this: command }, rawError)
+
+  return outcome
+}
+
+describe('_soapErrorHandler', function () {
+  it('replays a call made on an expired session, once the new session is ready', function () {
+    const self = fakeClient()
+
+    const outcome = failingCall(self, 'RetrievePropertiesEx')
+
+    assert.equal(self.reconnectCount, 1)
+    assert.equal(self.status, 'connecting')
+    assert.equal(self.unregisterExitHookCalls, 1)
+    assert.deepEqual(self.sent, [])
+
+    self.status = 'ready'
+    self.emit('ready')
+
+    assert.equal(self.sent.length, 1)
+    assert.equal(self.sent[0].command, 'RetrievePropertiesEx')
+    self.sent[0].emitter.emit('result', 'replayed')
+    assert.equal(outcome.result, 'replayed')
+  })
+
+  it('starts a single reconnect for a whole wave of calls on the same session', function () {
+    const self = fakeClient()
+
+    const outcomes = [failingCall(self, 'A'), failingCall(self, 'B'), failingCall(self, 'C')]
+
+    // one retry for the wave, not one per call: they used to exhaust the 10 of a busy import
+    assert.equal(self.reconnectCount, 1)
+    assert.equal(self.connectCalls, 1)
+    assert.equal(self.unregisterExitHookCalls, 1)
+    // and none of them is sent while the reconnect is in flight, which would mean sending it on
+    // the session which just expired
+    assert.deepEqual(self.sent, [])
+
+    self.status = 'ready'
+    self.emit('ready')
+
+    assert.deepEqual(
+      self.sent.map(({ command, statusWhenSent }) => [command, statusWhenSent]),
+      [
+        ['A', 'ready'],
+        ['B', 'ready'],
+        ['C', 'ready'],
+      ]
+    )
+
+    // each replay answers its own caller
+    self.sent[1].emitter.emit('result', 'B replayed')
+    assert.equal(outcomes[1].result, 'B replayed')
+    assert.equal(outcomes[0].result, undefined)
+    assert.equal(outcomes[2].result, undefined)
+  })
+
+  it('restarts a reconnect which already failed', function () {
+    const self = fakeClient()
+
+    failingCall(self, 'A')
+    assert.equal(self.connectCalls, 1)
+
+    // the reconnect failed, nothing is in flight any more
+    self.status = 'disconnected'
+
+    failingCall(self, 'B')
+    assert.equal(self.connectCalls, 2)
+    // the session was already dropped by the first call, the second one must not pay for it again
+    assert.equal(self.reconnectCount, 1)
+  })
+
+  it('reports a failed reconnect to every waiting call, and stops listening', function () {
+    const self = fakeClient()
+
+    const outcomes = [failingCall(self, 'A'), failingCall(self, 'B')]
+
+    const connectionError = new Error('host unreachable')
+    self.status = 'disconnected'
+    self.emit('error', connectionError)
+
+    assert.equal(outcomes[0].error, connectionError)
+    assert.equal(outcomes[1].error, connectionError)
+    assert.deepEqual(self.sent, [])
+    // a listener left behind would replay a call whose caller has long given up
+    assert.equal(self.listenerCount('ready'), 0)
+    assert.equal(self.listenerCount('error'), 0)
+  })
+
+  it('reports the error of a replay which failed too', function () {
+    const self = fakeClient()
+
+    const outcome = failingCall(self, 'A')
+
+    self.status = 'ready'
+    self.emit('ready')
+
+    const replayError = new Error('failed again')
+    self.sent[0].emitter.emit('error', replayError)
+    assert.equal(outcome.error, replayError)
+  })
+
+  it('gives up after 10 reconnects', function () {
+    const self = fakeClient()
+    self.reconnectCount = 10
+
+    const outcome = failingCall(self, 'A')
+
+    assert.equal(outcome.error.code, 'NotAuthenticated')
+    assert.equal(self.connectCalls, 0)
+    assert.equal(self.status, 'ready')
+    assert.deepEqual(self.sent, [])
+  })
+
+  it('emits an error which is not a session expiry as is, without reconnecting', function () {
+    const self = fakeClient()
+
+    const outcome = failingCall(self, 'A', FILE_LOCKED)
+
+    assert.equal(outcome.error.code, 'FileLocked')
+    assert.equal(self.connectCalls, 0)
+    assert.equal(self.reconnectCount, 0)
+    assert.equal(self.status, 'ready')
+    assert.deepEqual(self.sent, [])
+  })
+
+  it('recognizes an expiry which only says so in its faultstring', function () {
+    const self = fakeClient()
+
+    // no `detail`, hence no fault type to branch on
+    failingCall(self, 'A', {
+      root: { Envelope: { Body: { Fault: { faultstring: 'The session is not authenticated.' } } } },
+    })
+
+    assert.equal(self.reconnectCount, 1)
+    assert.equal(self.connectCalls, 1)
+  })
+})

@vates/node-vsphere-soap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vates/node-vsphere-soap",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "interface to vSphere SOAP/WSDL from node for interfacing with vCenter or ESXi, forked from node-vsphere-soap",
   "main": "lib/client.mjs",
   "author": "reedog117",
@@ -31,6 +31,7 @@
     "node": ">=14"
   },
   "scripts": {
-    "postversion": "npm publish --access public"
+    "postversion": "npm publish --access public",
+    "test": "node --test lib/*.test.mjs"
   }
 }

@vates/node-vsphere-soap/test/config-test.stub.mjs

@@ -1,7 +1,7 @@
-// place your own credentials here for a vCenter or ESXi server
-// this information will be used for connecting to a vCenter instance
-// for module testing
-// name the file config-test.js
+// place your own credentials here for a vCenter or ESXi server: they are used by
+// vsphere-soap.integ.mjs to connect to a real instance.
+//
+// copy this file next to it, as `config-test.mjs`. It is ignored by git, do not commit it.
 
 export const vCenterTestCreds = {
   vCenterIP: 'vcsa',

@vates/node-vsphere-soap/test/vsphere-soap.test.mjs

@@ -1,138 +0,0 @@
-/*
-  vsphere-soap.test.js
-
-  tests for the vCenterConnectionInstance class
-*/
-
-import assert from 'assert'
-import { describe, it } from 'node:test'
-
-import * as vc from '../lib/client.mjs'
-
-// eslint-disable-next-line n/no-missing-import
-import { vCenterTestCreds as TestCreds } from '../config-test.mjs'
-
-const VItest = new vc.Client(TestCreds.vCenterIP, TestCreds.vCenterUser, TestCreds.vCenterPassword, false)
-
-describe('Client object initialization:', function () {
-  it('provides a successful login', { timeout: 5000 }, function (t, done) {
-    VItest.once('ready', function () {
-      assert.notEqual(VItest.userName, null)
-      assert.notEqual(VItest.fullName, null)
-      assert.notEqual(VItest.serviceContent, null)
-      done()
-    }).once('error', function (err) {
-      console.error(err)
-      // this should fail if there's a problem
-      assert.notEqual(VItest.userName, null)
-      assert.notEqual(VItest.fullName, null)
-      assert.notEqual(VItest.serviceContent, null)
-      done()
-    })
-  })
-})
-
-describe('Client reconnection test:', function () {
-  it('can successfully reconnect', { timeout: 5000 }, function (t, done) {
-    VItest.runCommand('Logout', { _this: VItest.serviceContent.sessionManager })
-      .once('result', function (result) {
-        // now we're logged out, so let's try running a command to test automatic re-login
-        VItest.runCommand('CurrentTime', { _this: 'ServiceInstance' })
-          .once('result', function (result) {
-            assert(result.returnval instanceof Date)
-            done()
-          })
-          .once('error', function (err) {
-            console.error(err)
-          })
-      })
-      .once('error', function (err) {
-        console.error(err)
-      })
-  })
-})
-
-// these tests don't work yet
-describe('Client tests - query commands:', function () {
-  it('retrieves current time', { timeout: 5000 }, function (t, done) {
-    VItest.runCommand('CurrentTime', { _this: 'ServiceInstance' }).once('result', function (result) {
-      assert(result.returnval instanceof Date)
-      done()
-    })
-  })
-
-  it('retrieves current time 2 (check for event clobbering)', { timeout: 5000 }, function (t, done) {
-    VItest.runCommand('CurrentTime', { _this: 'ServiceInstance' }).once('result', function (result) {
-      assert(result.returnval instanceof Date)
-      done()
-    })
-  })
-
-  it('can obtain the names of all Virtual Machines in the inventory', { timeout: 20000 }, function (t, done) {
-    // get property collector
-    const propertyCollector = VItest.serviceContent.propertyCollector
-    // get view manager
-    const viewManager = VItest.serviceContent.viewManager
-    // get root folder
-    const rootFolder = VItest.serviceContent.rootFolder
-
-    let containerView, objectSpec, traversalSpec, propertySpec, propertyFilterSpec
-    // this is the equivalent to
-    VItest.runCommand('CreateContainerView', {
-      _this: viewManager,
-      container: rootFolder,
-      type: ['VirtualMachine'],
-      recursive: true,
-    }).once('result', function (result) {
-      // build all the data structures needed to query all the vm names
-      containerView = result.returnval
-
-      objectSpec = {
-        attributes: { 'xsi:type': 'ObjectSpec' }, // setting attributes xsi:type is important or else the server may mis-recognize types!
-        obj: containerView,
-        skip: true,
-      }
-
-      traversalSpec = {
-        attributes: { 'xsi:type': 'TraversalSpec' },
-        name: 'traverseEntities',
-        type: 'ContainerView',
-        path: 'view',
-        skip: false,
-      }
-
-      objectSpec = { ...objectSpec, selectSet: [traversalSpec] }
-
-      propertySpec = {
-        attributes: { 'xsi:type': 'PropertySpec' },
-        type: 'VirtualMachine',
-        pathSet: ['name'],
-      }
-
-      propertyFilterSpec = {
-        attributes: { 'xsi:type': 'PropertyFilterSpec' },
-        propSet: [propertySpec],
-        objectSet: [objectSpec],
-      }
-      // TODO: research why it fails if propSet is declared after objectSet
-
-      VItest.runCommand('RetrievePropertiesEx', {
-        _this: propertyCollector,
-        specSet: [propertyFilterSpec],
-        options: { attributes: { type: 'RetrieveOptions' } },
-      })
-        .once('result', function (result, raw) {
-          assert.notEqual(result.returnval.objects, null)
-          if (Array.isArray(result.returnval.objects)) {
-            assert.strictEqual(result.returnval.objects[0].obj.attributes.type, 'VirtualMachine')
-          } else {
-            assert.strictEqual(result.returnval.objects.obj.attributes.type, 'VirtualMachine')
-          }
-          done()
-        })
-        .once('error', function (err) {
-          console.error('\n\nlast request : ' + VItest.client.lastRequest, err)
-        })
-    })
-  })
-})

@vates/types/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vates/types",
   "private": false,
-  "version": "1.30.1",
+  "version": "2.3.0",
   "main": "./dist/index.mjs",
   "exports": {
     ".": {
@@ -33,7 +33,8 @@
     "@eslint/js": "^9.19.0",
     "typescript": "~5.6.3",
     "typescript-eslint": "^8.61.0",
-    "@types/express": "^5.0.0"
+    "@types/express": "^5.0.0",
+    "@xen-orchestra/disk-transform": "^1.3.3"
   },
   "scripts": {
     "build": "tsc",

@vates/types/src/common.mts

@@ -1,4 +1,4 @@
-import type { XoHost, XoNetwork, XoVif } from './xo.mjs'
+import type { XapiXoRecord, XoHost, XoNetwork, XoVif } from './xo.mjs'
 
 declare const __brand: unique symbol
 
@@ -755,9 +755,9 @@ export type TrafficRuleDirection = 'from' | 'to' | 'from/to'
 
 export type RawTrafficRule = {
   allow: boolean
-  protocol: string
+  protocol: TrafficRuleProtocol
   ipRange: string
-  direction: string
+  direction: TrafficRuleDirection
   port?: string
 }
 
@@ -769,3 +769,34 @@ type BaseTrafficRule = RawTrafficRule & {
 export type TrafficRule =
   | (BaseTrafficRule & { type: XoVif['type']; sourceId: XoVif['id'] })
   | (BaseTrafficRule & { type: XoNetwork['type']; sourceId: XoNetwork['id'] })
+
+export const XAPI_TYPES: readonly string[] = [
+  'network',
+  'VIF',
+  'message',
+  'gpuGroup',
+  'host',
+  'PBD',
+  'PCI',
+  'PGPU',
+  'PIF',
+  'pool',
+  'SR',
+  'VBD',
+  'VDI',
+  'VDI-snapshot',
+  'VDI-unmanaged',
+  'vgpu',
+  'vgpuType',
+  'VM',
+  'VM-controller',
+  'VM-snapshot',
+  'VM-template',
+  'VTPM',
+  'SM',
+] satisfies readonly XapiXoRecord['type'][]
+
+/** steps of a rolling pool update on one host, in execution order */
+export const RPU_RECOVERY_STEP_NAMES = ['evacuate', 'update', 'reboot', 'enable', 'restoreVms'] as const
+
+export type RPU_RECOVERY_STEP_NAME = (typeof RPU_RECOVERY_STEP_NAMES)[number]

@vates/types/src/lib/rest-api.mts

@@ -4,40 +4,34 @@ import type { XoApp } from '../xo-app.mjs'
 
 export type SecurityName = '*' | 'token' | 'basic' | 'none'
 
-export type FieldDefinition =
+export type FieldDefinition = { optional?: boolean; nullable?: boolean } & (
   | {
       type: 'string'
       example?: string
-      optional?: boolean
     }
   | {
       type: 'boolean'
       example?: boolean
-      optional?: boolean
     }
   | {
       type: 'number'
       example?: number
-      optional?: boolean
     }
   | {
       type: 'enum'
       enum: string[]
       example?: string
-      optional?: boolean
     }
   | {
       type: 'object'
       fields: Record<string, FieldDefinition>
-      optional?: boolean
     }
   | {
       type: 'array'
       items: FieldDefinition
       example?: unknown[]
-      optional?: boolean
     }
-
+)
 export type ParamFieldDefinition = Exclude<
   FieldDefinition,
   { type: 'boolean' } | { type: 'object' } | { type: 'array' }

@vates/types/src/lib/xen-orchestra-xapi.mts

@@ -24,6 +24,8 @@ import type {
   VIF_LOCKING_MODE,
   VM_OPERATIONS,
 } from '../common.mjs'
+import type { DiskPassthrough } from '@xen-orchestra/disk-transform'
+import type { EventEmitter } from 'node:events'
 import type { PassThrough, Readable } from 'node:stream'
 import type {
   XapiXoRecord,
@@ -469,6 +471,12 @@ export interface Xapi {
   destroySr(id: XoSr['id']): Promise<void>
   xostor_delete(ref: XenApiSr['$ref']): Promise<void>
   objects: {
+    // emits `add`/`update`/`remove` only while the connection watches the pool events
+    allIndexes: {
+      type: {
+        getEventEmitterByType(type: WrappedXenApiRecord['$type']): EventEmitter
+      }
+    }
     indexes: {
       type: {
         [XenApiRecord in WrappedXenApiRecord as XenApiRecord['$type']]: Record<XenApiRecord['uuid'], XenApiRecord>
@@ -476,3 +484,42 @@ export interface Xapi {
     }
   }
 }
+
+/**
+ * Parameters accepted by the `XapiDiskSource` constructor.
+ *
+ * `baseRef` turns the export into a differencing one: leaving it out exports the whole disk.
+ * `preferNbd` only expresses a preference, {@link XapiDiskSource} silently falls back to a plain
+ * stream export — and, when `baseRef` can't be used as a base, to a full one.
+ */
+export interface XapiDiskSourceOptions {
+  baseRef?: XenApiVdi['$ref']
+  blockSize?: number
+  nbdConcurrency?: number
+  /** When true, only `getBlockIndexes()` may be called: `readBlock()` throws. */
+  onlyListChangedBlocks?: boolean
+  preferNbd?: boolean
+  timeout?: number
+  vdiRef: XenApiVdi['$ref']
+  xapi: Xapi
+}
+
+/**
+ * Disk source handling the fallback logic of a VDI export: NBD + CBT, then NBD + stream export
+ * for the block list, then plain stream export.
+ *
+ * {@link XapiDiskSourceOptions.preferNbd} is a preference, not a guarantee: call
+ * {@link XapiDiskSource.useNbd} and {@link XapiDiskSource.useCbt} after `init()` to know what the
+ * export actually used.
+ */
+export interface XapiDiskSource extends DiskPassthrough {
+  useCbt(): boolean
+  useNbd(): boolean
+}
+
+/**
+ * Signature of `@xen-orchestra/xapi`'s `parseDateTime`.
+ *
+ * Returns a Unix timestamp in seconds, or `null` if the field is empty (as encoded by XAPI).
+ */
+export type ParseDateTime = (input: string | number | Date) => number | null

@vates/types/src/xo-app.mts

@@ -2,6 +2,7 @@ import { EventEmitter } from 'node:stream'
 import type {
   AnyXoJob,
   AnyXoLog,
+  NonXapiXoRecord,
   XapiXoRecord,
   XoAuthenticationToken,
   XoBackupRepository,
@@ -21,6 +22,7 @@ import type {
 } from './xo.mjs'
 import { VatesTask } from './lib/vates-task.mjs'
 import type { PluginRestRouteDefinition } from './lib/rest-api.mjs'
+import type { RPU_RECOVERY_STEP_NAME } from './common.mjs'
 import {
   Xapi,
   XapiHostStats,
@@ -125,6 +127,70 @@ type License = {
   bundleInfo?: { name: string; id: string }
 }
 
+export type PoolRollingUpdateRecoveryStep = {
+  status: 'pending' | 'running' | 'observed-succeeded' | 'failed' | 'not-needed'
+  startedAt?: string
+  finishedAt?: string
+}
+
+/** error serialized by the recovery recorder: secret-looking keys are redacted */
+export type PoolRollingUpdateRecoveryError = {
+  name?: string
+  message?: string
+  stack?: string
+  code?: string | number
+  [key: string]: unknown
+}
+
+export type PoolRollingUpdateRecoveryHost = {
+  status: 'pending' | 'running' | 'succeeded' | 'failed' | 'not-needed'
+  steps: Record<RPU_RECOVERY_STEP_NAME, PoolRollingUpdateRecoveryStep>
+  lastError: PoolRollingUpdateRecoveryError | null
+}
+
+export type PoolRollingUpdateRecoveryRun = {
+  runId: string
+  poolId: string
+  status: 'preparing' | 'running' | 'interrupted' | 'resuming' | 'failed' | 'cleaning' | 'succeeded'
+  startedAt: string
+  updatedAt: string
+  finishedAt?: string
+  interruptedAt?: string
+  taskId?: string
+  variant?: 'xcp' | 'xs-cdn'
+  hostOrder?: string[]
+  hosts: Record<string, PoolRollingUpdateRecoveryHost>
+  lastError: PoolRollingUpdateRecoveryError | null
+  /** VM UUID -> UUID of the host it must be started on */
+  haltedPinnedVms: Record<string, string>
+}
+
+/** record unreadable or of an unknown schema version: recovery needs a human */
+export type PoolRollingUpdateRecoveryBlocked = {
+  poolId?: string
+  runId?: string
+  status: 'blocked'
+  blockedReason: string
+}
+
+export type PoolRollingUpdateRecovery = PoolRollingUpdateRecoveryRun | PoolRollingUpdateRecoveryBlocked
+
+/** A disk of a backup archive currently served as a read-only iSCSI LUN */
+export type BackupArchiveDiskMount = {
+  /** Handle to pass to `unmountBackupArchiveDisk` */
+  id: string
+  /** UUID of the SR introduced on the host */
+  srUuid: string
+  /** UUID of the read-only VDI exposing the backup disk */
+  vdiUuid: string
+  /** IQN of the target serving the disk */
+  iqn: string
+  /** Address of the portal, as advertised to the host */
+  address: string
+  /** Port of the portal (ephemeral, one target per mount) */
+  port: number
+}
+
 export type XoApp = {
   hooks: EventEmitter
   _redis: {
@@ -201,9 +267,11 @@ export type XoApp = {
     userData?: { ip?: string },
     opts?: { bypassOtp?: boolean; bypassTaskCreation?: boolean }
   ) => Promise<{ bypassOtp: boolean; expiration: number; user: XoUser }>
-  backupGuard(poolId: XoPool['id']): Promise<void>
+  backupGuard(objectId: XapiXoRecord['id'], opts?: { bypassBackupCheck?: boolean; operation: string }): Promise<void>
   /* Throw if no authorization */
   checkFeatureAuthorization(featureCode: FeatureCode): Promise<void>
+  /* validate, apply and persist the configuration of a plugin */
+  configurePlugin(id: string, configuration: unknown, mergeWithExisting?: boolean): Promise<void>
   /* connect a server (XCP-ng/XenServer) */
   connectXenServer(id: XoServer['id']): Promise<void>
   // TODO: replace all XoAclBasePrivilege with a more strict type. (discriminate union)
@@ -233,7 +301,14 @@ export type XoApp = {
     proxy?: XoProxy['id']
     url: string
   }): Promise<XoBackupRepository>
-  createUser(params: { name?: string; password?: string; [key: string]: unknown }): Promise<XoUser>
+  createUser(params: {
+    firstname?: string
+    lastname?: string
+    name?: string
+    password?: string
+    username?: string
+    [key: string]: unknown
+  }): Promise<XoUser>
   deleteAclV2GroupRole(
     groupId: XoGroup['id'],
     roleId: XoAclRole['id'],
@@ -291,9 +366,16 @@ export type XoApp = {
     >
   >
   getAllSchedules(): Promise<XoSchedule[]>
-  getAllUsers(): Promise<XoUser[]>
+  getAllUsers(opts?: { obfuscatePassword?: boolean }): Promise<XoUser[]>
   getAllXenServers(): Promise<XoServer[]>
   getAuthenticationTokensForUser(userId: XoUser['id']): Promise<XoAuthenticationToken[]>
+  /** Archive/host a live-mounted disk belongs to, as recorded by `mountBackupArchiveDisk` */
+  getBackupArchiveDiskMountOwner(id: BackupArchiveDiskMount['id']): {
+    archiveId: XoVmBackupArchive['id']
+    hostId: XoHost['id']
+    /** set when the disk is served by a proxy instead of this appliance */
+    proxyId?: XoProxy['id']
+  }
   getBackupNgLogs(): Promise<Record<string, AnyXoLog>>
   getBackupNgLogs(id: AnyXoLog['id']): Promise<AnyXoLog>
   getBackupNgLogsSorted(opts: {
@@ -305,6 +387,7 @@ export type XoApp = {
   getGroup(id: XoGroup['id']): Promise<XoGroup>
   getHVSupportedVersions: undefined | (() => Promise<{ [key: XoHost['productBrand']]: string }>)
   getJob<T extends AnyXoJob>(id: T['id']): Promise<T>
+  isJobSequence(job: AnyXoJob): boolean
   getObject: <T extends XapiXoRecord>(id: T['id'], type?: T['type'] | T['type'][]) => T
   getObjectsByType: <T extends XapiXoRecord>(
     type: T['type'],
@@ -312,7 +395,8 @@ export type XoApp = {
   ) => Record<T['id'], T> | undefined
   getTotalBackupSizeOnRemote(id: XoBackupRepository['id']): Promise<{ onDisk: number }>
   getSchedule(id: XoSchedule['id']): Promise<XoSchedule>
-  getUser: (id: XoUser['id']) => Promise<XoUser>
+  getUser: (id: XoUser['id'], opts?: { obfuscatePassword?: boolean }) => Promise<XoUser>
+  getUserIdentityFields(): string[]
   getXapi(maybeId: XapiXoRecord['id'] | XapiXoRecord): Xapi
   getXapiHostStats: (hostId: XoHost['id'], granularity?: XapiStatsGranularity) => Promise<XapiHostStats>
   getXapiObject: <T extends XapiXoRecord>(
@@ -322,17 +406,42 @@ export type XoApp = {
   getXapiPoolStats(poolId: XoPool['id'], granularity?: XapiStatsGranularity): Promise<XapiPoolStats>
   getXapiVmStats: (vmId: XoVm['id'], granularity?: XapiStatsGranularity) => Promise<XapiVmStats>
   getXenServer(id: XoServer['id']): Promise<XoServer>
+  getXoEventEmitterByType(type: string): EventEmitter
   hasFeatureAuthorization(featureCode: string): Promise<boolean>
   hasObject<T extends XapiXoRecord>(id: T['id'], type: T['type']): boolean
   listMetadataBackups(backupRepositoryIds: XoBackupRepository['id'][]): Promise<{
     xo: Record<XoBackupRepository['id'], XoConfigBackupArchive[]>
     pool: Record<XoBackupRepository['id'], Record<XoPool['id'], XoPoolBackupArchive[]>>
   }>
+  /** `null` when the listing of a backup repository failed */
   listVmBackupsNg(
     backupRepositoryIds: XoBackupRepository['id'][],
-    opts?: { _forceRefresh?: boolean; vmId: XoVm['id'] }
-  ): Promise<Record<XoBackupRepository['id'], Record<XoVm['id'], XoVmBackupArchive[]>>>
+    opts?: { _forceRefresh?: boolean; vmId?: XoVm['id'] }
+  ): Promise<Record<XoBackupRepository['id'], Record<XoVm['id'], XoVmBackupArchive[]> | null>>
+  /**
+   * Serve one disk of a backup archive as a read-only iSCSI LUN and attach it to
+   * `host` as an SR. Undone by `unmountBackupArchiveDisk`.
+   *
+   * The LUN is served by whoever can read the backup repository: this appliance, or the proxy the
+   * repository is linked to.
+   */
+  mountBackupArchiveDisk(params: {
+    archiveId: XoVmBackupArchive['id']
+    /** One of the archive's `disks[].id` */
+    diskId: string
+    hostId: XoHost['id']
+  }): Promise<BackupArchiveDiskMount>
   pingRemote(id: XoBackupRepository['id']): Promise<{ success: true }>
+  /**
+   * Record the live mounts a proxy created by itself, while running a restore: they never went
+   * through `mountBackupArchiveDisk`, so nothing else knows which proxy serves them.
+   */
+  registerProxyBackupArchiveDiskMounts(params: {
+    archiveId: XoVmBackupArchive['id']
+    /** as reported by the restore, each with the host it is attached to */
+    mounts: { id: BackupArchiveDiskMount['id']; hostId: XoHost['id'] }[]
+    proxyId: XoProxy['id']
+  }): void
   /** Allow to add a new server in the DB (XCP-ng/XenServer) */
   registerXenServer(
     body: Pick<XoServer, 'host' | 'httpProxy' | 'label' | 'username'> & {
@@ -341,11 +450,22 @@ export type XoApp = {
       readOnly?: XoServer['readOnly']
     }
   ): Promise<XoServer>
-  rollingPoolReboot(pool: XoPool, opts?: { parentTask?: VatesTask; shutdownPinnedVms?: boolean }): Promise<void>
+  rollingPoolReboot(
+    pool: XoPool,
+    opts?: { bypassBackupCheck?: boolean; parentTask?: VatesTask; shutdownPinnedVms?: boolean }
+  ): Promise<void>
   rollingPoolUpdate(
     pool: XoPool,
-    opts?: { rebootVm?: boolean; parentTask?: VatesTask; shutdownPinnedVms?: boolean }
+    opts?: {
+      acceptCurrentStateAsBaseline?: boolean
+      bypassBackupCheck?: boolean
+      rebootVm?: boolean
+      parentTask?: VatesTask
+      shutdownPinnedVms?: boolean
+    }
   ): Promise<void>
+  getRollingUpdateRecovery(poolId: XoPool['id']): Promise<PoolRollingUpdateRecovery | undefined>
+  finalizeRollingUpdate(pool: XoPool, opts?: { force?: boolean; parentTask?: VatesTask }): Promise<void>
   setVmResourceSet(vmId: XoVm['id'], resourceSetId: string | null, force?: boolean): Promise<void>
   shareVmResourceSet(vmId: XoVm['id']): Promise<void>
   removeUserFromGroup(userId: XoUser['id'], id: XoGroup['id']): Promise<void>
@@ -357,20 +477,30 @@ export type XoApp = {
     | { success: true; readRate: number; writeRate: number }
     | { success: false; step: string; file: string; error: unknown }
   >
+  touchXoObject(type: string, id: NonXapiXoRecord['id']): Promise<void>
+  /** Detach a disk mounted by `mountBackupArchiveDisk` and stop serving it */
+  unmountBackupArchiveDisk(id: BackupArchiveDiskMount['id']): Promise<void>
+  reclaimSpace(
+    remoteId: XoBackupRepository['id'],
+    opts?: { vmUuid?: XoVm['id']; merge?: boolean; remove?: boolean }
+  ): Promise<{ vmUuid: string; success: boolean; merge?: boolean; size?: number; error?: string }[]>
   /** Remove a server from the DB (XCP-ng/XenServer) */
   unregisterXenServer(id: XoServer['id']): Promise<void>
   updateUser(
     id: XoUser['id'],
     updates: {
+      email?: string
+      authProviders?: Record<string, string>
+      firstname?: string
+      lastname?: string
       /**
        * @deprecated
        */
-      email?: string
-      authProviders?: Record<string, string>
       name?: string
       password?: string
       permission?: string
       preferences?: Record<string, string>
+      username?: string
     }
   ): Promise<void>
   updateAclV2Privilege(

@vates/types/src/xo.mts

@@ -19,7 +19,7 @@ import type {
   VM_POWER_STATE,
 } from './common.mjs'
 import type * as CMType from './lib/complex-matcher.mjs'
-import { XoAclPrivilege, XoAclRole, XoAclSupportedActionsByResource } from './lib/xen-orchestra-acl.mjs'
+import { XoAclBasePrivilege, XoAclRole } from './lib/xen-orchestra-acl.mjs'
 import type { XenApiHost, XenApiPool } from './xen-api.mjs'
 
 type BaseXapiXo = {
@@ -140,6 +140,7 @@ export type XoAlarm = Omit<XoMessage, '$object' | 'body'> & {
 }
 
 // TODO: to be typed when Bastien.N has finished working on the XO task
+// Once the [key:string]: unknown is removed, remove the `as XoMessage` in event.class.mts
 type BaseXoLog = {
   id: Branded<'xo-log'>
   infos?: { data: unknown; message: string }[]
@@ -200,8 +201,14 @@ export type XoPoolBackupArchive = XoMetadataBackupArchive & {
   type: 'xo-pool-metadata-backup'
 }
 
+export type XoBackupRepositoryBenchmark = {
+  readRate: number
+  timestamp: number
+  writeRate: number
+}
+
 export type XoBackupRepository = {
-  benchmarks?: { readRate: number; timestamp: number; writeRate: number }[]
+  benchmarks?: XoBackupRepositoryBenchmark[]
   enabled: boolean
   error?: Record<string, unknown>
   id: Branded<'backup-repository'>
@@ -578,6 +585,9 @@ export type XoJob = BaseXoJob & {
       [key: string]: unknown
     }[]
   }
+  userId?: XoUser['id']
+  createdBy?: XoUser['id']
+  updatedBy?: XoUser['id']
 }
 
 export type XoSchedule = {
@@ -602,7 +612,7 @@ export type XoServer = {
   poolNameDescription?: string
   poolNameLabel?: string
   readOnly: boolean
-  status: 'connected' | 'disconnected' | 'connecting'
+  status: 'connected' | 'disconnecting' | 'disconnected' | 'connecting'
   username: string
 }
 
@@ -712,12 +722,18 @@ export type XoTask = {
 export type XoUser = {
   authProviders?: Record<string, string>
   email: string
+  firstname?: string
   groups: XoGroup['id'][]
   id: Branded<'user'>
+  lastname?: string
+  /**
+   * @deprecated use username instead
+   */
   name?: string
   permission: 'none' | 'admin'
   pw_hash?: string
   preferences: Record<string, string>
+  username?: string
 }
 
 export type XoAuthenticationToken = {
@@ -889,10 +905,7 @@ export type XapiXoRecord =
   | XoVtpm
   | XoSm
 
-export type NonXapiXoRecord<
-  TActionsByResource extends XoAclSupportedActionsByResource = never,
-  TResource extends string = never,
-> =
+export type NonXapiXoRecord =
   | AnyXoBackupArchive
   | AnyXoJob
   | AnyXoLog
@@ -905,12 +918,9 @@ export type NonXapiXoRecord<
   | XoTask
   | XoUser
   | XoAclRole
-  | XoAclPrivilege<TActionsByResource, TResource>
+  | XoAclBasePrivilege
 
-export type XoRecord<
-  TActionsByResource extends XoAclSupportedActionsByResource = never,
-  TResource extends string = never,
-> = XapiXoRecord | NonXapiXoRecord<TActionsByResource, TResource>
+export type XoRecord = XapiXoRecord | NonXapiXoRecord
 
 export type AnyXoVm = XoVm | XoVmSnapshot | XoVmTemplate | XoVmController
 

@vates/types/tsconfig.json

@@ -4,6 +4,7 @@
     "declaration": true,
     "strict": true,
     "module": "ESNext",
+    "moduleResolution": "bundler",
     "target": "ES2022",
     "skipLibCheck": true,
     "types": ["node"] // Only use types from Node.js and packages that are explicitly imported

@xen-orchestra/acl/package.json

@@ -6,7 +6,7 @@
   "main": "dist/index.mjs",
   "name": "@xen-orchestra/acl",
   "homepage": "https://github.com/vatesfr/xen-orchestra/tree/master/@xen-orchestra/acl",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "license": "AGPL-3.0-or-later",
   "private": false,
   "type": "module",
@@ -30,7 +30,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.19.0",
-    "@vates/types": "^1.30.1",
+    "@vates/types": "^2.3.0",
     "rimraf": "^6.0.1",
     "typescript": "~5.6",
     "typescript-eslint": "^8.61.0"

@xen-orchestra/acl/src/actions/backup-repository.mts

@@ -10,4 +10,5 @@ export default {
     proxy: true,
     url: true,
   },
+  'reclaim-space': true,
 }

@xen-orchestra/acl/src/actions/user.mts

@@ -3,9 +3,12 @@ export default {
   delete: true,
   read: true,
   update: {
+    firstname: true,
+    lastname: true,
     name: true,
     password: true,
     permission: true,
     preferences: true,
+    username: true,
   },
 }

@xen-orchestra/async-map/index.js

@@ -13,11 +13,11 @@ const wrapCall = (fn, arg, thisArg) => {
  *
  * WARNING: Does not handle plain objects
  *
- * @template Item,This
+ * @template Item, Result, [This=Iterable<Item>]
  * @param {Iterable<Item>} iterable
- * @param {(this: This, item: Item) => (Item | PromiseLike<Item>)} mapFn
- * @param {This} [thisArg]
- * @returns {Promise<Item[]>}
+ * @param {(this: This, item: Item) => (Result | PromiseLike<Result>)} mapFn
+ * @param {This} [thisArg] defaults to `iterable`
+ * @returns {Promise<Result[]>}
  */
 exports.asyncMap = function asyncMap(iterable, mapFn, thisArg = iterable) {
   return Promise.all(Array.from(iterable, mapFn, thisArg))
@@ -26,11 +26,11 @@ exports.asyncMap = function asyncMap(iterable, mapFn, thisArg = iterable) {
 /**
  * Like `asyncMap` but wait for all promises to settle before rejecting
  *
- * @template Item,This
+ * @template Item, Result, [This=Iterable<Item>]
  * @param {Iterable<Item>} iterable
- * @param {(this: This, item: Item) => (Item | PromiseLike<Item>)} mapFn
- * @param {This} [thisArg]
- * @returns {Promise<Item[]>}
+ * @param {(this: This, item: Item) => (Result | PromiseLike<Result>)} mapFn
+ * @param {This} [thisArg] defaults to `iterable`
+ * @returns {Promise<Result[]>}
  */
 exports.asyncMapSettled = function asyncMapSettled(iterable, mapFn, thisArg = iterable) {
   return new Promise((resolve, reject) => {

@xen-orchestra/async-map/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "@xen-orchestra/async-map",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "license": "ISC",
   "description": "Promise.all + map for all iterables",
   "keywords": [

@xen-orchestra/backup-archive/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xen-orchestra/backup-archive",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Helper to handle generic backup archives",
   "license": "ISC",
   "author": "",
@@ -21,25 +21,25 @@
     "tar-stream": "^3.1.8",
     "@types/tar-stream": "^3.1.4",
     "tmp": "^0.2.1",
-    "@vates/types": "^1.30.1"
+    "@vates/types": "^2.3.0"
   },
   "dependencies": {
     "@xen-orchestra/log": "^0.7.1",
-    "@xen-orchestra/fs": "^4.9.3",
+    "@xen-orchestra/fs": "^4.9.5",
     "@xen-orchestra/disk-transform": "^1.3.3",
     "@vates/task": "0.7.0",
     "golike-defer": "0.5.1",
     "uuid": "^9.0.0",
     "promise-toolbox": "^0.21.0",
     "@vates/async-each": "^1.0.1",
-    "vhd-lib": "^4.16.1"
+    "vhd-lib": "^4.16.2"
   },
   "scripts": {
     "build": "yarn run clean && tsc",
     "dev": "tsc --watch",
     "postversion": "npm publish --access public",
     "test": "yarn run clean && tsc && node --test **/*.test.mjs",
-    "test-integration": "yarn run clean && tsc && node --test **/*.integ.mjs",
+    "test-integration": "tsc && node --test **/*.integ.mjs",
     "clean": "rimraf dist/"
   },
   "private": false,

@xen-orchestra/backup-archive/src/BackupCache.mts

@@ -0,0 +1,49 @@
+import { RemoteHandlerAbstract } from '@xen-orchestra/fs'
+import { promisify } from 'node:util'
+import zlib from 'node:zlib'
+
+const gzip = promisify(zlib.gzip)
+const gunzip = promisify(zlib.gunzip)
+
+type LogWarn = (message: any, opts?: object) => void
+
+/**
+ * Reads a gzip-compressed JSON cache file, tolerant of a missing or corrupt file.
+ * Shared with the legacy @xen-orchestra/backups RemoteAdapter.
+ */
+export async function readBackupCache(
+  handler: RemoteHandlerAbstract,
+  path: string,
+  logWarn: LogWarn
+): Promise<Record<string, unknown> | undefined> {
+  try {
+    return JSON.parse((await gunzip(await handler.readFile(path))).toString())
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      logWarn('failed to read cache', { error, path })
+    }
+  }
+}
+
+/**
+ * Writes data as a gzip-compressed JSON cache file.
+ * Shared with the legacy @xen-orchestra/backups RemoteAdapter.
+ *
+ * No-op on immutable remotes: the cache file may not be modifiable there,
+ * and callers should be regenerating/reading the data directly instead.
+ */
+export async function writeBackupCache(
+  handler: RemoteHandlerAbstract,
+  path: string,
+  data: Record<string, unknown>,
+  logWarn: LogWarn
+): Promise<void> {
+  if (handler.isImmutable()) {
+    return
+  }
+  try {
+    await handler.writeFile(path, await gzip(JSON.stringify(data)), { flags: 'w' })
+  } catch (error) {
+    logWarn('failed to write cache', { error, path })
+  }
+}

@xen-orchestra/backup-archive/src/MetadataBackup.mts

@@ -0,0 +1,16 @@
+import { RemoteHandlerAbstract } from '@xen-orchestra/fs'
+
+const METADATA_BACKUP_ID_REGEXP =
+  /^xo-(config|pool-metadata)-backups\/\w{8}(-\w{4}){3}-\w{12}(\/\w{8}(-\w{4}){3}-\w{12})?\/\d{8}T\d{6}Z/
+
+/**
+ * Deletes an XO config or pool metadata backup directory (not a VM backup).
+ * Shared with the legacy @xen-orchestra/backups RemoteAdapter.
+ */
+export async function deleteMetadataBackup(handler: RemoteHandlerAbstract, backupId: string): Promise<void> {
+  if (!METADATA_BACKUP_ID_REGEXP.test(backupId)) {
+    throw new Error(`The id (${backupId}) not correspond to a metadata folder`)
+  }
+
+  await handler.rmtree(backupId)
+}

@xen-orchestra/backup-archive/src/VmBackup.types.mts

@@ -55,6 +55,8 @@ export interface CheckResult {
 
 export type CleanResult = {
   removedFiles: string[]
+  // Files rewritten in place (e.g. metadata whose size was updated after a merge)
+  changedFiles?: string[]
   merge?: boolean
   size?: number
   mergedSizes?: Map<string, number>

@xen-orchestra/backup-archive/src/VmBackupDirectory.mts

@@ -17,11 +17,8 @@ import {
 import { cleanOrphanDiskDirs } from '@xen-orchestra/backup-archive/disks'
 import { asyncEach } from '@vates/async-each'
 import { createLogger } from '@xen-orchestra/log'
-import { promisify } from 'node:util'
-import zlib from 'node:zlib'
-
-const gzip = promisify(zlib.gzip)
-const gunzip = promisify(zlib.gunzip)
+import { readBackupCache, writeBackupCache } from './BackupCache.mjs'
+import { unlinkTolerant } from './_unlinkTolerant.mjs'
 
 const { info: logInfo, warn: logWarn } = createLogger('xo:backup-archive')
 
@@ -30,7 +27,7 @@ const FILES_TO_KEEP = ['cache.json.gz', 'vdis']
 export class VmBackupDirectory implements VmBackupInterface {
   handler: RemoteHandlerAbstract
   rootPath: string
-  files: Array<string> = new Array()
+  files: Array<string> = []
   orphans: Set<string> = new Set()
   backupArchives: Map<string, VmBackupInterface> = new Map()
   opts: ResolvedBackupCleanOptions
@@ -43,6 +40,9 @@ export class VmBackupDirectory implements VmBackupInterface {
   // on disk, so clean() must regenerate it even when nothing was merged/removed.
   #cacheOutOfSync = false
 
+  // Set by #checkCacheCount(): whether cache.json.gz existed at the start of the run.
+  #cacheExisted = false
+
   constructor(
     handler: RemoteHandlerAbstract,
     vmBackupPath: string,
@@ -67,21 +67,11 @@ export class VmBackupDirectory implements VmBackupInterface {
   }
 
   async #readCache(path: string): Promise<Record<string, unknown> | undefined> {
-    try {
-      return JSON.parse((await gunzip(await this.handler.readFile(path))).toString())
-    } catch (error) {
-      if (error?.code !== 'ENOENT') {
-        logWarn('failed to read cache', { error, path })
-      }
-    }
+    return readBackupCache(this.handler, path, logWarn)
   }
 
   async #writeCache(path: string, data: Record<string, unknown>): Promise<void> {
-    try {
-      await this.handler.writeFile(path, await gzip(JSON.stringify(data)), { flags: 'w' })
-    } catch (error) {
-      logWarn('failed to write cache', { error, path })
-    }
+    return writeBackupCache(this.handler, path, data, logWarn)
   }
 
   async init() {
@@ -90,7 +80,7 @@ export class VmBackupDirectory implements VmBackupInterface {
     this.#uniqueLineages = new Map()
 
     for (const fullPath of this.files.filter(path => path.endsWith('.json'))) {
-      let metadata: PartialBackupMetadata | undefined = undefined
+      let metadata: PartialBackupMetadata | undefined
       try {
         metadata = JSON.parse(await this.handler.readFile(fullPath)) satisfies PartialBackupMetadata
       } catch (error) {
@@ -176,18 +166,35 @@ export class VmBackupDirectory implements VmBackupInterface {
 
     // Let each archive clean its own files (e.g. remove metadata for incomplete backups)
     // and update metadata with merged sizes if applicable
+    const archiveRemovedFiles = new Set<string>()
+    const changedFiles = new Set<string>()
+    const goneArchives: string[] = []
     await asyncEach(
-      Array.from(this.backupArchives.values()),
-      async (archive: VmBackupInterface) => {
-        const { removedFiles } = await archive.clean({ remove, mergedSizes: allMergedSizes })
+      Array.from(this.backupArchives.entries()),
+      async ([metadataPath, archive]: [string, VmBackupInterface]) => {
+        const { removedFiles, changedFiles: archiveChangedFiles } = await archive.clean({
+          remove,
+          mergedSizes: allMergedSizes,
+        })
         if (removedFiles.length > 0) {
           cacheNeedsRegen = true
+          removedFiles.forEach(file => archiveRemovedFiles.add(file))
         }
+        if (removedFiles.includes(metadataPath)) {
+          goneArchives.push(metadataPath)
+        }
+        archiveChangedFiles?.forEach(file => changedFiles.add(file))
       },
       { concurrency: 2 }
     )
 
-    if (allMergedSizes.size > 0 || cacheNeedsRegen || this.#cacheOutOfSync) {
+    // an archive whose metadata has just been deleted is not a backup anymore: it must not be
+    // advertised by the regenerated cache
+    for (const metadataPath of goneArchives) {
+      this.backupArchives.delete(metadataPath)
+    }
+
+    if (this.#cacheExisted && (allMergedSizes.size > 0 || cacheNeedsRegen || this.#cacheOutOfSync)) {
       await this.#regenerateCache()
     }
 
@@ -210,13 +217,50 @@ export class VmBackupDirectory implements VmBackupInterface {
       )
     }
     const size = [...allMergedSizes.values()].reduce((total, merged) => total + merged, 0)
-    return { removedFiles: orphans, merge: someLineageMergedOrShouldBe, size: size }
+    // `removedFiles` lists the files this run removed, or would have removed if `remove` were set:
+    // root-level orphans plus the files each archive deemed removable (e.g. the metadata of an
+    // incomplete backup). Callers acting on it must therefore check `remove` themselves.
+    orphans.forEach(orphan => archiveRemovedFiles.add(orphan))
+    return {
+      removedFiles: Array.from(archiveRemovedFiles),
+      changedFiles: Array.from(changedFiles),
+      merge: someLineageMergedOrShouldBe,
+      size: size,
+    }
   }
 
   async #checkCacheCount(): Promise<void> {
     const cachePath = `${this.rootPath}/cache.json.gz`
+
+    this.#cacheExisted = false
+    this.#cacheOutOfSync = false
+
+    if (!this.files.includes(normalize(cachePath))) {
+      return
+    }
+
+    if (this.handler.isImmutable()) {
+      // RemoteAdapter never creates cache.json.gz on immutable repositories: remove the
+      // leftover, readable or not, and never regenerate it. Best effort: some remotes
+      // (e.g. S3) may not normalize a permission error to EPERM, so tolerate any error.
+      try {
+        await this.handler.unlink(cachePath)
+      } catch (error) {
+        this.opts.logWarn('error while deleting leftover backup cache', { path: cachePath, error })
+      }
+      return
+    }
+
     const existingCache = await this.#readCache(cachePath)
-    const actual = existingCache === undefined ? 0 : Object.keys(existingCache).length
+    if (existingCache === undefined) {
+      // present but unreadable: drop it, RemoteAdapter will recreate a valid one
+      this.opts.logWarn('removing unreadable backup cache', { path: cachePath })
+      await unlinkTolerant(this.handler, cachePath)
+      return
+    }
+
+    this.#cacheExisted = true
+    const actual = Object.keys(existingCache).length
     const expected = this.backupArchives.size
     this.#cacheOutOfSync = actual !== expected
     if (this.#cacheOutOfSync) {
@@ -283,7 +327,6 @@ export class VmBackupDirectory implements VmBackupInterface {
     const dir = new VmBackupDirectory(handler, vmBackupPath, cleanOpts)
     await dir.init()
     await dir.check()
-    const { merge, size } = await dir.clean({ remove: cleanOpts.remove, merge: cleanOpts.merge })
-    return { merge, size }
+    return await dir.clean({ remove: cleanOpts.remove, merge: cleanOpts.merge })
   }
 }

@xen-orchestra/backup-archive/src/VmFullBackupArchive.integ.mjs

@@ -10,8 +10,13 @@ import { rimraf } from 'rimraf'
 // eslint-disable-next-line n/no-missing-import
 import { VmBackupDirectory } from '../dist/VmBackupDirectory.mjs'
 import tar from 'tar-stream'
+import { promisify } from 'node:util'
+import zlib from 'node:zlib'
 const { beforeEach, afterEach, describe } = test
 
+const gzip = promisify(zlib.gzip)
+const gunzip = promisify(zlib.gunzip)
+
 let tempDir, handler, vmBackupDir
 const vmUuid = 'test-vm-uuid'
 const rootPath = `xo-vm-backups/${vmUuid}`
@@ -124,7 +129,10 @@ describe('VmBackupDirectory with full backups', { concurrency: 1 }, () => {
 
   test('clean() preserves cache.json.gz', async () => {
     await createFullBackupMetadata('backup1.json', 'backup1.xva')
-    await handler.writeFile(`${rootPath}/cache.json.gz`, 'cache')
+    await handler.writeFile(
+      `${rootPath}/cache.json.gz`,
+      await gzip(JSON.stringify({ [`/${rootPath}/backup1.json`]: {} }))
+    )
 
     await VmBackupDirectory.cleanVm(handler, rootPath)
 
@@ -133,6 +141,104 @@ describe('VmBackupDirectory with full backups', { concurrency: 1 }, () => {
     assert.ok(remainingFiles.includes('cache.json.gz'))
   })
 
+  test('clean() removes an unreadable cache.json.gz', async () => {
+    await createFullBackupMetadata('backup1.json', 'backup1.xva')
+    await handler.writeFile(`${rootPath}/cache.json.gz`, 'not gzipped json')
+
+    await VmBackupDirectory.cleanVm(handler, rootPath, { logWarn: () => {} })
+
+    const remainingFiles = await handler.list(rootPath)
+    assert.ok(!remainingFiles.includes('cache.json.gz'), 'an unreadable cache.json.gz should be removed, not kept')
+  })
+
+  test('clean() on an immutable remote never creates cache.json.gz', async () => {
+    await createFullBackupMetadata('backup1.json', 'backup1.xva')
+    await handler.writeFile(`${rootPath}/orphan.xva`, 'orphan-content')
+    handler.isImmutable = () => true
+
+    await VmBackupDirectory.cleanVm(handler, rootPath, { remove: true })
+
+    const remainingFiles = await handler.list(rootPath)
+    assert.ok(!remainingFiles.includes('cache.json.gz'), 'cache.json.gz should never be created on an immutable remote')
+  })
+
+  test('clean() removes a leftover cache.json.gz found on an immutable remote', async () => {
+    await createFullBackupMetadata('backup1.json', 'backup1.xva')
+    await handler.writeFile(`${rootPath}/cache.json.gz`, await gzip(JSON.stringify({})))
+    handler.isImmutable = () => true
+
+    await VmBackupDirectory.cleanVm(handler, rootPath)
+
+    const remainingFiles = await handler.list(rootPath)
+    assert.ok(!remainingFiles.includes('cache.json.gz'), 'erroneous cache.json.gz should be removed, not rewritten')
+  })
+
+  test('clean() removes an unreadable leftover cache.json.gz found on an immutable remote', async () => {
+    await createFullBackupMetadata('backup1.json', 'backup1.xva')
+    await handler.writeFile(`${rootPath}/cache.json.gz`, 'not gzipped json')
+    handler.isImmutable = () => true
+
+    await VmBackupDirectory.cleanVm(handler, rootPath)
+
+    const remainingFiles = await handler.list(rootPath)
+    assert.ok(
+      !remainingFiles.includes('cache.json.gz'),
+      'an unreadable cache.json.gz should be removed from an immutable remote'
+    )
+  })
+
+  test('clean() tolerates an EPERM while removing the cache of an immutable remote', async () => {
+    await createFullBackupMetadata('backup1.json', 'backup1.xva')
+    await handler.writeFile(`${rootPath}/cache.json.gz`, await gzip(JSON.stringify({})))
+    handler.isImmutable = () => true
+    handler.unlink = () => {
+      const error = new Error('EPERM: operation not permitted')
+      error.code = 'EPERM'
+      throw error
+    }
+
+    await VmBackupDirectory.cleanVm(handler, rootPath)
+
+    const remainingFiles = await handler.list(rootPath)
+    assert.ok(remainingFiles.includes('cache.json.gz'), 'the immutable cache.json.gz could not be removed')
+  })
+
+  test('clean() keeps maintaining a pre-existing cache.json.gz across a remove', async () => {
+    await createFullBackupMetadata('backup1.json', 'backup1.xva')
+    await createFullBackupMetadata('backup2.json', 'backup2.xva')
+
+    // a cache with the expected number of entries: only the removal can trigger the regeneration
+    const cachePath = `${rootPath}/cache.json.gz`
+    await handler.writeFile(
+      cachePath,
+      await gzip(
+        JSON.stringify({
+          [`/${rootPath}/backup1.json`]: { stale: true },
+          [`/${rootPath}/backup2.json`]: { stale: true },
+        })
+      )
+    )
+
+    // backup2 loses its XVA: its metadata will be removed by clean()
+    await handler.unlink(`${rootPath}/backup2.xva`)
+
+    await VmBackupDirectory.cleanVm(handler, rootPath, { remove: true, logInfo: () => {}, logWarn: () => {} })
+
+    const remainingFiles = await handler.list(rootPath)
+    assert.ok(remainingFiles.includes('backup1.json'))
+    assert.ok(remainingFiles.includes('backup1.xva'))
+    assert.ok(!remainingFiles.includes('backup2.json'), 'metadata of the backup with a missing XVA should be removed')
+    assert.ok(remainingFiles.includes('cache.json.gz'), 'an existing cache.json.gz must not be dropped by a remove')
+
+    const cache = JSON.parse((await gunzip(await handler.readFile(cachePath))).toString())
+    assert.deepEqual(
+      Object.keys(cache),
+      [`/${rootPath}/backup1.json`],
+      'cache.json.gz should have been regenerated with the surviving backup only'
+    )
+    assert.equal(cache[`/${rootPath}/backup1.json`].stale, undefined, 'the entry must come from the archive on disk')
+  })
+
   test('clean() removes an orphan XVA checksum file (no matching metadata or XVA)', async () => {
     await handler.writeFile(`${rootPath}/stray.xva.checksum`, 'sha256:deadbeef')
 

@xen-orchestra/backup-archive/src/VmFullBackupArchive.mts

@@ -1,6 +1,6 @@
-import { basename, normalize } from '@xen-orchestra/fs/path'
+import { basename, normalize, resolveFromFile } from '@xen-orchestra/fs/path'
 import assert from 'node:assert'
-import { FileDescriptor } from '@xen-orchestra/fs'
+import { FileDescriptor, RemoteHandlerAbstract } from '@xen-orchestra/fs'
 import {
   ArchiveCleanOptions,
   CheckResult,
@@ -8,8 +8,10 @@ import {
   VmBackupInterface,
   PartialBackupMetadata,
   ResolvedBackupCleanOptions,
+  DEFAULT_REMOVE_CONCURRENCY,
 } from './VmBackup.types.mjs'
-import { RemoteHandlerAbstract } from '@xen-orchestra/fs'
+import { asyncEach } from '@vates/async-each'
+import { unlinkTolerant } from './_unlinkTolerant.mjs'
 
 const COMPRESSED_MAGIC_NUMBERS: Buffer[] = [
   // https://tools.ietf.org/html/rfc1952.html#page-5
@@ -80,6 +82,29 @@ export async function isValidXva(
 
 const noop = (): void => {}
 
+/**
+ * Deletes a full VM backup's metadata json and, when provided, its xva and checksum.
+ * `xva` is the path as stored in the metadata, i.e. relative to the metadata file.
+ * Shared with the legacy @xen-orchestra/backups RemoteAdapter.
+ */
+export async function deleteFullVmBackups(
+  handler: RemoteHandlerAbstract,
+  backups: Array<{ metadataPath: string; xva?: string }>
+): Promise<void> {
+  await asyncEach(
+    backups,
+    async ({ metadataPath, xva }) => {
+      await unlinkTolerant(handler, metadataPath)
+      if (xva !== undefined) {
+        const xvaPath = resolveFromFile(metadataPath, xva)
+        await unlinkTolerant(handler, xvaPath)
+        await unlinkTolerant(handler, `${xvaPath}.checksum`)
+      }
+    },
+    { concurrency: DEFAULT_REMOVE_CONCURRENCY, stopOnError: false }
+  )
+}
+
 export class VmFullBackupArchive implements VmBackupInterface {
   handler: RemoteHandlerAbstract
   rootPath: string
@@ -158,12 +183,10 @@ export class VmFullBackupArchive implements VmBackupInterface {
             files: this.getAssociatedFiles({ prefix: false }),
           })
         } else {
-          for (const file of removedFiles) {
-            try {
-              await this.handler.unlink(file)
-            } catch (error) {
-              this.opts.logWarn(`Issue removing ${file}`, { error })
-            }
+          try {
+            await deleteFullVmBackups(this.handler, [{ metadataPath: this.metadataPath, xva: this.metadata.xva }])
+          } catch (error) {
+            this.opts.logWarn(`Issue removing backup files`, { error, metadataPath: this.metadataPath })
           }
         }
       }
@@ -173,7 +196,7 @@ export class VmFullBackupArchive implements VmBackupInterface {
   }
 
   getAssociatedFiles({ prefix = false }): Array<string> {
-    let validFiles = [this.metadataPath, this.xvaPath, `${this.xvaPath}.checksum`]
+    const validFiles = [this.metadataPath, this.xvaPath, `${this.xvaPath}.checksum`]
     return prefix ? validFiles : validFiles.map(file => basename(file))
   }
 }

@xen-orchestra/backup-archive/src/VmIncrementalBackupArchive.integ.mjs

@@ -6,10 +6,13 @@ import fs from 'fs-extra'
 import * as uuid from 'uuid'
 import { getHandler } from '@xen-orchestra/fs'
 import { pFromCallback } from 'promise-toolbox'
-// eslint-disable-next-line n/no-missing-import
+// `dist/` is built by the `test-integration` script, which starts by removing it: these imports
+// cannot be resolved when linting a working tree that has not been built yet
+/* eslint-disable n/no-missing-import */
 import { VmBackupDirectory } from '../dist/VmBackupDirectory.mjs'
 import { RemoteVhdDisk } from '../dist/disks/RemoteVhdDisk.mjs'
 import { MergeRemoteDisk } from '../dist/disks/MergeRemoteDisk.mjs'
+/* eslint-enable n/no-missing-import */
 import { VHDFOOTER, VHDHEADER } from './tests.fixtures.mjs'
 import { VhdFile, Constants, VhdDirectory, VhdAbstract } from 'vhd-lib'
 import { dirname, basename } from 'node:path'
@@ -20,6 +23,7 @@ import { rimraf } from 'rimraf'
 const { beforeEach, afterEach, describe } = test
 
 const gunzip = promisify(zlib.gunzip)
+const gzip = promisify(zlib.gzip)
 
 let tempDir, handler, jobId, vdiId, basePath, relativePath, vdiId2, basePath2, relativePath2
 const rootPath = 'xo-vm-backups/VMUUID/'
@@ -205,8 +209,8 @@ test('it remove backup metadata referencing a missing vhd in delta backup', asyn
   assert.equal(matched.length, 2) // all vhds (orphan and  child  ) should have been deleted
 
   assert.ok(
-    (await handler.list(rootPath)).includes('cache.json.gz'),
-    'cache.json.gz should be regenerated after metadata deletion'
+    !(await handler.list(rootPath)).includes('cache.json.gz'),
+    'cache.json.gz should not be created when none existed before the clean'
   )
 })
 
@@ -364,7 +368,6 @@ test('it merges delta of non destroyed chain', async () => {
     logged.push(message)
   }
   await VmBackupDirectory.cleanVm(handler, rootPath, { remove: true, logInfo, logWarn: logInfo })
-  assert.equal(logged[0], `unexpected number of entries in backup cache`)
 
   logged = []
   await VmBackupDirectory.cleanVm(handler, rootPath, { remove: true, merge: true, logInfo, logWarn: () => {} })
@@ -726,10 +729,10 @@ describe('tests multiple combination ', { concurrency: 1 }, () => {
         const metadata = JSON.parse(await handler.readFile(`${rootPath}/metadata.json`))
         // size should be the size of children + grand children + clean after the merge
         assert.deepEqual(metadata.size, 6501888)
-        // cache.json.gz must be regenerated when metadata changes after a merge
+        // no cache.json.gz existed before this run, so a merge must not create one
         assert.ok(
-          (await handler.list(rootPath)).includes('cache.json.gz'),
-          'cache.json.gz should be regenerated after a merge'
+          !(await handler.list(rootPath)).includes('cache.json.gz'),
+          'cache.json.gz should not be created when none existed before the merge'
         )
 
         // broken vhd, non referenced, abandoned should be deleted ( alias and data)
@@ -833,7 +836,7 @@ test('it preserves VDI directory when handler.list() throws during lineage init'
   assert.ok(remaining.includes('snapshot.vhd'), 'VHD must survive when handler.list() throws during lineage init')
 })
 
-test('it regenerates the cache when its entry count is out of sync, even with nothing to merge/remove', async () => {
+test('it does not create nor warn about the cache when none existed, even with a count mismatch', async () => {
   // a referenced disk + its metadata, but no cache.json.gz on disk
   await generateVhd(`${basePath}/diskA1.vhd`)
   await handler.writeFile(
@@ -842,6 +845,79 @@ test('it regenerates the cache when its entry count is out of sync, even with no
   )
   await assert.rejects(handler.readFile(`${rootPath}/cache.json.gz`), { code: 'ENOENT' })
 
+  const logged = []
+  // remove/merge both false: cacheNeedsRegen stays false and no merge happens,
+  // so only a pre-existing cache's count mismatch could trigger regeneration
+  await VmBackupDirectory.cleanVm(handler, rootPath, {
+    remove: false,
+    merge: false,
+    logInfo: () => {},
+    logWarn: message => logged.push(message),
+  })
+
+  assert.ok(!logged.includes('unexpected number of entries in backup cache'), 'no cache to be mismatched, no warning')
+  await assert.rejects(handler.readFile(`${rootPath}/cache.json.gz`), { code: 'ENOENT' })
+})
+
+test('it regenerates a pre-existing cache after a merge', async () => {
+  await handler.writeFile(
+    `${rootPath}/metadata.json`,
+    JSON.stringify({
+      mode: 'delta',
+      size: 12000, // a size too small, the merge will fix it
+      vhds: [`${relativePath}/grandchild.vhd`, `${relativePath}/child.vhd`],
+    })
+  )
+
+  // one orphan, which is a full vhd, no parent
+  const orphan = await generateVhd(`${basePath}/orphan.vhd`)
+  // a child to the orphan, orphan will be merged into it
+  const child = await generateVhd(`${basePath}/child.vhd`, {
+    header: {
+      parentUnicodeName: 'orphan.vhd',
+      parentUuid: orphan.footer.uuid,
+    },
+    blocks: [0, 1],
+  })
+  await generateVhd(`${basePath}/grandchild.vhd`, {
+    header: {
+      parentUnicodeName: 'child.vhd',
+      parentUuid: child.footer.uuid,
+    },
+  })
+
+  // a cache with the expected number of entries: it is not out of sync, only the merge can trigger the regeneration
+  await handler.writeFile(
+    `${rootPath}/cache.json.gz`,
+    await gzip(JSON.stringify({ [`/${rootPath}metadata.json`]: { size: 12000 } }))
+  )
+
+  const result = await VmBackupDirectory.cleanVm(handler, rootPath, {
+    remove: true,
+    merge: true,
+    logInfo: () => {},
+    logWarn: () => {},
+  })
+
+  const metadata = JSON.parse(await handler.readFile(`${rootPath}/metadata.json`))
+  // size of child + grandchild after orphan has been merged into child
+  assert.equal(metadata.size, 4299776, 'metadata.size should be updated after merge')
+  assert.deepEqual(result.changedFiles, [`/${rootPath}metadata.json`], 'the rewritten metadata should be reported')
+
+  const cache = JSON.parse((await gunzip(await handler.readFile(`${rootPath}/cache.json.gz`))).toString())
+  assert.equal(Object.keys(cache).length, 1)
+  assert.equal(Object.values(cache)[0].size, metadata.size, 'cache entry should carry the post-merge size')
+})
+
+test('it regenerates a pre-existing cache when its entry count is out of sync, even with nothing to merge/remove', async () => {
+  // a referenced disk + its metadata, and a pre-existing cache with the wrong entry count
+  await generateVhd(`${basePath}/diskA1.vhd`)
+  await handler.writeFile(
+    `${rootPath}/metadata.json`,
+    JSON.stringify({ mode: 'delta', vhds: [`${relativePath}/diskA1.vhd`] })
+  )
+  await handler.writeFile(`${rootPath}/cache.json.gz`, await gzip(JSON.stringify({})))
+
   const logged = []
   // remove/merge both false: cacheNeedsRegen stays false and no merge happens,
   // so only the cache-count mismatch can trigger the regeneration
@@ -857,3 +933,53 @@ test('it regenerates the cache when its entry count is out of sync, even with no
   const cache = JSON.parse((await gunzip(await handler.readFile(`${rootPath}/cache.json.gz`))).toString())
   assert.equal(Object.keys(cache).length, 1, 'cache should be regenerated to match the archives on disk')
 })
+
+test('it regenerates a pre-existing cache after a metadata removal', async () => {
+  // two backups, each on its own VDI directory, so removing one does not touch the other's disks
+  await generateVhd(`${basePath}/diskA1.vhd`)
+  await handler.writeFile(
+    `${rootPath}/metadata1.json`,
+    JSON.stringify({ mode: 'delta', vhds: [`${relativePath}/diskA1.vhd`] })
+  )
+  // metadata2 references a vhd missing from disk: clean() removes it
+  await handler.writeFile(
+    `${rootPath}/metadata2.json`,
+    JSON.stringify({ mode: 'delta', vhds: [`${relativePath2}/deleted.vhd`] })
+  )
+
+  // a cache with the expected number of entries: only the removal can trigger the regeneration
+  await handler.writeFile(
+    `${rootPath}/cache.json.gz`,
+    await gzip(
+      JSON.stringify({
+        [`/${rootPath}metadata1.json`]: { stale: true },
+        [`/${rootPath}metadata2.json`]: { stale: true },
+      })
+    )
+  )
+
+  const logged = []
+  await VmBackupDirectory.cleanVm(handler, rootPath, {
+    remove: true,
+    merge: false,
+    logInfo: () => {},
+    logWarn: message => logged.push(message),
+  })
+
+  const rootFiles = await handler.list(rootPath)
+  assert.ok(rootFiles.includes('metadata1.json'), 'the complete backup must survive')
+  assert.ok(!rootFiles.includes('metadata2.json'), 'the backup with a missing vhd must be removed')
+  assert.ok(rootFiles.includes('cache.json.gz'), 'an existing cache.json.gz must not be dropped by a remove')
+  assert.ok(
+    !logged.includes('unexpected number of entries in backup cache'),
+    'the cache matched the archives before the clean: the removal alone must trigger the regeneration'
+  )
+
+  const cache = JSON.parse((await gunzip(await handler.readFile(`${rootPath}/cache.json.gz`))).toString())
+  assert.deepEqual(
+    Object.keys(cache),
+    [`/${rootPath}metadata1.json`],
+    'the removed backup must be gone from the regenerated cache'
+  )
+  assert.equal(cache[`/${rootPath}metadata1.json`].stale, undefined, 'the entry must come from the archive on disk')
+})

@xen-orchestra/backup-archive/src/VmIncrementalBackupArchive.mts

@@ -5,10 +5,27 @@ import {
   ResolvedBackupCleanOptions,
   VmBackupInterface,
   PartialBackupMetadata,
+  DEFAULT_REMOVE_CONCURRENCY,
 } from './VmBackup.types.mjs'
 import { RemoteHandlerAbstract } from '@xen-orchestra/fs'
 import { basename, dirname, normalize } from '@xen-orchestra/fs/path'
 import { RemoteDiskLineage } from './RemoteDiskLineage.mjs'
+import { asyncEach } from '@vates/async-each'
+
+/**
+ * Deletes a delta VM backup's metadata json. Unused VHDs are detected and removed
+ * separately by VmBackupDirectory's clean(). Shared with the legacy @xen-orchestra/backups
+ * RemoteAdapter.
+ */
+export async function deleteDeltaVmBackups(
+  handler: RemoteHandlerAbstract,
+  backups: Array<{ metadataPath: string }>
+): Promise<void> {
+  await asyncEach(backups, ({ metadataPath }) => handler.unlink(metadataPath), {
+    concurrency: DEFAULT_REMOVE_CONCURRENCY,
+    stopOnError: false,
+  })
+}
 
 export class VmIncrementalBackupArchive implements VmBackupInterface {
   handler: RemoteHandlerAbstract
@@ -132,6 +149,7 @@ export class VmIncrementalBackupArchive implements VmBackupInterface {
       }
     }
 
+    const changedFiles: string[] = []
     let mergedSize = 0
     if (mergedSizes !== undefined) {
       for (const diskPath of this.diskPaths) {
@@ -139,10 +157,11 @@ export class VmIncrementalBackupArchive implements VmBackupInterface {
       }
       if (mergedSize > 0) {
         await this.updateMetadata(mergedSize)
+        changedFiles.push(this.metadataPath)
       }
     }
 
-    return { removedFiles }
+    return { removedFiles, changedFiles }
   }
 
   /**

@xen-orchestra/backup-archive/src/_unlinkTolerant.mts

@@ -0,0 +1,20 @@
+import { RemoteHandlerAbstract } from '@xen-orchestra/fs'
+
+/**
+ * Deletes a file, ignoring the given error codes.
+ * By default only a missing file is tolerated.
+ */
+export async function unlinkTolerant(
+  handler: RemoteHandlerAbstract,
+  path: string,
+  ignoredCodes: string[] = ['ENOENT']
+): Promise<void> {
+  try {
+    await handler.unlink(path)
+  } catch (error) {
+    if (!ignoredCodes.includes(error?.code)) {
+      error.path ??= path
+      throw error
+    }
+  }
+}

@xen-orchestra/backup-archive/src/disks/RemoteDisk.mjs

@@ -229,6 +229,21 @@ export class RemoteDisk extends RandomAccessDisk {
     throw new Error(`isDifferencing must be implemented`)
   }
 
+  /**
+   * Checks whether this disk (or chain) can act as the merge-target parent for a disk
+   * about to be written with the given reference configuration.
+   *
+   * Base check: this disk's own uuid matches the expected parent uuid. Subclasses should
+   * override to add implementation-specific compatibility checks (storage sub-format,
+   * compression, ...) — calling `super.isMergeableParent()` first.
+   *
+   * @param {string} parentUuid
+   * @returns {Promise<boolean>}
+   */
+  async isMergeableParent(parentUuid) {
+    return this.getUuid() === parentUuid
+  }
+
   /**
    * Abstract
    * Rename alias/disk

@xen-orchestra/backup-archive/src/disks/RemoteVhdDisk.mjs

@@ -81,12 +81,13 @@ export class RemoteVhdDisk extends RemoteDisk {
         })
         this.#vhd = value
 
+        this.#dispose = dispose
+
         if ((await this.isDirectory()) && !isVhdAlias(this.#path)) {
           this.#vhd = undefined
           throw Object.assign(new Error("Can't init vhd directory without using alias"), { code: 'NOT_SUPPORTED' })
         }
 
-        this.#dispose = dispose
         if (!options.ignoreBlockIndexes) {
           await this.#vhd.readBlockAllocationTable()
         }
@@ -433,6 +434,36 @@ export class RemoteVhdDisk extends RemoteDisk {
     return this.#isDifferencing
   }
 
+  /**
+   * Returns the compression codec id. Only meaningful for VHD directories;
+   * undefined for plain VHDs.
+   * @returns {string | undefined}
+   */
+  #getCompressionType() {
+    if (this.#vhd === undefined) {
+      throw new Error(`can't check compressionType of a RemoteVhdDisk before init`)
+    }
+    return this.#vhd instanceof VhdDirectory ? this.#vhd.compressionType : undefined
+  }
+
+  /**
+   * Adds VHD-specific compatibility checks on top of the uuid check: the storage
+   * sub-format (VHD directory vs plain) and, for directories, the compression codec
+   * must match what this remote would write for a new disk.
+   * @param {string} parentUuid
+   * @returns {Promise<boolean>}
+   */
+  async isMergeableParent(parentUuid) {
+    if (!(await super.isMergeableParent(parentUuid))) {
+      return false
+    }
+
+    const useVhdDirectory = this.#handler.getConfig('useVhdDirectory') ?? false
+    const compressionType = this.#handler.getConfig('compressionType') ?? 'brotli'
+    const isDirectory = await this.isDirectory()
+    return isDirectory ? useVhdDirectory && this.#getCompressionType() === compressionType : !useVhdDirectory
+  }
+
   /**
    * Rename alias/disk
    * @param {string} newPath

@xen-orchestra/backup-archive/src/index.mts

@@ -1 +1,5 @@
 export { VmBackupDirectory } from './VmBackupDirectory.mjs'
+export { deleteFullVmBackups } from './VmFullBackupArchive.mjs'
+export { deleteDeltaVmBackups } from './VmIncrementalBackupArchive.mjs'
+export { deleteMetadataBackup } from './MetadataBackup.mjs'
+export { readBackupCache, writeBackupCache } from './BackupCache.mjs'

@xen-orchestra/backup-archive/tsconfig.json

@@ -14,5 +14,6 @@
     "types": ["node"] // Only use types from Node.js and packages that are explicitly imported
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  // *.integ.mjs deliberately imports from the built dist/ output to test it
+  "exclude": ["node_modules", "dist", "**/*.integ.mjs"]
 }

@xen-orchestra/backups-cli/package.json

@@ -7,9 +7,9 @@
   "bugs": "https://github.com/vatesfr/xen-orchestra/issues",
   "dependencies": {
     "@vates/async-each": "^1.0.3",
-    "@xen-orchestra/async-map": "^0.1.3",
-    "@xen-orchestra/backups": "^0.73.10",
-    "@xen-orchestra/fs": "^4.9.3",
+    "@xen-orchestra/async-map": "^0.1.5",
+    "@xen-orchestra/backups": "^0.76.0",
+    "@xen-orchestra/fs": "^4.9.5",
     "filenamify": "^6.0.0",
     "getopts": "^2.2.5",
     "lodash": "^4.18.0",
@@ -28,7 +28,7 @@
   "scripts": {
     "postversion": "npm publish --access public"
   },
-  "version": "1.1.13",
+  "version": "1.1.16",
   "license": "AGPL-3.0-or-later",
   "author": {
     "name": "Vates SAS",

@xen-orchestra/backups/.USAGE.md

@@ -1,3 +1,10 @@
+## Documentation
+
+- [VM backups](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/VM%20backups/README.md): file structure on a remote, XAPI attributes, task logs, run description object, writer API
+- [Incremental replication](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/VM%20backups/incrementalReplication.md): how CR selects its target VM and VDIs
+- [Metadata backups](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/Metadata%20backups/README.md): file structure on a remote, structure of `metadata.json`, task logs
+- [Health check](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/healthcheck/example.sh): example guest script reporting to xenstore
+
 ## Changing the default backup configuration
 
 This library receives a backup configuration from `xo-server` or `xo-proxy`. This configuration is split between multiple properties:

@xen-orchestra/backups/ImportVmBackup.mjs

@@ -10,6 +10,7 @@ import { dirname, join } from 'node:path'
 import pickBy from 'lodash/pickBy.js'
 import { defer } from 'golike-defer'
 import { NegativeDisk } from '@xen-orchestra/disk-transform'
+import { normalizeVdiRestoreTargets } from './_vdiRestoreTargets.mjs'
 import { openDiskChain } from '@xen-orchestra/backup-archive/disks'
 import { resetVmOtherConfig } from './_otherConfig.mjs'
 
@@ -25,20 +26,54 @@ async function resolveUuid(xapi, cache, uuid, type) {
   return cache.get(uuid)
 }
 export class ImportVmBackup {
+  // live mounts created by this restore, with the host they are attached to, so a failure can
+  // release them and a success can report them to the caller, which is the one keeping track of them
+  #liveMounts = []
+
+  // ref of the host serving the live mounts, resolved once on the destination pool
+  #liveMountHostRef
+
+  /**
+   * @param {object} params
+   * @param {object} params.adapter - remote adapter of the backup repository
+   * @param {object} params.metadata - metadata of the backup to restore
+   * @param {string} params.srUuid - SR the disks are restored to, unless a per disk target says otherwise
+   * @param {object} params.xapi - XAPI connection of the pool owning `srUuid`
+   * @param {object} [params.liveMount] - how to serve a disk from the backup repository instead of
+   * copying it, injected by the caller since a live mount outlives the restore and cannot be run
+   * from this package
+   * @param {({ diskPath, hostId }) => Promise<{ id: string, vdiUuid: string }>} params.liveMount.mountDisk
+   * @param {(id: string) => Promise<void>} params.liveMount.unmountDisk
+   * @param {object} [params.settings]
+   */
   constructor({
     adapter,
+    liveMount,
     metadata,
     srUuid,
     xapi,
-    settings: { additionalVmTag, newMacAddresses, mapVdisSrs = {}, useDifferentialRestore = false } = {},
+    settings: { additionalVmTag, newMacAddresses, mapVdisSrs = {}, useDifferentialRestore = false, vmNamePrefix } = {},
   }) {
     this._adapter = adapter
-    this._importIncrementalVmSettings = { additionalVmTag, newMacAddresses, mapVdisSrs, useDifferentialRestore }
+    this._importIncrementalVmSettings = {
+      additionalVmTag,
+      newMacAddresses,
+      useDifferentialRestore,
+      vmNamePrefix,
+    }
+    this._liveMount = liveMount
     this._metadata = metadata
     this._srUuid = srUuid
+    this._vdiRestoreTargets = normalizeVdiRestoreTargets(mapVdisSrs, { useDifferentialRestore })
     this._xapi = xapi
   }
 
+  /** SR a disk must be restored to, the restore's default one unless its target names another */
+  #getTargetSrUuid(vdiUuid) {
+    const target = this._vdiRestoreTargets.get(vdiUuid)
+    return (target.type === 'restore' ? target.sr : undefined) ?? this._srUuid
+  }
+
   async #getPathOfVdiSnapshot(snapshotUuid) {
     const metadata = this._metadata
     if (this._pathToVdis === undefined) {
@@ -57,13 +92,13 @@ export class ImportVmBackup {
     return this._pathToVdis.get(snapshotUuid)
   }
 
-  async _reuseNearestSnapshot($defer, ignoredVdis) {
+  async _reuseNearestSnapshot($defer, excludedVdiUuids) {
     const metadata = this._metadata
-    const { mapVdisSrs } = this._importIncrementalVmSettings
     const { vbds, vhds, vifs, vm, vmSnapshot, vtpms } = metadata
     const disks = {}
     const metadataDir = dirname(metadata._filename)
-    const vdis = ignoredVdis === undefined ? metadata.vdis : pickBy(metadata.vdis, vdi => !ignoredVdis.has(vdi.uuid))
+    const vdis =
+      excludedVdiUuids === undefined ? metadata.vdis : pickBy(metadata.vdis, vdi => !excludedVdiUuids.has(vdi.uuid))
 
     for (const [vdiRef, vdi] of Object.entries(vdis)) {
       const vhdPath = join(metadataDir, vhds[vdiRef])
@@ -100,8 +135,11 @@ export class ImportVmBackup {
             debug('no backup linked to this snapshot')
             continue
           }
-          if (snapshot.$SR.uuid !== (mapVdisSrs[vdi.$snapshot_of$uuid] ?? this._srUuid)) {
-            debug('not restored on the same SR', { snapshotSr: snapshot.$SR.uuid, mapVdisSrs, srUuid: this._srUuid })
+          // reusing a snapshot means cloning it, and a clone lands on the SR of its source: a
+          // snapshot which is not on the SR this disk is restored to is not a usable base
+          const targetSrUuid = this.#getTargetSrUuid(vdi.uuid)
+          if (snapshot.$SR.uuid !== targetSrUuid) {
+            debug('not restored on the same SR', { snapshotSr: snapshot.$SR.uuid, targetSrUuid })
             continue
           }
 
@@ -194,52 +232,192 @@ export class ImportVmBackup {
     }
   }
 
-  async #decorateIncrementalVmMetadata() {
-    const { additionalVmTag, mapVdisSrs, useDifferentialRestore } = this._importIncrementalVmSettings
+  async _decorateIncrementalVmMetadata() {
+    const { additionalVmTag, useDifferentialRestore } = this._importIncrementalVmSettings
+    const targets = this._vdiRestoreTargets
+
+    this.#checkTargetsMatchBackup()
+
+    // a live mounted disk stays on the backup repository and is served from there, so it is left
+    // out of the disks to read, exactly like an ignored one, then added back below
+    const liveMountedVdiUuids = targets.getLiveMountedVdiUuids()
+    const excludedVdiUuids = new Set([...targets.getIgnoredVdiUuids(), ...liveMountedVdiUuids])
 
-    const ignoredVdis = new Set(
-      Object.entries(mapVdisSrs)
-        .filter(([_, srUuid]) => srUuid === null)
-        .map(([vdiUuid]) => vdiUuid)
-    )
     let backup
     if (useDifferentialRestore) {
-      backup = await this._reuseNearestSnapshot(ignoredVdis)
+      backup = await this._reuseNearestSnapshot(excludedVdiUuids)
     } else {
-      backup = await this._adapter.readIncrementalVmBackup(this._metadata, ignoredVdis)
+      backup = await this._adapter.readIncrementalVmBackup(this._metadata, excludedVdiUuids)
     }
     const xapi = this._xapi
 
     const cache = new Map()
-    const mapVdisSrRefs = {}
     if (additionalVmTag !== undefined) {
       backup.vm.tags.push(additionalVmTag)
     }
-    for (const [vdiUuid, srUuid] of Object.entries(mapVdisSrs)) {
-      mapVdisSrRefs[vdiUuid] = await resolveUuid(xapi, cache, srUuid, 'SR')
+    for (const vdi of Object.values(backup.vdis)) {
+      vdi.SR = await resolveUuid(xapi, cache, this.#getTargetSrUuid(vdi.uuid), 'SR')
     }
-    const srRef = await resolveUuid(xapi, cache, this._srUuid, 'SR')
-    Object.values(backup.vdis).forEach(vdi => {
-      vdi.SR = mapVdisSrRefs[vdi.uuid] ?? srRef
-    })
+
+    // after the SR resolution: a live mounted VDI already exists, it is not created on any SR
+    await this.#addLiveMountedVdis(backup)
+
     return backup
   }
 
-  async run() {
+  /**
+   * Reject a restore whose targets name disks this backup does not contain.
+   *
+   * An unknown uuid is a mistake in every case — a stale `mapVdisSrs`, a uuid taken from the
+   * running VM instead of the backup — but it is only fatal for a live mount: that target is new,
+   * and silently restoring the disk the usual way would copy the very data the caller asked not
+   * to. The historical targets keep their lenient behavior, so a restore which used to work still
+   * does, and say so in the logs.
+   */
+  #checkTargetsMatchBackup() {
+    const backedUpVdiUuids = new Set(Object.values(this._metadata.vdis ?? {}).map(vdi => vdi.uuid))
+
+    const unknownLiveMounted = []
+    for (const [vdiUuid, target] of this._vdiRestoreTargets.entries()) {
+      if (backedUpVdiUuids.has(vdiUuid)) {
+        continue
+      }
+      if (target.type === 'live-mount') {
+        unknownLiveMounted.push(vdiUuid)
+      } else {
+        warn('restore target of a disk which is not in this backup, ignoring it', {
+          type: target.type,
+          vdiUuid,
+        })
+      }
+    }
+
+    if (unknownLiveMounted.length !== 0) {
+      throw new Error(
+        `these disks cannot be live mounted, they are not in this backup: ${unknownLiveMounted.join(', ')}`
+      )
+    }
+  }
+
+  /**
+   * Ref, on the pool the VM is restored to, of the host serving the live mounts.
+   *
+   * A live mount plugs its SR into a single host, which therefore has to belong to that pool: the
+   * uuid is resolved here, once and before anything is mounted, so a host picked on another pool
+   * is rejected with an explicit message instead of a bare `UUID_INVALID` raised halfway through
+   * the restore.
+   */
+  async #resolveLiveMountHostRef() {
+    if (this.#liveMountHostRef === undefined) {
+      // also validates that every live mount of this restore uses the same host
+      const hostId = this._vdiRestoreTargets.getLiveMountHost()
+      try {
+        this.#liveMountHostRef = await this._xapi.call('host.get_by_uuid', hostId)
+      } catch (error) {
+        if (error?.code !== 'UUID_INVALID') {
+          throw error
+        }
+        throw new Error(
+          `host ${hostId} cannot live mount a disk of this restore: it does not belong to the pool the VM is restored to`,
+          { cause: error }
+        )
+      }
+    }
+    return this.#liveMountHostRef
+  }
+
+  /**
+   * Mount every disk whose target asks for it and add it to the backup to import, as an existing
+   * VDI to attach instead of a disk to transfer.
+   */
+  async #addLiveMountedVdis(backup) {
+    const vdiUuids = this._vdiRestoreTargets.getLiveMountedVdiUuids()
+    if (vdiUuids.size === 0) {
+      return
+    }
+
+    const liveMount = this._liveMount
+    if (liveMount === undefined) {
+      throw new Error('live mounting a disk during a restore is not supported here')
+    }
+
+    const xapi = this._xapi
+    const metadata = this._metadata
+    const metadataDir = dirname(metadata._filename)
+    // before the first mount, so a host which cannot serve them leaves nothing behind
+    await this.#resolveLiveMountHostRef()
+    const hostId = this._vdiRestoreTargets.getLiveMountHost()
+
+    for (const [vdiRef, vdi] of Object.entries(metadata.vdis)) {
+      // a disk of the backup which is restored the usual way, or not at all; a target naming a
+      // disk absent from the backup has already been rejected by `#checkTargetsMatchBackup`
+      if (!vdiUuids.has(vdi.uuid)) {
+        continue
+      }
+
+      const diskPath = join(metadataDir, metadata.vhds[vdiRef])
+      const mount = await liveMount.mountDisk({ diskPath, hostId })
+      this.#liveMounts.push({ ...mount, hostId })
+      info('disk live mounted', { diskPath, hostId, mountId: mount.id, vdiUuid: vdi.uuid })
+
+      const record = { ...vdi, liveMountedVdiRef: await xapi.call('VDI.get_by_uuid', mount.vdiUuid) }
+      // it is attached as is: there is nothing to clone it from, nothing to transfer into it, and
+      // no SR to create it on — `SR` still holds the ref it had on the backed up pool
+      delete record.baseVdi
+      delete record.SR
+      backup.vdis[vdiRef] = record
+    }
+  }
+
+  /**
+   * Point the restored VM at the host serving its live mounted disks.
+   *
+   * Their SR is plugged on that host only, so the VM can run nowhere else.
+   */
+  async #setLiveMountAffinity(vmRef) {
+    if (this.#liveMounts.length === 0) {
+      return
+    }
+    await this._xapi.call('VM.set_affinity', vmRef, await this.#resolveLiveMountHostRef())
+  }
+
+  /**
+   * Release the live mounts created by this restore.
+   *
+   * Best effort: this runs while a restore is already failing, and a mount left behind must not
+   * hide the error which caused it.
+   */
+  async #releaseLiveMounts() {
+    for (const { id } of this.#liveMounts.splice(0)) {
+      try {
+        await this._liveMount.unmountDisk(id)
+      } catch (error) {
+        warn('failed to unmount a live mounted disk', { error, mountId: id })
+      }
+    }
+  }
+
+  async run($defer) {
     const adapter = this._adapter
     const metadata = this._metadata
     const isFull = metadata.mode === 'full'
-
     const sizeContainer = { size: 0 }
-    const { newMacAddresses } = this._importIncrementalVmSettings
+    const { newMacAddresses, vmNamePrefix, additionalVmTag } = this._importIncrementalVmSettings
     let backup
     if (isFull) {
+      if (this._vdiRestoreTargets.getLiveMountedVdiUuids().size > 0) {
+        // a full backup is a single XVA stream: there is no per disk handling at all
+        throw new Error('live mounting a disk is only supported when restoring an incremental backup')
+      }
       backup = await adapter.readFullVmBackup(metadata)
       watchStreamSize(backup, sizeContainer)
     } else {
       assert.strictEqual(metadata.mode, 'delta')
 
-      backup = await this.#decorateIncrementalVmMetadata()
+      // the mounts are created here, before the import, and outlive this restore: only a failure
+      // releases them, a successful one hands their ids back to the caller
+      $defer.onFailure(() => this.#releaseLiveMounts())
+      backup = await this._decorateIncrementalVmMetadata()
     }
 
     return Task.run(
@@ -250,10 +428,20 @@ export class ImportVmBackup {
         const xapi = this._xapi
         const srRef = await xapi.call('SR.get_by_uuid', this._srUuid)
 
+        const onVmCreation =
+          vmNamePrefix === undefined && additionalVmTag === undefined
+            ? null
+            : vm =>
+                Promise.all([
+                  vmNamePrefix !== undefined && vm.set_name_label(vmNamePrefix + metadata.vm.name_label),
+                  additionalVmTag !== undefined && vm.add_tags(additionalVmTag),
+                ])
+
         const vmRef = isFull
-          ? await xapi.VM_import(backup, srRef)
+          ? await xapi.VM_import(backup, srRef, onVmCreation)
           : await importIncrementalVm(backup, await xapi.getRecord('SR', srRef), {
               newMacAddresses,
+              vmNamePrefix,
             })
         let size = 0
         if (isFull) {
@@ -276,19 +464,21 @@ export class ImportVmBackup {
           xapi.call(
             'VM.set_name_label',
             vmRef,
-            `${metadata.vm.name_label} (${formatFilenameDate(metadata.timestamp)})`
+            `${vmNamePrefix ?? ''}${metadata.vm.name_label} (${formatFilenameDate(metadata.timestamp)})`
           ),
           xapi.call('VM.set_name_description', vmRef, desc),
           resetVmOtherConfig(xapi, vmRef),
+          this.#setLiveMountAffinity(vmRef),
         ])
 
         return {
           size,
           id: await xapi.getField('VM', vmRef, 'uuid'),
+          liveMounts: [...this.#liveMounts],
         }
       }
     )
   }
 }
 
-decorateClass(ImportVmBackup, { _reuseNearestSnapshot: defer })
+decorateClass(ImportVmBackup, { _reuseNearestSnapshot: defer, run: defer })

@xen-orchestra/backups/ImportVmBackup.test.mjs

@@ -0,0 +1,279 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import pickBy from 'lodash/pickBy.js'
+
+import { ImportVmBackup } from './ImportVmBackup.mjs'
+
+const VM_UUID = 'vm-uuid'
+const JOB_ID = 'job-id'
+const DEFAULT_SR = 'default-sr-uuid'
+const OTHER_SR = 'other-sr-uuid'
+const HOST = 'host-uuid'
+
+// two disks, each identified in the backup by the uuid of the snapshot it was taken from
+const SYSTEM = { ref: 'OpaqueRef:system', uuid: 'snapshot-vdi-system', liveUuid: 'live-vdi-system' }
+const DATA = { ref: 'OpaqueRef:data', uuid: 'snapshot-vdi-data', liveUuid: 'live-vdi-data' }
+
+const metadataFilename = `/xo-vm-backups/${VM_UUID}/20250801T080832Z.json`
+
+const vhdPath = disk => `vdis/${JOB_ID}/${disk.liveUuid}/20250801T080832Z.vhd`
+
+function makeMetadata() {
+  return {
+    _filename: metadataFilename,
+    jobId: JOB_ID,
+    mode: 'delta',
+    timestamp: 1754035712000,
+    vbds: {},
+    vdis: {
+      // `SR` is the ref the VDI had on the pool the backup was taken from
+      [SYSTEM.ref]: { uuid: SYSTEM.uuid, $snapshot_of$uuid: SYSTEM.liveUuid, name_label: 'system', SR: 'OpaqueRef:sr' },
+      [DATA.ref]: { uuid: DATA.uuid, $snapshot_of$uuid: DATA.liveUuid, name_label: 'data', SR: 'OpaqueRef:sr' },
+    },
+    vhds: {
+      [SYSTEM.ref]: vhdPath(SYSTEM),
+      [DATA.ref]: vhdPath(DATA),
+    },
+    vifs: {},
+    vm: { uuid: VM_UUID, name_label: 'a vm', tags: [] },
+    vmSnapshot: { suspend_VDI: 'OpaqueRef:NULL' },
+    vtpms: [],
+  }
+}
+
+// mimics `RemoteAdapter#readIncrementalVmBackup`: excluded VDIs are dropped, the others get a disk
+function makeAdapter(metadata) {
+  return {
+    _handler: {},
+    readIncrementalVmBackup(_metadata, excludedVdiUuids) {
+      const vdis = pickBy(metadata.vdis, vdi => !excludedVdiUuids.has(vdi.uuid))
+      const disks = {}
+      for (const ref of Object.keys(vdis)) {
+        disks[ref] = { path: metadata.vhds[ref] }
+      }
+      return { disks, vbds: metadata.vbds, vdis, version: '1.0.0', vifs: {}, vm: metadata.vm, vtpms: [] }
+    },
+  }
+}
+
+// `unknownUuids` are refused exactly like XAPI refuses a uuid of another pool
+const makeXapi = ({ unknownUuids = [] } = {}) => ({
+  call(method, uuid) {
+    const [type, getter] = method.split('.')
+    assert.equal(getter, 'get_by_uuid')
+    if (unknownUuids.includes(uuid)) {
+      const error = new Error(`UUID_INVALID(${type}, ${uuid})`)
+      error.code = 'UUID_INVALID'
+      throw error
+    }
+    return `${type}_REF:${uuid}`
+  },
+})
+
+function makeLiveMount() {
+  const mounted = []
+  return {
+    mounted,
+    unmounted: [],
+    mountDisk(params) {
+      mounted.push(params)
+      return { id: `mount-${mounted.length}`, vdiUuid: `mounted-vdi-${mounted.length}` }
+    },
+    unmountDisk(id) {
+      this.unmounted.push(id)
+    },
+  }
+}
+
+function makeImporter({ mapVdisSrs, unknownUuids, useDifferentialRestore = false, withoutLiveMount = false } = {}) {
+  const liveMount = withoutLiveMount ? undefined : makeLiveMount()
+  const metadata = makeMetadata()
+  const importer = new ImportVmBackup({
+    adapter: makeAdapter(metadata),
+    liveMount,
+    metadata,
+    settings: { mapVdisSrs, useDifferentialRestore },
+    srUuid: DEFAULT_SR,
+    xapi: makeXapi({ unknownUuids }),
+  })
+  return { importer, liveMount, metadata }
+}
+
+describe('ImportVmBackup#_decorateIncrementalVmMetadata()', () => {
+  it('restores every disk onto the default SR when nothing is mapped', async () => {
+    const { importer } = makeImporter()
+
+    const backup = await importer._decorateIncrementalVmMetadata()
+
+    assert.deepEqual(Object.keys(backup.vdis), [SYSTEM.ref, DATA.ref])
+    for (const vdi of Object.values(backup.vdis)) {
+      assert.equal(vdi.SR, `SR_REF:${DEFAULT_SR}`)
+    }
+  })
+
+  it('honors a per disk SR, in both the legacy and the current shape', async () => {
+    for (const mapVdisSrs of [{ [DATA.uuid]: OTHER_SR }, { [DATA.uuid]: { type: 'restore', sr: OTHER_SR } }]) {
+      const { importer } = makeImporter({ mapVdisSrs })
+
+      const backup = await importer._decorateIncrementalVmMetadata()
+
+      assert.equal(backup.vdis[SYSTEM.ref].SR, `SR_REF:${DEFAULT_SR}`)
+      assert.equal(backup.vdis[DATA.ref].SR, `SR_REF:${OTHER_SR}`)
+    }
+  })
+
+  it('leaves out an ignored disk, in both the legacy and the current shape', async () => {
+    for (const mapVdisSrs of [{ [DATA.uuid]: null }, { [DATA.uuid]: { type: 'ignore' } }]) {
+      const { importer } = makeImporter({ mapVdisSrs })
+
+      const backup = await importer._decorateIncrementalVmMetadata()
+
+      assert.deepEqual(Object.keys(backup.vdis), [SYSTEM.ref])
+      assert.deepEqual(Object.keys(backup.disks), [SYSTEM.ref])
+    }
+  })
+
+  describe('live mount', () => {
+    const mapVdisSrs = { [DATA.uuid]: { type: 'live-mount', host: HOST } }
+
+    it('mounts the disk instead of reading it', async () => {
+      const { importer, liveMount } = makeImporter({ mapVdisSrs })
+
+      const backup = await importer._decorateIncrementalVmMetadata()
+
+      assert.deepEqual(liveMount.mounted, [{ diskPath: `/xo-vm-backups/${VM_UUID}/${vhdPath(DATA)}`, hostId: HOST }])
+      // no data is transferred for it
+      assert.deepEqual(Object.keys(backup.disks), [SYSTEM.ref])
+    })
+
+    it('attaches the mounted VDI and gives it no SR', async () => {
+      const { importer } = makeImporter({ mapVdisSrs })
+
+      const backup = await importer._decorateIncrementalVmMetadata()
+
+      const vdi = backup.vdis[DATA.ref]
+      assert.equal(vdi.liveMountedVdiRef, 'VDI_REF:mounted-vdi-1')
+      assert.equal(vdi.SR, undefined)
+      assert.equal(vdi.uuid, DATA.uuid)
+      // the other disk is restored as usual
+      assert.equal(backup.vdis[SYSTEM.ref].SR, `SR_REF:${DEFAULT_SR}`)
+      assert.equal(backup.vdis[SYSTEM.ref].liveMountedVdiRef, undefined)
+    })
+
+    it('rejects live mounts spread over several hosts', async () => {
+      const { importer } = makeImporter({
+        mapVdisSrs: {
+          [SYSTEM.uuid]: { type: 'live-mount', host: HOST },
+          [DATA.uuid]: { type: 'live-mount', host: 'another-host' },
+        },
+      })
+
+      await assert.rejects(() => importer._decorateIncrementalVmMetadata(), /must use the same host/)
+    })
+
+    it('rejects a live mount when the caller cannot serve one', async () => {
+      const { importer } = makeImporter({ mapVdisSrs, withoutLiveMount: true })
+
+      await assert.rejects(() => importer._decorateIncrementalVmMetadata(), /not supported here/)
+    })
+
+    it('rejects a live mount of a disk which is not in this backup', async () => {
+      const { importer, liveMount } = makeImporter({
+        mapVdisSrs: { 'not-in-this-backup': { type: 'live-mount', host: HOST } },
+      })
+
+      await assert.rejects(
+        () => importer._decorateIncrementalVmMetadata(),
+        /cannot be live mounted, they are not in this backup: not-in-this-backup/
+      )
+      assert.deepEqual(liveMount.mounted, [])
+    })
+
+    it('rejects a host which is not on the pool the VM is restored to', async () => {
+      const { importer, liveMount } = makeImporter({ mapVdisSrs, unknownUuids: [HOST] })
+
+      await assert.rejects(() => importer._decorateIncrementalVmMetadata(), /does not belong to the pool/)
+      // the host is resolved first, so nothing is left mounted behind
+      assert.deepEqual(liveMount.mounted, [])
+    })
+  })
+
+  it('still restores when a disk of `mapVdisSrs` is not in this backup', async () => {
+    // a stale mapping must not break a restore which used to work
+    const { importer } = makeImporter({ mapVdisSrs: { 'not-in-this-backup': OTHER_SR } })
+
+    const backup = await importer._decorateIncrementalVmMetadata()
+
+    assert.deepEqual(Object.keys(backup.vdis), [SYSTEM.ref, DATA.ref])
+  })
+})
+
+describe('ImportVmBackup#_reuseNearestSnapshot()', () => {
+  // a snapshot whose backup is the very file being restored: `_reuseNearestSnapshot` reuses it as
+  // is, which is the one branch that opens no VHD chain
+  function makeDifferentialImporter({ mapVdisSrs, snapshotSrUuid }) {
+    const metadata = makeMetadata()
+    const adapter = makeAdapter(metadata)
+    adapter.listVmBackups = () => [{ vdis: metadata.vdis, vhds: metadata.vhds }]
+    // reusing a snapshot as is opens nothing: any attempt to open the backup chain means the disk
+    // is about to be transferred instead
+    adapter._handler = {
+      openFile() {
+        throw new Error('would transfer the disk')
+      },
+    }
+
+    const snapshots = {
+      'OpaqueRef:snapshot': {
+        uuid: DATA.uuid,
+        type: 'user',
+        snapshot_time: 1,
+        $SR: { uuid: snapshotSrUuid },
+      },
+    }
+
+    const xapi = {
+      ...makeXapi(),
+      getRecordByUuid(type, uuid) {
+        assert.equal(type, 'VDI')
+        return uuid === DATA.liveUuid ? { snapshots: Object.keys(snapshots) } : undefined
+      },
+      getRecord(type, ref) {
+        assert.equal(type, 'VDI')
+        return snapshots[ref]
+      },
+    }
+
+    return new ImportVmBackup({
+      adapter,
+      metadata,
+      settings: { mapVdisSrs, useDifferentialRestore: true },
+      srUuid: DEFAULT_SR,
+      xapi,
+    })
+  }
+
+  it('reuses a snapshot sitting on the SR that disk is restored to', async () => {
+    // the disk is remapped to another SR, and the snapshot is there too
+    const importer = makeDifferentialImporter({
+      mapVdisSrs: { [DATA.uuid]: OTHER_SR, [SYSTEM.uuid]: null },
+      snapshotSrUuid: OTHER_SR,
+    })
+
+    const backup = await importer._reuseNearestSnapshot(new Set([SYSTEM.uuid]))
+
+    assert.equal(backup.vdis[DATA.ref].baseVdi.uuid, DATA.uuid)
+    assert.equal(backup.disks[DATA.ref], undefined)
+  })
+
+  it('skips a snapshot sitting on another SR', async () => {
+    // the snapshot is on the default SR, but that disk is restored to another one: cloning it
+    // would land on the wrong SR, so it must be transferred instead
+    const importer = makeDifferentialImporter({
+      mapVdisSrs: { [DATA.uuid]: OTHER_SR, [SYSTEM.uuid]: null },
+      snapshotSrUuid: DEFAULT_SR,
+    })
+
+    await assert.rejects(() => importer._reuseNearestSnapshot(new Set([SYSTEM.uuid])), /would transfer the disk/)
+  })
+})

@xen-orchestra/backups/README.md

@@ -14,6 +14,13 @@ npm install --save @xen-orchestra/backups
 
 ## Usage
 
+## Documentation
+
+- [VM backups](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/VM%20backups/README.md): file structure on a remote, XAPI attributes, task logs, run description object, writer API
+- [Incremental replication](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/VM%20backups/incrementalReplication.md): how CR selects its target VM and VDIs
+- [Metadata backups](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/Metadata%20backups/README.md): file structure on a remote, structure of `metadata.json`, task logs
+- [Health check](https://github.com/vatesfr/xen-orchestra/blob/master/%40xen-orchestra/backups/docs/healthcheck/example.sh): example guest script reporting to xenstore
+
 ## Changing the default backup configuration
 
 This library receives a backup configuration from `xo-server` or `xo-proxy`. This configuration is split between multiple properties:

@xen-orchestra/backups/RemoteAdapter.integ.mjs

@@ -0,0 +1,325 @@
+import test from 'node:test'
+import { strict as assert } from 'node:assert'
+
+import tmp from 'tmp'
+import fs from 'fs-extra'
+import * as uuid from 'uuid'
+import { getHandler } from '@xen-orchestra/fs'
+import { relativeFromFile } from '@xen-orchestra/fs/path'
+import { Disposable, pFromCallback } from 'promise-toolbox'
+import { RandomAccessDisk } from '@xen-orchestra/disk-transform'
+import { RemoteAdapter } from './RemoteAdapter.mjs'
+import { checkDisk } from './_runners/_writers/_checkDisk.mjs'
+import { formatFilenameDate } from './_filenameDate.mjs'
+import { VHDFOOTER, VHDHEADER } from './tests.fixtures.mjs'
+import { openVhd, VhdFile, VhdAbstract, Constants, VhdDirectory } from 'vhd-lib'
+import computeGeometryForSize from 'vhd-lib/_computeGeometryForSize.js'
+import { dirname, basename } from 'node:path'
+import { rimraf } from 'rimraf'
+
+const { beforeEach, afterEach, describe } = test
+
+let tempDir, handler, jobId, vdiId, basePath, relativePath
+const vmUuid = 'a1b2c3d4-0000-0000-0000-000000000000'
+const rootPath = `xo-vm-backups/${vmUuid}`
+
+beforeEach(async () => {
+  tempDir = await pFromCallback(cb => tmp.dir(cb))
+  jobId = uniqueId()
+  vdiId = uniqueId()
+  relativePath = `vdis/${jobId}/${vdiId}`
+  basePath = `${rootPath}/${relativePath}`
+  await fs.mkdirp(`${tempDir}/${basePath}`)
+})
+
+afterEach(async () => {
+  await rimraf(tempDir)
+  await handler.forget()
+})
+
+const uniqueId = () => uuid.v1()
+const uniqueIdBuffer = () => uuid.v1({}, Buffer.alloc(16))
+
+async function getAdapter({ useVhdDirectory = false, vhdDirectoryCompression, remoteCompressionType } = {}) {
+  handler = getHandler({ url: `file://${tempDir}`, useVhdDirectory, compressionType: remoteCompressionType })
+  await handler.sync()
+  return new RemoteAdapter(handler, { vhdDirectoryCompression })
+}
+
+const listVmDir = () => handler.list(rootPath, { ignoreMissing: true })
+
+// write a full backup the way a backup job would, i.e. through the adapter
+function writeFullBackup(adapter, timestamp = Date.now()) {
+  return adapter.writeVmBackupMetadata(vmUuid, {
+    mode: 'full',
+    xva: `./${formatFilenameDate(timestamp)}.xva`,
+    vm: { uuid: vmUuid },
+    jobId: uuid.v1(),
+    scheduleId: uuid.v1(),
+    timestamp,
+  })
+}
+
+// mirrors the helper in _cleanVm.integ.mjs, with compression support for VHD directories.
+// VHD directories are only openable through their alias (see RemoteVhdDisk.init), so
+// `path` here is always the alias-less name; the alias is created as `${path}.alias.vhd`.
+async function generateVhd(path, opts = {}) {
+  let vhd
+
+  let dataPath = path
+  const { mode = 'file' } = opts
+  assert.ok(mode === 'file' || mode === 'directory', `unknown mode ${mode}`)
+  if (mode === 'directory') {
+    dataPath = dirname(path) + '/data/' + basename(path)
+    await handler.mkdir(dirname(path) + '/data/')
+    await handler.mkdir(dataPath)
+    vhd = new VhdDirectory(handler, dataPath, { compression: opts.compression })
+  } else {
+    const fd = await handler.openFile(dataPath, 'wx')
+    vhd = new VhdFile(handler, fd)
+  }
+
+  vhd.header = { ...VHDHEADER, ...opts.header }
+  vhd.footer = { ...VHDFOOTER, ...opts.footer, uuid: opts.uuid ?? uniqueIdBuffer() }
+
+  if (vhd.header.parentUuid) {
+    vhd.footer.diskType = Constants.DISK_TYPES.DIFFERENCING
+  } else {
+    vhd.footer.diskType = Constants.DISK_TYPES.DYNAMIC
+  }
+
+  if (mode === 'directory') {
+    await VhdAbstract.createAlias(handler, path + '.alias.vhd', dataPath)
+  }
+
+  await vhd.writeBlockAllocationTable()
+  await vhd.writeHeader()
+  await vhd.writeFooter()
+  return vhd
+}
+
+describe('cache.json.gz on an immutable remote', { concurrency: 1 }, () => {
+  test('writing a backup does not create it', async () => {
+    const adapter = await getAdapter()
+    handler.isImmutable = () => true
+
+    await writeFullBackup(adapter)
+
+    assert.ok(
+      !(await listVmDir()).includes('cache.json.gz'),
+      'cache.json.gz must never be created on an immutable remote'
+    )
+  })
+
+  // deleteFullVmBackups() rather than deleteVmBackup(), because the latter also runs cleanVm()
+  // which removes a leftover cache and would hide a cache wrongly written by the deletion itself
+  test('deleting a backup does not create it', async () => {
+    const adapter = await getAdapter()
+    handler.isImmutable = () => true
+    await writeFullBackup(adapter)
+    const backups = await adapter.listVmBackups(vmUuid)
+    assert.equal(backups.length, 1)
+
+    await adapter.deleteFullVmBackups(backups)
+
+    assert.ok(
+      !(await listVmDir()).includes('cache.json.gz'),
+      'cache.json.gz must never be created on an immutable remote'
+    )
+  })
+
+  test('it is still created on a mutable remote', async () => {
+    const adapter = await getAdapter()
+    await writeFullBackup(adapter)
+
+    assert.ok((await listVmDir()).includes('cache.json.gz'), 'a mutable remote must keep using the cache')
+  })
+})
+
+describe('RemoteAdapter#isMergeableParent', { concurrency: 1 }, () => {
+  for (const diskIsDirectory of [false, true]) {
+    for (const useVhdDirectory of [false, true]) {
+      for (const compressionMatches of [false, true]) {
+        for (const uuidMatches of [false, true]) {
+          const expected = uuidMatches && (diskIsDirectory ? useVhdDirectory && compressionMatches : !useVhdDirectory)
+
+          test(`diskIsDirectory=${diskIsDirectory} useVhdDirectory=${useVhdDirectory} compressionMatches=${compressionMatches} uuidMatches=${uuidMatches} -> ${expected}`, async () => {
+            const targetCompression = 'brotli'
+            const adapter = await getAdapter({ useVhdDirectory, vhdDirectoryCompression: targetCompression })
+            const targetUuid = uniqueIdBuffer()
+
+            await generateVhd(`${basePath}/disk.vhd`, {
+              mode: diskIsDirectory ? 'directory' : 'file',
+              compression: diskIsDirectory ? (compressionMatches ? targetCompression : 'gzip') : undefined,
+              uuid: uuidMatches ? targetUuid : uniqueIdBuffer(),
+            })
+            const path = diskIsDirectory ? `${basePath}/disk.vhd.alias.vhd` : `${basePath}/disk.vhd`
+
+            assert.equal(await adapter.isMergeableParent(targetUuid, path), expected)
+          })
+        }
+      }
+    }
+  }
+})
+
+describe('RemoteAdapter#isMergeableParent compression resolution', { concurrency: 1 }, () => {
+  test('the per-remote compressionType override wins over the adapter default', async () => {
+    const adapter = await getAdapter({
+      useVhdDirectory: true,
+      vhdDirectoryCompression: 'gzip', // config.toml-style default
+      remoteCompressionType: 'brotli', // per-remote override, should be the one actually compared against
+    })
+    const targetUuid = uniqueIdBuffer()
+    await generateVhd(`${basePath}/disk.vhd`, { mode: 'directory', compression: 'brotli', uuid: targetUuid })
+
+    assert.equal(await adapter.isMergeableParent(targetUuid, `${basePath}/disk.vhd.alias.vhd`), true)
+  })
+
+  test('a disk compressed with the adapter default (not the override) is rejected', async () => {
+    const adapter = await getAdapter({
+      useVhdDirectory: true,
+      vhdDirectoryCompression: 'gzip',
+      remoteCompressionType: 'brotli',
+    })
+    const targetUuid = uniqueIdBuffer()
+    // disk uses the config default, not the remote override that's actually in effect
+    await generateVhd(`${basePath}/disk.vhd`, { mode: 'directory', compression: 'gzip', uuid: targetUuid })
+
+    assert.equal(await adapter.isMergeableParent(targetUuid, `${basePath}/disk.vhd.alias.vhd`), false)
+  })
+
+  test("a remote-level 'none' override means no compression, ignoring the adapter default", async () => {
+    const adapter = await getAdapter({
+      useVhdDirectory: true,
+      vhdDirectoryCompression: 'brotli',
+      remoteCompressionType: 'none',
+    })
+    const targetUuid = uniqueIdBuffer()
+    // no compression option => VhdDirectory's own getCompressionType() is undefined, matching 'none'
+    await generateVhd(`${basePath}/disk.vhd`, { mode: 'directory', uuid: targetUuid })
+
+    assert.equal(await adapter.isMergeableParent(targetUuid, `${basePath}/disk.vhd.alias.vhd`), true)
+  })
+})
+
+const DEFAULT_BLOCK_SIZE = 0x00200000 // 2MB, from vhd-lib spec
+
+// minimal source disk, enough for writeVhd() to produce a real, readable VHD
+class MockDisk extends RandomAccessDisk {
+  #size
+  #blockIndexes
+  #fillByte
+  #differencing
+
+  constructor(nbBlocks, blockIndexes, fillByte, { differencing = false } = {}) {
+    super()
+    const { actualSize } = computeGeometryForSize(nbBlocks * DEFAULT_BLOCK_SIZE)
+    this.#size = actualSize
+    this.#blockIndexes = blockIndexes
+    this.#fillByte = fillByte
+    this.#differencing = differencing
+  }
+
+  async readBlock(index) {
+    const remaining = this.#size - DEFAULT_BLOCK_SIZE * index
+    return { index, data: Buffer.alloc(Math.min(remaining, DEFAULT_BLOCK_SIZE), this.#fillByte) }
+  }
+
+  getVirtualSize() {
+    return this.#size
+  }
+
+  getBlockSize() {
+    return DEFAULT_BLOCK_SIZE
+  }
+
+  isDifferencing() {
+    return this.#differencing
+  }
+
+  getBlockIndexes() {
+    return this.#blockIndexes
+  }
+
+  hasBlock(index) {
+    return this.#blockIndexes.includes(index)
+  }
+
+  async init() {}
+  async close() {}
+}
+
+// IncrementalRemoteWriter._transfer(): the disk is written
+// through the adapter, and the *real* checkDisk() is used as the validator
+describe('RemoteAdapter#writeVhd validated by checkDisk', { concurrency: 1 }, () => {
+  for (const useVhdDirectory of [false, true]) {
+    const mode = useVhdDirectory ? 'directory' : 'file'
+
+    test(`${mode}: writes a base disk that passes validation and reads back`, async () => {
+      const adapter = await getAdapter({ useVhdDirectory })
+      const path = `${basePath}/${adapter.getVhdFileName('base')}`
+
+      const size = await adapter.writeVhd(path, new MockDisk(2, [0, 1], 0x42), {
+        validator: tmpPath => checkDisk(handler, tmpPath),
+        uuid: uniqueIdBuffer(),
+      })
+
+      assert.ok(size > 0, 'reported size should be greater than 0')
+      assert.equal(basename(path).endsWith('.alias.vhd'), useVhdDirectory)
+      await Disposable.use(openVhd(handler, path), async vhd => {
+        assert.equal(vhd.footer.diskType, Constants.DISK_TYPES.DYNAMIC)
+        await vhd.readBlockAllocationTable()
+        const { data } = await vhd.readBlock(1)
+        assert.ok(
+          data.every(byte => byte === 0x42),
+          'block 1 should contain the source disk data'
+        )
+      })
+    })
+
+    test(`${mode}: writes a differencing disk chained to its parent that passes validation`, async () => {
+      const adapter = await getAdapter({ useVhdDirectory })
+      const parentPath = `${basePath}/${adapter.getVhdFileName('20000101T000000Z')}`
+      const childPath = `${basePath}/${adapter.getVhdFileName('20000102T000000Z')}`
+      const parentUuid = uniqueIdBuffer()
+
+      await adapter.writeVhd(parentPath, new MockDisk(2, [0, 1], 0xaa), {
+        validator: tmpPath => checkDisk(handler, tmpPath),
+        uuid: parentUuid,
+      })
+      await adapter.writeVhd(childPath, new MockDisk(2, [1], 0xbb, { differencing: true }), {
+        validator: tmpPath => checkDisk(handler, tmpPath),
+        uuid: uniqueIdBuffer(),
+        parentUuid,
+        parentPath: relativeFromFile(childPath, parentPath),
+      })
+
+      await Disposable.use(openVhd(handler, childPath), async vhd => {
+        assert.equal(vhd.footer.diskType, Constants.DISK_TYPES.DIFFERENCING)
+        assert.deepEqual(vhd.header.parentUuid, parentUuid)
+        assert.equal(vhd.header.parentUnicodeName, relativeFromFile(childPath, parentPath))
+      })
+    })
+
+    test(`${mode}: a rejected validation leaves no disk behind`, async () => {
+      const adapter = await getAdapter({ useVhdDirectory })
+      const path = `${basePath}/${adapter.getVhdFileName('base')}`
+
+      await assert.rejects(
+        adapter.writeVhd(path, new MockDisk(1, [0], 0x11), {
+          validator: async () => {
+            throw new Error('boom')
+          },
+          uuid: uniqueIdBuffer(),
+        }),
+        /boom/
+      )
+
+      // neither the alias/file nor the VHD directory it points to must survive, otherwise the
+      // next run would chain onto a disk that was never validated
+      assert.deepEqual(await handler.list(basePath, { ignoreMissing: true }), useVhdDirectory ? ['data'] : [])
+      assert.deepEqual(await handler.list(`${basePath}/data`, { ignoreMissing: true }), [])
+    })
+  }
+})