/**
 * A connected client's view of its hub's provider, login and roster state (#4236).
 *
 * The rule this module exists to enforce: on a connected client, the hub is the authority, and
 * when the hub cannot be read the answer is "unavailable" — never the client's own local
 * credential store. That store is empty by design, and reporting it as the truth is what made an
 * agent on a connected machine conclude the hub could not serve grok while the hub was serving
 * grok. Every failure path here therefore lands on `stateSource: "unavailable"` with a reason a
 * human can act on, and none of them reaches back into local config.
 *
 * The last good response is cached at `<OPENCODEX_HOME>/hub-state.json`, 0600, stamped with the
 * connection that produced it. The owner stamp is not decoration: after `ocx disconnect` and a
 * reconnect to a different hub (or a key rotation that changes `apiKeyId`), a stale file would
 * otherwise be presented as this hub's state. `sameClientConnectionOwner` is the same triple
 * (`serverUrl`, `apiKeyId`, `connectedAt`) the rest of the client lifecycle compares on.
 */
import { existsSync, lstatSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { getConfigDir } from "../config";
import { atomicWriteFile } from "../config/atomic-write";
import { parseHubStateBody, type HubStateDTO } from "../remote/hub-state";
import type { OcxClientConnectionConfig } from "../types";
import { fetchHubState, HubClientError } from "./hub-client";
import { sameClientConnectionOwner } from "./state";

/** Bound the status path: `ocx status` must answer even when the hub is gone. */
const DEFAULT_HUB_STATE_TIMEOUT_MS = 3_000;
/** The cache document plus its stamp; the DTO itself is already capped by its own contract. */
const MAX_CACHE_BYTES = 128 * 1024;

export type HubStateOwner = Pick<OcxClientConnectionConfig, "serverUrl" | "apiKeyId" | "connectedAt">;

/** Where the state came from. "unavailable" is a reportable outcome, not a fallback to local. */
export type HubStateSource = "hub" | "cache" | "unavailable";

export interface HubStateResolution {
  stateSource: HubStateSource;
  state: HubStateDTO | null;
  /** Present whenever the live read did not succeed. Short, operator-facing. */
  reason?: string;
  /** ISO timestamp of the response this state came from. */
  fetchedAt?: string;
  ageSeconds?: number;
}

export function hubStateCachePath(): string {
  return join(getConfigDir(), "hub-state.json");
}

interface CacheDocument {
  version: 1;
  owner: HubStateOwner;
  fetchedAt: string;
  state: HubStateDTO;
}

function readCacheDocument(): CacheDocument | null {
  const path = hubStateCachePath();
  if (!existsSync(path)) return null;
  try {
    const stat = lstatSync(path);
    // A symlink or an oversized file is refused rather than followed: this file is written
    // 0600 by us, and anything else about it is someone else's doing.
    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_CACHE_BYTES) return null;
    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
    const doc = raw as Record<string, unknown>;
    if (doc.version !== 1) return null;
    const owner = doc.owner;
    if (!owner || typeof owner !== "object" || Array.isArray(owner)) return null;
    const ownerRow = owner as Record<string, unknown>;
    if (typeof ownerRow.serverUrl !== "string" || typeof ownerRow.apiKeyId !== "string"
      || typeof ownerRow.connectedAt !== "string") return null;
    if (typeof doc.fetchedAt !== "string" || Number.isNaN(Date.parse(doc.fetchedAt))) return null;
    const state = parseHubStateBody(doc.state);
    if (!state) return null;
    return {
      version: 1,
      owner: {
        serverUrl: ownerRow.serverUrl,
        apiKeyId: ownerRow.apiKeyId,
        connectedAt: ownerRow.connectedAt,
      },
      fetchedAt: doc.fetchedAt,
      state,
    };
  } catch {
    return null;
  }
}

/** The cached state for THIS connection, or null when absent, malformed, or another hub's. */
export function readCachedHubState(owner: HubStateOwner): { state: HubStateDTO; fetchedAt: string } | null {
  const doc = readCacheDocument();
  if (!doc) return null;
  if (!sameClientConnectionOwner(doc.owner, owner)) return null;
  return { state: doc.state, fetchedAt: doc.fetchedAt };
}

/** Best-effort: a cache that cannot be written must never fail the command that asked. */
export function writeCachedHubState(owner: HubStateOwner, state: HubStateDTO, fetchedAt: string): boolean {
  try {
    const document: CacheDocument = {
      version: 1,
      owner: { serverUrl: owner.serverUrl, apiKeyId: owner.apiKeyId, connectedAt: owner.connectedAt },
      fetchedAt,
      state,
    };
    atomicWriteFile(hubStateCachePath(), `${JSON.stringify(document, null, 2)}\n`);
    return true;
  } catch {
    return false;
  }
}

/**
 * Why the live read did not land, in words an operator can act on.
 *
 * `hub_state_unsupported` is the version-skew case and gets an explicit upgrade instruction:
 * left as a bare code it reads like a bug in the client.
 *
 * Every code `fetchHubState` can throw has a sentence here, including the open-ended
 * `hub_state_http_<status>` family. This reason is printed in the `ocx status` banner, and a
 * banner reading `state unavailable (hub_state_http_507)` sends the reader looking for a client
 * bug when the hub has in fact answered and said something.
 */
