Files
orca/src/shared/file-write/file-write-disk-precondition.ts
T

161 lines
6.5 KiB
TypeScript

import { getDiskBaselineSignature, getWrittenContentDiskSignature } from './disk-baseline-signature'
import { ERRNO_CODE_PATTERN } from '../errno-code'
// Why: the host serves `files.writeIfUnchanged`; without it a client compares from its side first.
export const FILE_WRITE_DISK_PRECONDITION_RUNTIME_CAPABILITY =
'files.write.disk-precondition.v1' as const
// Why separate: v1 hosts can rewrite identical text and cannot enforce lossless automatic saves.
export const FILE_WRITE_IDENTICAL_RUNTIME_CAPABILITY = 'files.write.identical-noop.v1' as const
export const FILE_WRITE_IF_UNCHANGED_METHOD = 'files.writeIfUnchanged'
/** v1 hosts cannot check bytes or skip identical writes; require a client-side read only for saves that must refuse non-UTF-8 files. */
export function hostEnforcesPrecondition(
capabilities: readonly unknown[],
precondition: FileWriteDiskPrecondition
): boolean {
return (
capabilities.includes(FILE_WRITE_IDENTICAL_RUNTIME_CAPABILITY) ||
(capabilities.includes(FILE_WRITE_DISK_PRECONDITION_RUNTIME_CAPABILITY) &&
precondition.requireLosslessUtf8 !== true)
)
}
/** Refuse the write unless disk still holds the content this signature was taken over. */
export type FileWriteDiskPrecondition = {
expectedSignature: string
/** A missing file is written (recreated) instead of refused. */
allowMissing?: boolean
/** Refuse a file that isn't valid UTF-8 rather than convert it unasked. */
requireLosslessUtf8?: boolean
}
/** `not-utf8`: a save met bytes it can't round-trip; older clients read it as `changed`. */
export type FileWriteDiskConflict = 'changed' | 'missing' | 'not-utf8'
export type FileWriteDiskComparison = FileWriteDiskConflict | 'identical' | null
export type FileWriteResult =
| { ok: true; unchanged?: boolean }
| { ok: false; diskConflict: FileWriteDiskConflict }
export const FILE_WRITE_OK: FileWriteResult = { ok: true }
export const FILE_WRITE_UNCHANGED: FileWriteResult = { ok: true, unchanged: true }
/** `current` is the decoded disk text, `null` when missing, `undefined` when not comparable text; `content` is the text being saved. */
export function compareDiskWritePrecondition(
precondition: FileWriteDiskPrecondition,
current: string | null | undefined,
content: string
): FileWriteDiskComparison {
if (current === null) {
return precondition.allowMissing === true ? null : 'missing'
}
if (current === undefined) {
return 'changed'
}
// Why: U+FFFD may stand for bytes a decode dropped, so decoded equality proves nothing.
if (current === content && !current.includes('\uFFFD')) {
return 'identical'
}
if (getDiskBaselineSignature(current) !== precondition.expectedSignature) {
return 'changed'
}
// Why: decoded text can't tell a real U+FFFD from replaced bytes, so a reader of text stays conservative.
return precondition.requireLosslessUtf8 && current.includes('\uFFFD') ? 'not-utf8' : null
}
/** Why: old hosts answer `{ ok: true }` or nothing; only an explicit `ok: false` is a refusal. */
export function parseFileWriteResult(value: unknown): FileWriteResult {
if (typeof value !== 'object' || value === null || !('ok' in value)) {
return FILE_WRITE_OK
}
if (value.ok !== false) {
return value.ok === true && 'unchanged' in value && value.unchanged === true
? FILE_WRITE_UNCHANGED
: FILE_WRITE_OK
}
const diskConflict = 'diskConflict' in value ? value.diskConflict : undefined
return {
ok: false,
diskConflict:
diskConflict === 'missing' || diskConflict === 'not-utf8' ? diskConflict : 'changed'
}
}
/** Only a not-found answer proves the file is gone; a lost transport proves nothing. */
export function isConfirmedFileNotFoundError(error: unknown): boolean {
if (!(error instanceof Error)) {
return false
}
// Other codes (an RPC envelope's 'runtime_error') carry no errno, so the wording decides.
const code = 'code' in error ? error.code : undefined
if (typeof code === 'string' && ERRNO_CODE_PATTERN.test(code)) {
return code === 'ENOENT'
}
// Why only a leading wrapper is stripped: the rest may quote a path, which can spell anything.
return NOT_FOUND_MESSAGE.test(error.message.replace(IPC_ERROR_WRAPPER, ''))
}
const IPC_ERROR_WRAPPER = /^Error invoking remote method '[^']*': (?:Error: )?/
const NOT_FOUND_MESSAGE = /^(?:ENOENT: no such file or directory|No such file(?: or directory)?$)/i
const FILE_TOO_LARGE_CODE = 'file_too_large'
/** A host's `file_too_large` refusal, which travels as the bare code in the message. */
export function isFileTooLargeCodeMessage(message: string): boolean {
return message === FILE_TOO_LARGE_CODE
}
// Why both: hosts answer with the `file_too_large` code (carried as the message); local readers in prose.
export function isFileTooLargeMessage(message: string): boolean {
return isFileTooLargeCodeMessage(message) || /\btoo large\b|\bis larger than\b/i.test(message)
}
function isFileTooLargeToReadError(error: unknown): boolean {
if (!(error instanceof Error)) {
return false
}
const code = 'code' in error ? error.code : undefined
return code === FILE_TOO_LARGE_CODE || isFileTooLargeMessage(error.message)
}
/** Settles a precondition whose disk read failed; rethrows anything that doesn't prove the disk state. */
export function diskConflictFromReadFailure(
precondition: FileWriteDiskPrecondition,
error: unknown
): FileWriteDiskConflict | null {
if (isConfirmedFileNotFoundError(error)) {
return precondition.allowMissing === true ? null : 'missing'
}
// Why: the baseline was read whole, so content too big to read now cannot match it.
if (isFileTooLargeToReadError(error)) {
return 'changed'
}
throw error
}
/** For writers that create or restore a file: write only where none exists or it already holds `content`. */
export function missingOrIdenticalPrecondition(content: string): FileWriteDiskPrecondition {
return { expectedSignature: getWrittenContentDiskSignature(content), allowMissing: true }
}
export const FILE_ALREADY_EXISTS_DIFFERENTLY_MESSAGE =
'A different file already exists at this path, so it was left unchanged.'
/** A write the host refused before writing anything, so retrying it later is safe. */
export class FileWriteRefusedError extends Error {
constructor() {
super(FILE_ALREADY_EXISTS_DIFFERENTLY_MESSAGE)
this.name = 'FileWriteRefusedError'
}
}
/** Turns a refusal into the error a caller's existing failure path already reports. */
export function assertFileWriteApplied(result: FileWriteResult): void {
if (!result.ok) {
throw new FileWriteRefusedError()
}
}