mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-17 11:49:33 +01:00
57 lines
2.9 KiB
TypeScript
57 lines
2.9 KiB
TypeScript
/**
|
|||
|
|
* @fileoverview The ONE reader and writer of `local-model.json`, the state file of the local
|
||
|
|
* model install (`LocalModelStateFile`).
|
||
|
|
*
|
||
|
|
* CONTRACT STAGE: `IDLE_LOCAL_MODEL_STATE` is final. Every function below has its final
|
||
|
|
* signature and a body that throws; the bodies are written next.
|
||
|
|
*
|
||
|
|
* Why one module: the install job writes the state, the step and the digest, and the caller
|
||
|
|
* of the runtime supervisor writes the pid and the port. Two writers with their own temp file
|
||
|
|
* and rename would lose each other's change, which is the fault `mutateCustomModelHosts()`
|
||
|
|
* exists to end for the endpoint store. So every write goes through `mutateLocalModelState()`.
|
||
|
|
*
|
||
|
|
* The shape of `mutateSettingsFile()` (src/web/settings-writer.ts):
|
||
|
|
* - Serialized: mutations run one at a time on one promise chain.
|
||
|
|
* - Atomic: each write goes to a temp file with a random name beside the target and is
|
||
|
|
* renamed over it. The file is mode 0600.
|
||
|
|
* - Reading is TOTAL, unlike the settings writer: the file holds no setting of the user, only
|
||
|
|
* what this feature recorded, so a missing file, one that does not parse or one with
|
||
|
|
* another `schema` reads as `IDLE_LOCAL_MODEL_STATE` and the next write replaces it.
|
||
|
|
* - The path is `localModelPaths().stateFile`. The file itself holds no path.
|
||
|
|
*/
|
||
|
|
|
||
|
|
import type { LocalModelStateFile } from '../types.js';
|
||
|
|
|
||
|
|
/** Marks a body the contract stage left unwritten. */
|
||
|
|
function notImplemented(what: string, ..._args: unknown[]): never {
|
||
|
|
throw new Error(`${what} is not implemented yet`);
|
||
|
|
}
|
||
|
|
|
||
|
|
/** The state when nothing was ever installed. What an unreadable file reads as. */
|
||
|
|
export const IDLE_LOCAL_MODEL_STATE: LocalModelStateFile = Object.freeze({ schema: 1, state: 'idle' });
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The state a file's text stands for. Pure and total: text that is not a JSON object of
|
||
|
|
* `schema: 1` with a known `state` is `IDLE_LOCAL_MODEL_STATE`. Members it does not know are
|
||
|
|
* dropped, and a member of the wrong type is dropped rather than trusted.
|
||
|
|
*/
|
||
|
|
export function parseLocalModelState(raw: string): LocalModelStateFile {
|
||
|
|
return notImplemented('parseLocalModelState', raw);
|
||
|
|
}
|
||
|
|
|
||
|
|
/** The stored state. Never throws: a file that cannot be read is `IDLE_LOCAL_MODEL_STATE`. */
|
||
|
|
export async function readLocalModelState(): Promise<LocalModelStateFile> {
|
||
|
|
return notImplemented('readLocalModelState');
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Runs one change to the state file. `fn` receives the current state and returns the state to
|
||
|
|
* write, or `undefined` to write nothing. Resolves with the state before and after the change
|
||
|
|
* (`after` is `undefined` when nothing was written). `updatedAt` is stamped here. A failed
|
||
|
|
* write rejects its own caller only; the chain keeps going.
|
||
|
|
*/
|
||
|
|
export function mutateLocalModelState(
|
||
|
|
fn: (current: LocalModelStateFile) => LocalModelStateFile | undefined
|
||
|
|
): Promise<{ before: LocalModelStateFile; after: LocalModelStateFile | undefined }> {
|
||
|
|
return notImplemented('mutateLocalModelState', fn);
|
||
|
|
}
|