export function hubStateFailureReason(error: unknown, peer: "hub" | "Home" = "hub"): string {
  // A Remote Link Child reads the same route from its Home (#6957); the sentences name the peer
  // the operator actually configured.
  const holder = peer === "Home" ? "this Child's link key" : "this client's data key";
  if (error instanceof HubClientError) {
    switch (error.code) {
      case "hub_state_not_a_hub":
        return "the remote host does not publish hub state";
      case "hub_state_unsupported":
        return `this ${peer} is too old to report its state; upgrade the ${peer}`;
      case "hub_state_unauthorized":
        return `the ${peer} rejected ${holder}`;
      case "hub_state_schema_invalid":
      case "hub_state_invalid":
        return `the ${peer} returned an unreadable hub-state document`;
      case "hub_state_content_type_invalid":
        // Usually a captive portal, a TLS-terminating proxy or an error page in front of the
        // hub: the request reached SOMETHING, and that something is not the hub's API.
        return `the ${peer}'s state response was not JSON`;
      case "body_too_large":
        return `the ${peer}'s state response exceeded the allowed size`;
      case "unreachable":
        return `the ${peer} is unreachable`;
      case "redirect_refused":
        return `the ${peer} redirected the state request`;
      default: {
        const status = error.code.startsWith("hub_state_http_")
          ? error.code.slice("hub_state_http_".length)
          : null;
        return status && /^\d+$/.test(status)
          ? `the ${peer} answered HTTP ${status} to the state request`
          : error.code;
      }
    }
  }
  if (error instanceof Error && error.name === "LinkRelayAuthenticationError") return error.message;
  return `the ${peer} state could not be read`;
}

export interface ResolveHubStateOptions {
  owner: HubStateOwner;
  /** The per-client data key. Null when the token file is missing or unsafe. */
  token: string | null;
  /**
   * Why the caller withheld the token, when it withheld one it holds. A null token reads the
   * same here whether the file is missing or the caller declined to send a perfectly good
   * token for a different connection, and the operator acts on that difference.
   */
  withheldTokenReason?: string;
  /** Identity-checked local Child transport that strips credentials and owns Home admission. */
  localRelayFetchImpl?: typeof fetch;
  timeoutMs?: number;
  fetchImpl?: typeof fetch;
  now?: number;
  /** False reads only the cache — for paths that must not make a network call. */
  allowNetwork?: boolean;
  /** False skips the cache write, for read-only callers. */
  persist?: boolean;
  /** Which peer the sentences name: a hub, or a Remote Link Child's Home. */
  peer?: "hub" | "Home";
}

function withAge(
  source: HubStateSource,
  state: HubStateDTO | null,
  fetchedAt: string | undefined,
  now: number,
  reason?: string,
): HubStateResolution {
  const ageSeconds = fetchedAt ? Math.max(0, Math.floor((now - Date.parse(fetchedAt)) / 1000)) : undefined;
  return {
    stateSource: source,
    state,
    ...(reason ? { reason } : {}),
    ...(fetchedAt ? { fetchedAt } : {}),
    ...(ageSeconds === undefined || Number.isNaN(ageSeconds) ? {} : { ageSeconds }),
  };
}

export async function resolveHubState(options: ResolveHubStateOptions): Promise<HubStateResolution> {
  const now = options.now ?? Date.now();
  const fromCache = (reason: string): HubStateResolution => {
    const cached = readCachedHubState(options.owner);
    return cached
      ? withAge("cache", cached.state, cached.fetchedAt, now, reason)
      : withAge("unavailable", null, undefined, now, reason);
  };
  if (!options.token && !options.localRelayFetchImpl) {
    return fromCache(options.withheldTokenReason ?? "this client has no usable data-plane token");
  }
  if (options.allowNetwork === false) return fromCache("a live hub read was not attempted");
  let state: HubStateDTO;
  try {
    state = await fetchHubState(options.owner.serverUrl, options.localRelayFetchImpl ? null : options.token, {
      timeoutMs: options.timeoutMs ?? DEFAULT_HUB_STATE_TIMEOUT_MS,
      ...((options.localRelayFetchImpl ?? options.fetchImpl) ? { fetchImpl: options.localRelayFetchImpl ?? options.fetchImpl } : {}),
    });
  } catch (error) {
    // Deliberately no local-state fallback here. A stale cache is still the HUB's state; the
    // client's own providers and logins are not, at any age.
    if (error instanceof HubClientError && error.code === "hub_state_not_a_hub") return withAge("unavailable", null, undefined, now, hubStateFailureReason(error, options.peer));
    return fromCache(hubStateFailureReason(error, options.peer));
  }
  const fetchedAt = new Date(now).toISOString();
  if (options.persist !== false) writeCachedHubState(options.owner, state, fetchedAt);
  return withAge("hub", state, fetchedAt, now);
}
