Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* gfs:// URI parsing + resolution (spec §Global reference scheme).
*
* URI forms:
* identity (canonical): gfs://<drive>/<rid>
* human (display+id): gfs://<drive>/<display/path>/<slug>-<rid>
*
* Precedence: the identity form (a single 32-hex segment) is ALWAYS the rid,
* never by-path. In the human form the rid is the trailing 32 hex of the final
* segment; the rest is display. `rid` ALWAYS wins when it resolves; only when
* the parsed UUID has no row does resolution fall back to by-path (so a file
* legitimately named with trailing hex is not mis-parsed).
*/
const RID_RE = /^[0-9a-f]{32}$/
const TRAILING_RID_RE = /-([0-9a-f]{32})$/
export class GfsUriError extends Error {
readonly code = 'path_invalid'
constructor(message: string) {
super(message)
this.name = 'GfsUriError'
}
}
export interface ParsedGfsUri {
drive: string
/** A candidate 32-hex rid, when the URI carries one (identity or human form). */
rid: string | null
/** The absolute display path, for by-path fallback. Null for the identity form. */
byPath: string | null
}
export function parseGfsUri(uri: string): ParsedGfsUri {
if (typeof uri !== 'string' || !uri.startsWith('gfs://')) {
throw new GfsUriError(`not a gfs URI: ${JSON.stringify(uri)}`)
}
const segments = uri
.slice('gfs://'.length)
.split('/')
.filter(s => s.length > 0)
if (segments.length < 2) {
throw new GfsUriError(`gfs URI must be gfs://<drive>/<resource>: ${uri}`)
}
const drive = segments[0]
const pathSegments = segments.slice(1)
// Identity form — a single 32-hex segment is ALWAYS the rid (never by-path).
if (pathSegments.length === 1 && RID_RE.test(pathSegments[0])) {
return { drive, rid: pathSegments[0], byPath: null }
}
const byPath = '/' + pathSegments.join('/')
// Human form — rid = trailing 32 hex of the final segment, after the last '-'.
const match = TRAILING_RID_RE.exec(pathSegments[pathSegments.length - 1])
if (match) {
return { drive, rid: match[1], byPath }
}
// Pure by-path form — no trailing rid.
return { drive, rid: null, byPath }
}
export interface ResolvedResource {
resourceId: string
drive: string
name: string
kind: string
pathCache: string | null
bytes: number
version: number
updatedAt: string
}
export interface ResolveStore {
getByRid(drive: string, rid: string): Promise<ResolvedResource | null>
getByPath(drive: string, path: string): Promise<ResolvedResource | null>
}
/**
* Resolve a gfs:// URI to a resource. Returns null when nothing resolves (the
* route maps that to 404). Throws GfsUriError only when the URI is malformed.
*/
export async function resolveGfsUri(
store: ResolveStore,
uri: string
): Promise<ResolvedResource | null> {
const parsed = parseGfsUri(uri)
if (parsed.rid) {
const byRid = await store.getByRid(parsed.drive, parsed.rid)
if (byRid) return byRid // rid always wins
}
if (parsed.byPath) {
const byPath = await store.getByPath(parsed.drive, parsed.byPath)
if (byPath) return byPath
}
return null
}
/** Minimal query surface — a pg client/pool satisfies this; tests inject a fake. */
export interface ResolveDb {
query(text: string, values?: unknown[]): Promise<{ rows: unknown[] }>
}
const SELECT_COLS = 'resource_id, drive, name, kind, path_cache, bytes, version, updated_at'
function toIsoTimestamp(value: unknown): string {
if (value instanceof Date) return value.toISOString()
if (typeof value === 'string' && value.length > 0) {
const parsed = new Date(value)
return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString()
}
throw new Error('gfs_resources.updated_at is required')
}
function rowToResource(row: unknown): ResolvedResource {
const r = row as {
resource_id: unknown
drive: unknown
name: unknown
kind: unknown
path_cache: unknown
bytes: unknown
version: unknown
updated_at: unknown
}
return {
resourceId: String(r.resource_id),
drive: String(r.drive),
name: String(r.name),
kind: String(r.kind),
pathCache: r.path_cache == null ? null : String(r.path_cache),
bytes: Number(r.bytes),
version: Number(r.version),
updatedAt: toIsoTimestamp(r.updated_at),
}
}
/**
* DB-backed resolver. getByRid is a single keyed lookup; getByPath walks the
* path segments from the synthetic root (parent IS NULL), one hop per segment.
* A missing rid row or a missing path segment resolves to null (→ 404).
*/
export class DbResolveStore implements ResolveStore {
constructor(private readonly db: ResolveDb) {}
async getByRid(drive: string, rid: string): Promise<ResolvedResource | null> {
const result = await this.db.query(
`SELECT ${SELECT_COLS} FROM gfs_resources
WHERE drive = $1 AND resource_id = $2::uuid AND deleted_at IS NULL`,
[drive, rid]
)
return result.rows.length > 0 ? rowToResource(result.rows[0]) : null
}
async getByPath(drive: string, path: string): Promise<ResolvedResource | null> {
const segments = path.split('/').filter(s => s.length > 0)
const root = await this.db.query(
`SELECT ${SELECT_COLS} FROM gfs_resources
WHERE drive = $1 AND parent_resource_id IS NULL AND deleted_at IS NULL`,
[drive]
)
if (root.rows.length === 0) return null
let current = rowToResource(root.rows[0])
for (const segment of segments) {
const child = await this.db.query(
`SELECT ${SELECT_COLS} FROM gfs_resources
WHERE drive = $1 AND parent_resource_id = $2::uuid AND name = $3 AND deleted_at IS NULL`,
[drive, current.resourceId, segment]
)
if (child.rows.length === 0) return null
current = rowToResource(child.rows[0])
}
return current
}
}