import type { Metadata } from "next";
import { PLAN_LIMITS } from "@fetcha/core";
import { CodeBlock } from "@/components/ui/code-block";
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: "Retries",
  description: "How Fetcha retries and escalates: what triggers a retry, the retries option and its maximum, the shared timeout, attempt metadata, bandwidth implications and idempotency.",
};

const L = PLAN_LIMITS.unlimited;

export default function RetriesPage() {
  return (
    <DocPage path="/docs/retries" eyebrow="Reliability" title="Retries" description="Retries are built into every fetch. When a target blocks or a route fails, Fetcha tries again with a new exit identity and, when it helps, a different route, all within a single request and a single timeout." status="Stable">
      <H2>How a retry works</H2>
      <P>
        Before executing, the routing engine produces an ordered list of candidate routes for the request (see <A href="/docs/networks">Network selection</A>). Fetcha walks that list:
      </P>
      <Ul>
        <Li>
          <Strong>New IP.</Strong> Each attempt asks the network for a fresh exit identity, so a second attempt on the same route already comes from a different address. The exception is a request
          pinned to a <A href="/docs/sessions">session</A>, which deliberately keeps its identity.
        </Li>
        <Li>
          <Strong>Alternate route.</Strong> Distinct routes are preferred before repeating one. If several routes serve the same class, the second attempt typically goes through another one.
        </Li>
        <Li>
          <Strong>Escalation.</Strong> In <Code>auto</Code> mode, routes are ordered by class from cheapest to most reliable, so retries climb toward premium classes as they launch. With a single
          live class today, escalation happens between routes inside that class.
        </Li>
        <Li>
          <Strong>Learning.</Strong> Every attempt, successful or not, updates the domain profile and the route&apos;s circuit breaker.
        </Li>
      </Ul>

      <H3>What triggers a retry</H3>
      <Table dense>
        <THead>
          <Tr>
            <Th>Outcome of an attempt</Th>
            <Th>Retried?</Th>
            <Th>If all attempts fail</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td>Block page: HTTP 403, 407, 429 or 999; 503 challenge; captcha, anti-bot or WAF signatures</Td>
            <Td className="text-success">Yes</Td>
            <Td>
              <Code>200</Code> with <Code>success: false</Code> and the last blocked page
            </Td>
          </Tr>
          <Tr>
            <Td>Timeout waiting for the target</Td>
            <Td className="text-success">Yes, while budget remains</Td>
            <Td mono>504 TARGET_TIMEOUT</Td>
          </Tr>
          <Tr>
            <Td>Connection failure to the target</Td>
            <Td className="text-success">Yes</Td>
            <Td mono>502 TARGET_UNAVAILABLE</Td>
          </Tr>
          <Tr>
            <Td>Network-side failure (gateway error, upstream auth, 5xx from the route)</Td>
            <Td className="text-success">Yes</Td>
            <Td mono>503 PROVIDER_UNAVAILABLE</Td>
          </Tr>
          <Tr>
            <Td>2xx/3xx response that is not a block</Td>
            <Td>No, returned immediately</Td>
            <Td>&mdash;</Td>
          </Tr>
          <Tr>
            <Td>4xx/5xx response that is not a block (plain 404, 500, …)</Td>
            <Td>No, returned immediately with <Code>success: false</Code></Td>
            <Td>&mdash;</Td>
          </Tr>
          <Tr>
            <Td>Response larger than the size cap</Td>
            <Td className="text-danger">No</Td>
            <Td mono>502 RESPONSE_TOO_LARGE</Td>
          </Tr>
          <Tr>
            <Td>
              More than <Code>max_redirects</Code> hops
            </Td>
            <Td className="text-danger">No</Td>
            <Td mono>502 TOO_MANY_REDIRECTS</Td>
          </Tr>
          <Tr>
            <Td>Redirect to a private or internal host</Td>
            <Td className="text-danger">No</Td>
            <Td mono>400 URL_NOT_ALLOWED</Td>
          </Tr>
        </TBody>
      </Table>

      <H2>The retries option</H2>
      <P>
        <Code>retries</Code> is the number of <Strong>additional</Strong> attempts after the first; total attempts are <Code>retries + 1</Code>. Omit it to use the maximum. The schema accepts 0 to{" "}
        {L.max_retries}; the same maximum applies to every organization (single plan).
      </P>
      <Table>
        <THead>
          <Tr>
            <Th>Limit</Th>
            <Th>Value</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td className="font-medium text-fg">Max retries</Td>
            <Td mono>{L.max_retries}</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Max attempts</Td>
            <Td mono>{L.max_retries + 1}</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Max timeout</Td>
            <Td mono>{L.max_timeout_ms / 1000} s</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Browser fallback</Td>
            <Td>
              On by default (<Code>browser_fallback: true</Code>): a JavaScript challenge on an HTTP attempt escalates to the managed browser within the same budget.
            </Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        The candidate list is also bounded by how many distinct routes exist for the request. When there are fewer routes than attempts, the engine repeats the best route (with a new IP each time),
        so <Code>metadata.attempts</Code> may come out lower than <Code>retries + 1</Code> even on a fully blocked target.
      </P>
      <CodeTabs tabs={fetchTabs({ url: "https://shop.example.net/", retries: 0 }, { javascript: `console.log(data.metadata.attempts); // always 1 with retries: 0`, python: `print(data["metadata"]["attempts"])  # always 1 with retries: 0` }, ["curl", "javascript", "python"])} />

      <H2>One timeout for everything</H2>
      <P>
        <Code>timeout</Code> is the budget for the <Strong>whole</Strong> request, not per attempt. Each attempt receives what is left; when fewer than 500 ms remain, Fetcha stops and returns{" "}
        <Code>TARGET_TIMEOUT</Code>. If you rely on several attempts against slow targets, size <Code>timeout</Code> accordingly (up to {L.max_timeout_ms / 1000} s) rather than raising <Code>retries</Code>.
      </P>

      <H2>Attempts in metadata</H2>
      <P>
        <Code>metadata.attempts</Code> counts every attempt including the final one. <Code>metadata.duration_ms</Code> and <Code>metadata.bytes</Code> cover all of them. With <Code>debug: true</Code>,{" "}
        <Code>metadata.debug.attempts</Code> lists each attempt with the route alias, network, country, outcome, target status and duration.
      </P>
      <ResponseExample
        status={200}
        title="200 OK · metadata after one block and one success"
        body={{
          metadata: {
            network: "residential",
            country: "US",
            attempts: 2,
            duration_ms: 3140,
            bytes: 71822,
            session: null,
            cached: false,
            timing: { dns_ms: 17, proxy_connect_ms: 0, tls_ms: 0, origin_ms: 1402, processing_ms: 9, total_ms: 3140 },
            debug: {
              attempts: [
                { provider: "network-a", network: "residential", country: "US", outcome: "blocked", status: 403, duration_ms: 1210 },
                { provider: "network-b", network: "residential", country: "US", outcome: "success", status: 200, duration_ms: 1888 },
              ],
            },
          },
        }}
      />

      <H2>Usage implications</H2>
      <P>Fetcha has no billing, but retries still show up in your usage figures and in the internal cost estimate behind optional spending limits:</P>
      <Ul>
        <Li>
          <Strong>Bandwidth is counted for every attempt.</Strong> <Code>metadata.bytes</Code> sums request and response bytes across attempts. A block page is usually small, but a large page that
          gets blocked after being fully downloaded counts its full size.
        </Li>
        <Li>
          <Strong>Every request counts in your usage</Strong>, including failed and blocked ones, but there is no monthly quota; see <A href="/docs/rate-limits">Rate limits</A>.
        </Li>
        <Li>
          Requests refused before any attempt (validation, limits, <Code>URL_NOT_ALLOWED</Code>, session errors) transfer no bytes and are not counted.
        </Li>
      </Ul>

      <H2>Idempotency for POST and other writes</H2>
      <Callout variant="warning" title="Retries replay the request">
        A retry sends the <Strong>same method and body</Strong> again. If your <Code>POST</Code> creates an order, sends a message or otherwise has side effects on the target, an attempt that was
        processed by the origin but answered with something Fetcha classifies as a block (a 429 for instance) would be replayed.
      </Callout>
      <Ul>
        <Li>
          Set <Code>{`"retries": 0`}</Code> for non-idempotent writes and implement your own retry decision based on <Code>status</Code>.
        </Li>
        <Li>Where the target supports it, include an idempotency token in your body or headers so replays are harmless.</Li>
        <Li>
          Remember that a 301/302 after a POST, and any 303, is followed as a <Code>GET</Code> without the body (standard browser behaviour).
        </Li>
        <Li>
          For <Code>POST /v1/sessions</Code>, use the <Code>Idempotency-Key</Code> header to make session creation safe to retry on your side.
        </Li>
      </Ul>

      <H2>Retrying on your side</H2>
      <P>
        Fetcha already retries target-side problems. Client-side retries are still appropriate for <Code>RATE_LIMITED</Code> (honour <Code>Retry-After</Code>), <Code>CONCURRENCY_LIMIT</Code> (when a
        slot frees up), <Code>PROVIDER_UNAVAILABLE</Code> and <Code>INTERNAL_ERROR</Code> (exponential backoff), and for a <Code>success: false</Code> block you may want to retry later with a different
        country or a fresh session.
      </P>
      <CodeBlock
        lang="typescript"
        code={`async function fetchWithBackoff(opts: FetchOptions, maxTries = 4) {
  for (let i = 0; ; i++) {
    try {
      return await fetcha.fetch(opts);
    } catch (e) {
      const transient = e instanceof FetchaError && ["RATE_LIMITED", "CONCURRENCY_LIMIT", "PROVIDER_UNAVAILABLE", "INTERNAL_ERROR"].includes(e.code);
      if (!transient || i + 1 >= maxTries) throw e;
      await new Promise((r) => setTimeout(r, Math.min(8000, 500 * 2 ** i) + Math.random() * 250));
    }
  }
}`}
      />
    </DocPage>
  );
}