import type { Metadata } from "next";
import { PLAN_LIMITS } from "@fetcha/core";
import { CodeBlock } from "@/components/ui/code-block";
import { Badge } from "@/components/ui/badge";
import { DocPage } from "@/components/docs/doc-page";
import { A, Code, H2, H3, Li, P, Strong, Table, TBody, Td, Th, THead, Tr, Ul } from "@/components/docs/prose";
import { Callout } from "@/components/docs/callout";
import { CodeTabs } from "@/components/docs/code-tabs";
import { ResponseExample } from "@/components/docs/response-example";
import { fetchTabs } from "@/components/docs/snippets";

export const metadata: Metadata = {
  title: "Network Selection",
  description: "Network classes, what auto does, how routes are scored, per-domain intelligence, escalation, circuit breakers and which classes are available (all of them).",
};

const CLASSES: Array<{ name: string; live: boolean; desc: string }> = [
  { name: "auto", live: true, desc: "Let the engine choose. Cheapest class first, escalating to more reliable classes on blocks. Resolves to residential today." },
  { name: "residential", live: true, desc: "Exit IPs assigned by consumer ISPs to households. Highest acceptance on sites that filter datacenter traffic. Geo-targetable." },
  { name: "datacenter", live: false, desc: "Exit IPs from hosting providers. Fastest and cheapest, most often blocked. Included, no live route yet." },
  { name: "isp", live: false, desc: "Static IPs registered to consumer ISPs but hosted in datacenters. Residential reputation with datacenter speed. Included, no live route yet." },
  { name: "mobile", live: false, desc: "Exit IPs from cellular carriers. Highest acceptance, highest cost. Included, no live route yet." },
];

const ALL_NETWORKS = ["datacenter", "residential", "isp", "mobile"] as const;
const L = PLAN_LIMITS.unlimited;

