@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
335 lines (312 loc) • 14.9 kB
text/typescript
import { lstatSync, mkdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { atomicWriteFileNoFollow } from "../config/atomic-write";
import { getConfigDir } from "../config/paths";
import { recordOwnedConfigPath } from "../lib/config-ownership";
import type { OcxConfig, OcxTelemetryConfig } from "../types";
import { parseCalendarUtcDayMs } from "./contract";
import { deleteTelemetryInstallId } from "./install-id";
/**
* `telemetry-state.json`: sent days, opt-out bookkeeping and the pending decision. Kept apart from
* the scheduler so the server's background lifecycle can record an env opt-out without loading the
* scheduler, aggregation, payload and sender modules.
*/
export const TELEMETRY_STATE_FILE = "telemetry-state.json";
const DAY_MS = 86_400_000;
const STATE_RETENTION_DAYS = 30;
/**
* How often a proxy running under an env opt-out records itself again, so a state file rebuilt after
* corruption (which forgets every owner) learns that the proxy is still opted out.
*/
export const TELEMETRY_ENV_OPT_OUT_REFRESH_MS = 6 * 60 * 60 * 1000;
/** A proxy that started under an env opt-out and has not stopped cleanly yet. */
export interface TelemetryEnvOptOutOwner {
pid: number;
since: string;
}
export interface TelemetryState {
version: 1;
sentDays: Record<string, string>;
lastSentDay: string | null;
lastSentAt: string | null;
ineligibleThroughDay: string | null;
retryAfterUntil: string | null;
/**
* Set whenever an env opt-out is observed and cleared only by a clean opted-out shutdown or by the
* next tick that runs without the opt-out. While it is set, every day up to the current one is
* ineligible, because a proxy started under `OCX_TELEMETRY=0` reads the env once and runs no ticks
* that could keep `ineligibleThroughDay` current (D2).
*/
envOptOutActiveSince?: string | null;
/**
* Proxies running under an env opt-out. A tick without the opt-out ends the period only once all
* of them have exited, so a second proxy sharing the home cannot reopen days the first still covers.
*/
envOptOutOwners?: TelemetryEnvOptOutOwner[];
/**
* A decision made before `config.json` exists (the Windows installer opt-out, `ocx telemetry
* disable` or the dashboard on a fresh install). Writing the config would turn the install into a
* configured one and make `ocx init` skip setup, so the decision waits here and applies until a
* decision is written into the config.
*/
pendingDecision?: OcxTelemetryConfig | null;
/** Set once any report was accepted, so an id minted after an opt-out is not counted as a new install. */
everReported?: boolean;
}
export function telemetryStatePath(configDir = getConfigDir()): string {
return join(configDir, TELEMETRY_STATE_FILE);
}
function emptyState(): TelemetryState {
return {
version: 1,
sentDays: {},
lastSentDay: null,
lastSentAt: null,
ineligibleThroughDay: null,
retryAfterUntil: null,
envOptOutActiveSince: null,
envOptOutOwners: [],
pendingDecision: null,
everReported: false,
};
}
function parseOwners(raw: unknown): TelemetryEnvOptOutOwner[] {
if (!Array.isArray(raw)) return [];
const owners: TelemetryEnvOptOutOwner[] = [];
for (const entry of raw.slice(0, 64)) {
if (!entry || typeof entry !== "object") continue;
const { pid, since } = entry as Record<string, unknown>;
if (typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0 && typeof since === "string" && !Number.isNaN(Date.parse(since))) {
owners.push({ pid, since });
}
}
return owners;
}
function ownersAreValid(raw: unknown): boolean {
return Array.isArray(raw) && raw.length <= 64 && raw.every(entry => {
if (!entry || typeof entry !== "object") return false;
const { pid, since } = entry as Record<string, unknown>;
return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0 && typeof since === "string" && !Number.isNaN(Date.parse(since));
});
}
/** A held decision that is present but cannot be trusted returns "invalid", which blocks sending. */
function parsePendingDecision(raw: unknown, fileTime: Date): OcxTelemetryConfig | null | "invalid" {
if (raw === undefined || raw === null) return null;
if (typeof raw !== "object" || Array.isArray(raw)) return "invalid";
const value = raw as Record<string, unknown>;
if (value.decision !== "accepted" && value.decision !== "declined") return "invalid";
const stamp = (key: string): string | null =>
typeof value[key] === "string" && !Number.isNaN(Date.parse(value[key] as string)) ? (value[key] as string) : null;
const decidedAt = stamp("decidedAt");
if (!decidedAt) {
// A decline needs no date to apply; dropping it could let a notice-only config send.
if (value.decision !== "declined") return "invalid";
const at = stamp("noticeShownAt") ?? fileTime.toISOString();
return { decision: "declined", decidedAt: at, noticeShownAt: at };
}
return { decision: value.decision, decidedAt, noticeShownAt: stamp("noticeShownAt") ?? decidedAt };
}
/**
* Read the state, noting whether a file exists but cannot be trusted (a symlink, oversized or
* malformed, or with an opt-out field that is present but invalid). Such a file must not be read as
* empty: that would forget opt-out days. Only a file that does not exist reads as empty.
*/
export function readTelemetryStateFile(configDir = getConfigDir()): { state: TelemetryState; unreadable: boolean } {
const path = telemetryStatePath(configDir);
let stat;
try {
stat = lstatSync(path);
} catch (error) {
const missing = (error as NodeJS.ErrnoException)?.code === "ENOENT";
return { state: emptyState(), unreadable: !missing };
}
try {
if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024) return { state: emptyState(), unreadable: true };
const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
if (raw?.version !== 1 || !raw.sentDays || typeof raw.sentDays !== "object" || Array.isArray(raw.sentDays)) {
return { state: emptyState(), unreadable: true };
}
const sentDays: Record<string, string> = {};
for (const [day, at] of Object.entries(raw.sentDays as Record<string, unknown>)) {
if (/^\d{4}-\d{2}-\d{2}$/.test(day) && typeof at === "string") {
sentDays[day] = at;
}
}
// Opt-out fields may be absent or null; present but invalid means the file cannot be trusted.
const present = (value: unknown) => value !== undefined && value !== null;
if (present(raw.ineligibleThroughDay)
&& !(typeof raw.ineligibleThroughDay === "string" && parseCalendarUtcDayMs(raw.ineligibleThroughDay) !== null)) {
return { state: emptyState(), unreadable: true };
}
if (present(raw.envOptOutActiveSince)
&& !(typeof raw.envOptOutActiveSince === "string" && !Number.isNaN(Date.parse(raw.envOptOutActiveSince)))) {
return { state: emptyState(), unreadable: true };
}
if (present(raw.envOptOutOwners) && !ownersAreValid(raw.envOptOutOwners)) {
return { state: emptyState(), unreadable: true };
}
const pendingDecision = parsePendingDecision(raw.pendingDecision, stat.mtime);
if (pendingDecision === "invalid") return { state: emptyState(), unreadable: true };
const ineligibleThroughDay = typeof raw.ineligibleThroughDay === "string" ? raw.ineligibleThroughDay : null;
const retryAfterUntil =
typeof raw.retryAfterUntil === "string" && !Number.isNaN(Date.parse(raw.retryAfterUntil))
? raw.retryAfterUntil
: null;
const envOptOutActiveSince = typeof raw.envOptOutActiveSince === "string" ? raw.envOptOutActiveSince : null;
return { unreadable: false, state: {
version: 1,
sentDays,
lastSentDay: typeof raw.lastSentDay === "string" ? raw.lastSentDay : null,
lastSentAt: typeof raw.lastSentAt === "string" ? raw.lastSentAt : null,
ineligibleThroughDay,
retryAfterUntil,
envOptOutActiveSince,
envOptOutOwners: parseOwners(raw.envOptOutOwners),
pendingDecision,
everReported: raw.everReported === true,
} };
} catch {
return { state: emptyState(), unreadable: true };
}
}
export function readTelemetryState(configDir = getConfigDir()): TelemetryState {
return readTelemetryStateFile(configDir).state;
}
/**
* Read the state for a rewrite. A file that exists but cannot be read may have held opt-out days
* or sent days and opted-out proxies that are still running, so the rewrite starts from "nothing
* may be sent through the UTC day those proxies have recorded themselves again by".
*/
function readTelemetryStateForWrite(configDir: string, now: number): TelemetryState {
const { state, unreadable } = readTelemetryStateFile(configDir);
if (unreadable) extendIneligibleThroughToday(state, now + TELEMETRY_ENV_OPT_OUT_REFRESH_MS);
return state;
}
export function writeTelemetryState(state: TelemetryState, configDir = getConfigDir(), now = Date.now()): void {
mkdirSync(configDir, { recursive: true, mode: 0o700 });
const path = telemetryStatePath(configDir);
try { recordOwnedConfigPath(configDir, path); } catch { /* best-effort */ }
const minKeepDay = formatUtcDay(utcMidnightMs(now) - STATE_RETENTION_DAYS * DAY_MS);
const prunedSentDays: Record<string, string> = {};
for (const [day, at] of Object.entries(state.sentDays ?? {})) {
if (day >= minKeepDay) prunedSentDays[day] = at;
}
const payload: TelemetryState = {
version: 1,
sentDays: prunedSentDays,
lastSentDay: state.lastSentDay ?? null,
lastSentAt: state.lastSentAt ?? null,
ineligibleThroughDay: state.ineligibleThroughDay ?? null,
retryAfterUntil: state.retryAfterUntil ?? null,
envOptOutActiveSince: state.envOptOutActiveSince ?? null,
envOptOutOwners: state.envOptOutOwners ?? [],
pendingDecision: state.pendingDecision ?? null,
everReported: state.everReported === true,
};
atomicWriteFileNoFollow(path, `${JSON.stringify(payload, null, 2)}\n`);
}
/** Hold a decision made before `config.json` exists. */
export function recordPendingTelemetryDecision(
decision: OcxTelemetryConfig,
configDir = getConfigDir(),
now = Date.now(),
): void {
const state = readTelemetryStateForWrite(configDir, now);
state.pendingDecision = structuredClone(decision);
writeTelemetryState(state, configDir, now);
}
/**
* Drop the pending decision once a decision is written into `config.json`. A person's decision also
* rebuilds an unreadable state file, which otherwise pauses sending for good.
*/
export function clearPendingTelemetryDecision(configDir = getConfigDir(), now = Date.now()): void {
const { state: current, unreadable } = readTelemetryStateFile(configDir);
if (unreadable) {
// Best effort: the decision is already saved. If the rebuild fails, the file stays unreadable,
// which keeps sending blocked.
try {
const rebuilt = readTelemetryStateForWrite(configDir, now);
rebuilt.pendingDecision = null;
writeTelemetryState(rebuilt, configDir, now);
} catch { /* keep the unreadable file */ }
return;
}
if (!current.pendingDecision) return;
current.pendingDecision = null;
writeTelemetryState(current, configDir, now);
}
/**
* The telemetry block consent is resolved from: the config's own decision when it has one,
* otherwise a decision held from before `config.json` existed, otherwise whatever the config says.
*/
export function withPendingTelemetryDecision<T extends Pick<OcxConfig, "telemetry">>(
config: T | null | undefined,
configDir = getConfigDir(),
): Pick<OcxConfig, "telemetry"> | null | undefined {
if (config?.telemetry?.decision) return config;
const pending = readTelemetryState(configDir).pendingDecision;
if (!pending) return config;
return { ...(config ?? {}), telemetry: structuredClone(pending) };
}
function isProcessAlive(pid: number): boolean {
try {
process.kill(pid, 0);
return true;
} catch (error) {
return (error as NodeJS.ErrnoException)?.code === "EPERM";
}
}
function extendIneligibleThroughToday(state: TelemetryState, now: number): void {
const todayDay = formatUtcDay(utcMidnightMs(now));
if (!state.ineligibleThroughDay || state.ineligibleThroughDay < todayDay) {
state.ineligibleThroughDay = todayDay;
}
}
/**
* Persist `ineligibleThroughDay = today's UTC day` and the active opt-out marker in
* `telemetry-state.json` (atomic no-follow) and delete `telemetry-id.json` whenever an
* `OCX_TELEMETRY` or `DO_NOT_TRACK` opt-out is observed. A proxy that runs under the opt-out
* passes its pid as `owner`; a one-off observation (a CLI command, a tick) passes none.
*/
export function recordTelemetryEnvOptOut(configDir = getConfigDir(), now = Date.now(), owner?: number): void {
const state = readTelemetryStateForWrite(configDir, now);
extendIneligibleThroughToday(state, now);
if (owner === undefined) {
state.envOptOutActiveSince ??= new Date(now).toISOString();
} else {
// Drop owners that have exited (their days through today are covered above) and stay within the
// 64 entries a reader accepts.
const owners = (state.envOptOutOwners ?? [])
.filter(entry => entry.pid !== owner && isProcessAlive(entry.pid))
.slice(-63);
state.envOptOutOwners = [...owners, { pid: owner, since: new Date(now).toISOString() }];
}
writeTelemetryState(state, configDir, now);
deleteTelemetryInstallId(configDir);
}
/**
* Close an env opt-out period so only days strictly after today can be sent. A clean stop of an
* opted-out proxy passes its pid and always covers its stop day. A tick passes none: it ends the
* period only when no recorded opted-out proxy is still running, and otherwise extends
* `ineligibleThroughDay` to today. Returns true while an opted-out proxy is still running.
*/
export function endTelemetryEnvOptOut(configDir = getConfigDir(), now = Date.now(), owner?: number): boolean {
const state = readTelemetryStateForWrite(configDir, now);
const recorded = state.envOptOutOwners ?? [];
const others = owner === undefined ? recorded : recorded.filter(entry => entry.pid !== owner);
const running = others.filter(entry => isProcessAlive(entry.pid));
if (owner === undefined && !state.envOptOutActiveSince && recorded.length === 0) return false;
extendIneligibleThroughToday(state, now);
state.envOptOutOwners = running;
if (running.length === 0) state.envOptOutActiveSince = null;
writeTelemetryState(state, configDir, now);
deleteTelemetryInstallId(configDir);
return running.length > 0;
}
export function utcMidnightMs(epochMs: number): number {
const d = new Date(epochMs);
return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
}
export function formatUtcDay(epochMs: number): string {
return new Date(epochMs).toISOString().slice(0, 10);
}