src/server.ts

Functions

Imports

It imports src/adapter.ts, src/contract.ts, src/server/content.ts, src/server/http.ts, src/server/media.ts, src/server/mentions.ts. Imported by src/index.ts, src/local.ts.

Source

1// The site side: one handler for everything under /api/carrel/v1.
2//
3// Order is the guard: prefix, then rate limit, then key, then route. A request outside the prefix
4// is never served, whatever key it carries; a request without the key learns nothing about routes.
5
6import { safeEqual } from "@dustinedwards/site-runtime/compare";
7
8import type { SiteAdapter } from "./adapter.js";
9import { PREFIX } from "./contract.js";
10import { contentRoutes } from "./server/content.js";
11import { describeFailure, fail, type Route } from "./server/http.js";
12import { mediaRoutes } from "./server/media.js";
13import { mentionsRoutes } from "./server/mentions.js";
14
15/** The shape of Cloudflare's `ratelimit` binding, so a site passes its binding straight in. */
16export interface RateLimiter {
17  limit(options: { key: string }): Promise<{ success: boolean }>;
18}
19
20export interface SiteApiConfig {
21  adapter: SiteAdapter;
22  /** The site's Carrel key, from its secrets. Shorter than 32 characters refuses every request. */
23  key: string | undefined;
24  limiter: RateLimiter;
25  /** Where refusals and adapter failures are logged. Defaults to console. */
26  log?: (entry: Record<string, unknown>) => void;
27}
28
29export interface SiteApi {
30  /** True when the request's path is inside the prefix. Mount the handler only where this holds. */
31  matches(request: Request): boolean;
32  handle(request: Request): Promise<Response>;
33}
34
35export const MIN_KEY_LENGTH = 32;
36
37export function insidePrefix(pathname: string): boolean {
38  return pathname === PREFIX || pathname.startsWith(`${PREFIX}/`);
39}
40
41function bearer(request: Request): string | null {
42  const header = request.headers.get("authorization");
43  const match = header?.match(/^Bearer[ ]+(\S+)\s*$/i);
44  return match ? match[1]! : null;
45}
46
47export function createSiteApi(config: SiteApiConfig): SiteApi {
48  const { adapter, limiter } = config;
49  const log = config.log ?? ((entry) => console.warn(JSON.stringify(entry)));
50  const { media, mentions } = adapter;
51
52  const routes: Route[] = [
53    ...contentRoutes(adapter),
54    ...(media ? mediaRoutes(media, log) : []),
55    ...(mentions ? mentionsRoutes(mentions) : []),
56  ];
57
58  // Groups a site has not implemented. Media and mentions leave this list when the adapter has them.
59  const LATER = new RegExp(
60    `^/(${[...(media ? [] : ["media"]), ...(mentions ? [] : ["mentions"]), "inbox", "insight", "publications"].join("|")})(/|$)`,
61  );
62
63  async function handle(request: Request): Promise<Response> {
64    const url = new URL(request.url);
65    // The URL parser has already resolved dot segments, so /api/carrel/v1/../admin arrives as /admin.
66    if (!insidePrefix(url.pathname)) return fail("not-found", "Not found.");
67
68    try {
69      const ip = request.headers.get("cf-connecting-ip") ?? "unknown";
70      if (!(await limiter.limit({ key: ip })).success) {
71        log({ siteApi: "refused", reason: "rate-limited" });
72        return fail("rate-limited", "Too many requests.");
73      }
74    } catch (error) {
75      log({ siteApi: "refused", reason: "limiter-failed", error: String(error) });
76      return fail("unavailable", "The site API is unavailable.");
77    }
78
79    const expected = config.key?.trim() ?? "";
80    if (expected.length < MIN_KEY_LENGTH) {
81      log({ siteApi: "refused", reason: "not-configured" });
82      return fail("not-configured", "The site API is not configured.");
83    }
84    const presented = bearer(request);
85    if (!presented || !(await safeEqual(presented, expected))) {
86      log({ siteApi: "refused", reason: presented ? "wrong-key" : "no-key" });
87      return fail("unauthorized", "Unauthorized.");
88    }
89
90    const path = url.pathname.slice(PREFIX.length) || "/";
91    if (LATER.test(path)) return fail("not-implemented", "This group arrives in a later stage.");
92
93    const candidates = routes
94      .map((route) => ({ route, match: path.match(route.pattern) }))
95      .filter((c): c is { route: Route; match: RegExpMatchArray } => c.match !== null);
96    if (candidates.length === 0) return fail("not-found", "No such route.");
97    const hit = candidates.find((c) => c.route.method === request.method);
98    if (!hit) return fail("method-not-allowed", "Method not allowed.");
99
100    try {
101      return await hit.route.run(hit.match, url, request);
102    } catch (error) {
103      const failure = describeFailure(error, log);
104      return fail(failure.code, failure.message, {
105        ...(failure.currentVersion !== undefined ? { currentVersion: failure.currentVersion } : {}),
106        ...(failure.usedBy ? { usedBy: failure.usedBy } : {}),
107      });
108    }
109  }
110
111  return {
112    matches: (request) => insidePrefix(new URL(request.url).pathname),
113    handle,
114  };
115}