@hamak/filesystem-server-api 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,6 +2,11 @@
2
2
  * Workspace Manager Interface
3
3
  *
4
4
  * Provides filesystem operations for a workspace (directory-based storage)
5
+ *
6
+ * Versioning (amah/app-framework#70): every file entry returned should carry
7
+ * `FileInfo.version`, the content hash from `computeFileVersion`. The HTTP
8
+ * router turns it into an `ETag` and checks `If-Match` against it before a
9
+ * write. Directories carry no version.
5
10
  */
6
11
  import { FileInfo } from '@hamak/shared-utils';
7
12
  export interface IWorkspaceManager {
@@ -1 +1 @@
1
- {"version":3,"file":"IWorkspaceManager.d.ts","sourceRoot":"","sources":["../../src/api/IWorkspaceManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAElE;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE/D;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjF;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEtE;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/D"}
1
+ {"version":3,"file":"IWorkspaceManager.d.ts","sourceRoot":"","sources":["../../src/api/IWorkspaceManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAElE;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE/D;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjF;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEtE;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/D"}
@@ -2,5 +2,10 @@
2
2
  * Workspace Manager Interface
3
3
  *
4
4
  * Provides filesystem operations for a workspace (directory-based storage)
5
+ *
6
+ * Versioning (amah/app-framework#70): every file entry returned should carry
7
+ * `FileInfo.version`, the content hash from `computeFileVersion`. The HTTP
8
+ * router turns it into an `ETag` and checks `If-Match` against it before a
9
+ * write. Directories carry no version.
5
10
  */
6
11
  export {};
@@ -3,5 +3,10 @@
3
3
  * Workspace Manager Interface
4
4
  *
5
5
  * Provides filesystem operations for a workspace (directory-based storage)
6
+ *
7
+ * Versioning (amah/app-framework#70): every file entry returned should carry
8
+ * `FileInfo.version`, the content hash from `computeFileVersion`. The HTTP
9
+ * router turns it into an `ETag` and checks `If-Match` against it before a
10
+ * write. Directories carry no version.
6
11
  */
7
12
  Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,36 @@
1
+ "use strict";
2
+ /**
3
+ * File version — the write-precondition contract (amah/app-framework#70)
4
+ *
5
+ * A file's `version` is a content hash: the hex SHA-1 of its bytes. It is
6
+ * stable across servers and processes (no mtime, no counter), so a version
7
+ * read from one workspace provider stays comparable after a restart or a
8
+ * git checkout, and an unchanged file always reports the same version.
9
+ *
10
+ * Any `IWorkspaceManager` implementation should set `FileInfo.version` with
11
+ * `computeFileVersion` on every file entry it returns (list / get / read /
12
+ * write). The router derives the `ETag` header from it and checks `If-Match`
13
+ * against it; a manager that leaves `version` unset still works, because the
14
+ * router falls back to hashing the content it reads.
15
+ */
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ exports.VERSION_MISMATCH = exports.computeFileVersion = void 0;
18
+ const crypto_1 = require("crypto");
19
+ /**
20
+ * Compute the version token of a file's content.
21
+ *
22
+ * @param content - The file's bytes, or its text (hashed as UTF-8)
23
+ * @returns Lower-case hex SHA-1 of the content
24
+ */
25
+ function computeFileVersion(content) {
26
+ return (0, crypto_1.createHash)('sha1').update(content).digest('hex');
27
+ }
28
+ exports.computeFileVersion = computeFileVersion;
29
+ /**
30
+ * Error code carried by a refused conditional write.
31
+ *
32
+ * The HTTP router answers such a write with `412 Precondition Failed` and the
33
+ * body `{ code: 'version-mismatch', current: '<version now on the server>' }`;
34
+ * nothing is written.
35
+ */
36
+ exports.VERSION_MISMATCH = 'version-mismatch';
@@ -19,3 +19,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
19
19
  Object.defineProperty(exports, "__esModule", { value: true });
20
20
  __exportStar(require("./workspace-config"), exports);
21
21
  __exportStar(require("./server-config"), exports);
22
+ __exportStar(require("./file-version"), exports);
@@ -0,0 +1,41 @@
1
+ /**
2
+ * File version — the write-precondition contract (amah/app-framework#70)
3
+ *
4
+ * A file's `version` is a content hash: the hex SHA-1 of its bytes. It is
5
+ * stable across servers and processes (no mtime, no counter), so a version
6
+ * read from one workspace provider stays comparable after a restart or a
7
+ * git checkout, and an unchanged file always reports the same version.
8
+ *
9
+ * Any `IWorkspaceManager` implementation should set `FileInfo.version` with
10
+ * `computeFileVersion` on every file entry it returns (list / get / read /
11
+ * write). The router derives the `ETag` header from it and checks `If-Match`
12
+ * against it; a manager that leaves `version` unset still works, because the
13
+ * router falls back to hashing the content it reads.
14
+ */
15
+ /**
16
+ * Compute the version token of a file's content.
17
+ *
18
+ * @param content - The file's bytes, or its text (hashed as UTF-8)
19
+ * @returns Lower-case hex SHA-1 of the content
20
+ */
21
+ export declare function computeFileVersion(content: string | Uint8Array): string;
22
+ /**
23
+ * Error code carried by a refused conditional write.
24
+ *
25
+ * The HTTP router answers such a write with `412 Precondition Failed` and the
26
+ * body `{ code: 'version-mismatch', current: '<version now on the server>' }`;
27
+ * nothing is written.
28
+ */
29
+ export declare const VERSION_MISMATCH = "version-mismatch";
30
+ /**
31
+ * Body of a `412 Precondition Failed` response.
32
+ */
33
+ export interface VersionMismatchBody {
34
+ code: typeof VERSION_MISMATCH;
35
+ /**
36
+ * The version the server holds now. `undefined` when the file does not
37
+ * exist any more (the client's copy was deleted underneath it).
38
+ */
39
+ current: string | undefined;
40
+ }
41
+ //# sourceMappingURL=file-version.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-version.d.ts","sourceRoot":"","sources":["../../src/types/file-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAEvE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,gBAAgB,CAAC;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B"}
@@ -0,0 +1,32 @@
1
+ /**
2
+ * File version — the write-precondition contract (amah/app-framework#70)
3
+ *
4
+ * A file's `version` is a content hash: the hex SHA-1 of its bytes. It is
5
+ * stable across servers and processes (no mtime, no counter), so a version
6
+ * read from one workspace provider stays comparable after a restart or a
7
+ * git checkout, and an unchanged file always reports the same version.
8
+ *
9
+ * Any `IWorkspaceManager` implementation should set `FileInfo.version` with
10
+ * `computeFileVersion` on every file entry it returns (list / get / read /
11
+ * write). The router derives the `ETag` header from it and checks `If-Match`
12
+ * against it; a manager that leaves `version` unset still works, because the
13
+ * router falls back to hashing the content it reads.
14
+ */
15
+ import { createHash } from 'crypto';
16
+ /**
17
+ * Compute the version token of a file's content.
18
+ *
19
+ * @param content - The file's bytes, or its text (hashed as UTF-8)
20
+ * @returns Lower-case hex SHA-1 of the content
21
+ */
22
+ export function computeFileVersion(content) {
23
+ return createHash('sha1').update(content).digest('hex');
24
+ }
25
+ /**
26
+ * Error code carried by a refused conditional write.
27
+ *
28
+ * The HTTP router answers such a write with `412 Precondition Failed` and the
29
+ * body `{ code: 'version-mismatch', current: '<version now on the server>' }`;
30
+ * nothing is written.
31
+ */
32
+ export const VERSION_MISMATCH = 'version-mismatch';
@@ -3,4 +3,5 @@
3
3
  */
4
4
  export * from './workspace-config.js';
5
5
  export * from './server-config.js';
6
+ export * from './file-version.js';
6
7
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}
@@ -3,3 +3,4 @@
3
3
  */
4
4
  export * from './workspace-config.js';
5
5
  export * from './server-config.js';
6
+ export * from './file-version.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hamak/filesystem-server-api",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "FileSystem Server API - Backend filesystem server interfaces and contracts",