export default function NetworksPage() {
  return (
    <DocPage path="/docs/networks" eyebrow="Core API" title="Network selection" description="Fetcha routes requests across classes of networks rather than individual proxies. You pick a class, or let auto pick for you, and the engine handles scoring, escalation and health." status="Stable">
      <H2>Network classes</H2>
      <P>
        The <Code>network</Code> field of a fetch request accepts one of five values. Classes describe the <Strong>kind</Strong> of exit IP; the upstream networks behind each class are managed by
        Fetcha and never exposed.
      </P>
      <Table>
        <THead>
          <Tr>
            <Th>Value</Th>
            <Th>Status</Th>
            <Th>Description</Th>
          </Tr>
        </THead>
        <TBody>
          {CLASSES.map((c) => (
            <Tr key={c.name}>
              <Td mono>{c.name}</Td>
              <Td>
                <Badge variant={c.live ? "success" : "warning"} dot>
                  {c.live ? "Live" : "Coming soon"}
                </Badge>
              </Td>
              <Td>{c.desc}</Td>
            </Tr>
          ))}
        </TBody>
      </Table>
      <Callout variant="warning" title="What happens today">
        Only the <Code>residential</Code> class has live capacity. <Code>auto</Code> therefore resolves to residential and <Code>metadata.network</Code> reports <Code>{`"residential"`}</Code>. Requesting{" "}
        <Code>datacenter</Code>, <Code>isp</Code> or <Code>mobile</Code> explicitly returns <Code>400 NETWORK_UNAVAILABLE</Code> because the class has no live route yet — never because of your plan: all
        classes are included for every organization. When those classes launch, <Code>auto</Code> will start using them without any change on your side.
      </Callout>

      <H2>What auto does</H2>
      <P>
        <Code>auto</Code> is the default and the recommended setting. For each request the routing engine builds an ordered list of candidate routes (a route is one upstream network serving one class),
        then executes them in order until one succeeds or the retry budget is spent.
      </P>
      <H3>1. Eligible classes</H3>
      <P>
        The engine starts from the escalation order <Code>datacenter → isp → residential → mobile</Code> (all four classes are available to every organization) and drops classes that have no
        configured, healthy route right now. If the domain has an admin-pinned <Code>force_network</Code> policy, only that class is considered.
      </P>
      <H3>2. Scoring</H3>
      <P>Every eligible route receives a score between 0 and 1, computed as a weighted sum of six signals:</P>
      <Table>
        <THead>
          <Tr>
            <Th>Weight</Th>
            <Th>Signal</Th>
            <Th>How it is measured</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td mono>35 %</Td>
            <Td>Historical success</Td>
            <Td>
              Success rate of this route on this domain, Bayesian-smoothed toward a per-class prior (datacenter 70 %, isp 85 %, residential 93 %, mobile 95 %) so new domains start with sensible
              expectations.
            </Td>
          </Tr>
          <Tr>
            <Td mono>20 %</Td>
            <Td>Cost</Td>
            <Td>Price per GB of the route, normalised against the most expensive class (about $15/GB).</Td>
          </Tr>
          <Tr>
            <Td mono>15 %</Td>
            <Td>Latency</Td>
            <Td>Average latency observed on this domain (300 ms scores 1.0, 5 s scores 0). Without history, datacenter assumes 500 ms and other classes 1,200 ms.</Td>
          </Tr>
          <Tr>
            <Td mono>15 %</Td>
            <Td>Network health</Td>
            <Td>Health factor from the route&apos;s circuit breaker: 1.0 when closed and clean, degraded by recent failure ratio, 0.3 while half-open, 0 while open.</Td>
          </Tr>
          <Tr>
            <Td mono>10 %</Td>
            <Td>Geography</Td>
            <Td>Whether the route can serve the requested country, region and city.</Td>
          </Tr>
          <Tr>
            <Td mono>5 %</Td>
            <Td>Session stability</Td>
            <Td>Whether the route supports sticky sessions when the request carries one.</Td>
          </Tr>
        </TBody>
      </Table>
      <H3>3. Ordering and escalation</H3>
      <Ul>
        <Li>
          In <Code>auto</Code> mode, candidates are grouped by class in escalation order (cheap first) and sorted by score inside each class. Distinct routes are preferred before repeating one, so a
          retry usually changes both the exit IP and the route.
        </Li>
        <Li>
          <Strong>Per-domain intelligence:</Strong> if the domain profile shows a cheaper class being blocked more than 60 % of the time over at least 5 attempts, that class is skipped entirely for
          the domain. Residential is never skipped by this rule.
        </Li>
        <Li>
          The list is cut to your attempt budget: <Code>retries + 1</Code>, at most {L.max_retries + 1}. See <A href="/docs/retries">Retries</A>.
        </Li>
        <Li>
          With an explicit class (for example <Code>{`"network": "residential"`}</Code>), candidates are simply sorted by score; there is no cross-class escalation.
        </Li>
      </Ul>
      <H3>4. Learning</H3>
      <P>
        After every attempt, the domain profile is updated with the outcome (success, block, latency, cost). Profiles are shared across all Fetcha customers, so a site that starts blocking a class is
        learned once and avoided for everyone. Only aggregate statistics are stored; never your request or response content.
      </P>

      <H2>Circuit breakers</H2>
      <P>
        Each route has an in-memory circuit breaker so that an upstream incident does not turn into a wave of failed requests:
      </P>
      <Ul>
        <Li>Outcomes are tracked in a rolling 120-second window.</Li>
        <Li>
          The circuit <Strong>opens</Strong> when at least 8 samples are present and 60 % or more of them failed. An open route is excluded from routing and scores 0 on the health signal.
        </Li>
        <Li>After a 60-second cooldown the circuit becomes half-open: one request probes the route; success closes the circuit, failure reopens it.</Li>
        <Li>
          Only network-side failures count (upstream authentication or gateway errors, connection failures, 5xx from the gateway). A target that blocks or times out does not penalise the route.
        </Li>
      </Ul>
      <P>
        When every candidate route is open or unconfigured, <Code>auto</Code> requests fail fast with <Code>503 PROVIDER_UNAVAILABLE</Code> and explicit-class requests with{" "}
        <Code>400 NETWORK_UNAVAILABLE</Code>. Neither counts as a target failure and both are safe to retry after a short pause.
      </P>

      <H2>Availability</H2>
      <P>
        Fetcha has a single plan and no network class is gated: every organization may request any class. The only reason an explicit class is refused is the absence of a live route for it. The table
        reflects the platform configuration; remember that only residential is live today.
      </P>
      <Table>
        <THead>
          <Tr>
            <Th>Class</Th>
            <Th className="text-center">Included</Th>
            <Th className="text-center">Live route</Th>
          </Tr>
        </THead>
        <TBody>
          {ALL_NETWORKS.map((n) => {
            const live = CLASSES.find((c) => c.name === n)?.live ?? false;
            return (
              <Tr key={n}>
                <Td mono>{n}</Td>
                <Td className="text-center">{L.networks.includes(n) ? <span className="text-success">Yes</span> : <span className="text-fg-subtle">&mdash;</span>}</Td>
                <Td className="text-center">{live ? <span className="text-success">Yes</span> : <span className="text-fg-subtle">Not yet</span>}</Td>
              </Tr>
            );
          })}
        </TBody>
      </Table>

      <H2>Choosing a class</H2>
      <P>
        Prefer <Code>auto</Code>. Pin <Code>residential</Code> when you need to guarantee that no cheaper class is ever tried on a sensitive target. Read the served class from <Code>metadata.network</Code> and, with <Code>debug: true</Code>, the per-attempt route aliases from <Code>metadata.debug.attempts</Code>.
      </P>
      <CodeTabs
        tabs={fetchTabs(
          { url: "https://example.com", network: "residential", country: "US", debug: true },
          {
            javascript: `console.log(data.metadata.network, data.metadata.debug.attempts);`,
            python: `print(data["metadata"]["network"], data["metadata"]["debug"]["attempts"])`,
          },
          ["curl", "javascript", "python"],
        )}
      />
      <ResponseExample
        status={400}
        statusText="Bad Request"
        title="400 Bad Request · explicit class not available"
        body={{ error: { code: "NETWORK_UNAVAILABLE", message: 'The "mobile" network has no live route right now.', request_id: "req_0a1b2c3d4e5f6g7h" } }}
      />
      <CodeBlock
        lang="json"
        title="metadata.debug.attempts — escalation across two routes"
        code={JSON.stringify(
          {
            attempts: [
              { provider: "network-a", network: "residential", country: "US", outcome: "blocked", status: 403, duration_ms: 1320 },
              { provider: "network-b", network: "residential", country: "US", outcome: "success", status: 200, duration_ms: 1710 },
            ],
          },
          null,
          2,
        )}
      />
    </DocPage>
  );
}