rastack 0.0.58 → 0.0.60

package/src/external/envelope.ts

@@ -0,0 +1,78 @@
+/**
+ * Normalise an upstream response into rastack's REST contract — the DRF-shaped
+ * list envelope and bare detail object the typed hooks and `<DataTable>` expect,
+ * identical to what the Rust API and the WASM/local engine emit.
+ *
+ * External APIs rarely page the way rastack does (GitHub uses `per_page` + Link
+ * headers; a GraphQL list just returns an array), so the envelope is synthesised
+ * from what we have: the page the client asked for and the number of items this
+ * page actually returned. `count`/`last` are best-effort when the upstream total
+ * is unknown — enough for the pager to advance while there is a full page.
+ */
+
+import { ensureId, projectFields } from "./util";
+
+export interface ListEnvelope {
+  results: Record<string, unknown>[];
+  pagination: {
+    current: number;
+    last: number;
+    next: number | null;
+    previous: number | null;
+    page_size: number;
+    /** Best-effort total; equals what we can prove when the upstream omits it. */
+    count: number;
+  };
+}
+
+export interface NormalizeOptions {
+  page: number;
+  pageSize: number;
+  primaryKey: string;
+  fields?: string[];
+  /** A known upstream total, if the transport could determine one. */
+  totalCount?: number;
+}
+
+/** Shape a page of upstream items into the list envelope. */
+export function toListEnvelope(
+  items: unknown,
+  opts: NormalizeOptions,
+): ListEnvelope {
+  const rows = (Array.isArray(items) ? items : [])
+    .filter((r): r is Record<string, unknown> => !!r && typeof r === "object")
+    .map((r) => projectFields(ensureId(r, opts.primaryKey), opts.fields));
+
+  const { page, pageSize } = opts;
+  // A full page implies there may be more; a short page is the last one.
+  const hasMore = rows.length >= pageSize;
+  const count =
+    opts.totalCount ?? (page - 1) * pageSize + rows.length;
+  const last = opts.totalCount
+    ? Math.max(1, Math.ceil(opts.totalCount / pageSize))
+    : hasMore
+      ? page + 1
+      : page;
+
+  return {
+    results: rows,
+    pagination: {
+      current: page,
+      last,
+      next: page < last ? page + 1 : null,
+      previous: page > 1 ? page - 1 : null,
+      page_size: pageSize,
+      count,
+    },
+  };
+}
+
+/** Shape a single upstream object into a rastack detail row. */
+export function toDetail(
+  item: unknown,
+  primaryKey: string,
+  fields?: string[],
+): Record<string, unknown> | null {
+  if (!item || typeof item !== "object") return null;
+  return projectFields(ensureId(item as Record<string, unknown>, primaryKey), fields);
+}

package/src/external/graphql.ts

@@ -0,0 +1,98 @@
+/**
+ * Build the upstream request for a GraphQL-backed resource (Expo's API is
+ * GraphQL, for instance), and pull the item array / detail object out of the
+ * `data` payload. A GraphQL call is always a POST of `{ query, variables }`; the
+ * rastack list params map onto the query's variables (`page_size` → `first`,
+ * etc.), so the same `/api/{app}/v1/{model}/` contract fronts a GraphQL API with
+ * no client awareness that it isn't REST.
+ */
+
+import type { GraphQLBinding } from "./types";
+import { firstParam, getPath } from "./util";
+
+export interface GraphQLRequest {
+  url: string;
+  method: "POST";
+  headers: Record<string, string>;
+  body: string;
+}
+
+function buildVariables(
+  binding: GraphQLBinding,
+  query: Record<string, string[]>,
+  id?: string,
+): Record<string, unknown> {
+  const vars: Record<string, unknown> = { ...(binding.variables ?? {}) };
+  const map = binding.variableMap ?? {};
+  const put = (rastackKey: keyof NonNullable<GraphQLBinding["variableMap"]>, raw?: string) => {
+    const name = map[rastackKey];
+    if (!name || raw == null || raw === "") return;
+    // page_size / page are numbers in GraphQL land; coerce when they parse.
+    const num = Number(raw);
+    vars[name] = Number.isFinite(num) && /^\d+$/.test(raw) ? num : raw;
+  };
+  put("page", firstParam(query, "page"));
+  put("page_size", firstParam(query, "page_size"));
+  put("search", firstParam(query, "search"));
+  put("order_by", firstParam(query, "order_by"));
+  if (id != null && map.id) vars[map.id] = id;
+  return vars;
+}
+
+/** Build the GraphQL list request. */
+export function graphqlListRequest(
+  binding: GraphQLBinding,
+  query: Record<string, string[]>,
+  headers: Record<string, string>,
+): GraphQLRequest {
+  return {
+    url: binding.baseUrl,
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({
+      query: binding.listQuery,
+      variables: buildVariables(binding, query),
+    }),
+  };
+}
+
+/** Build the GraphQL detail request. Throws if the binding has no detail query. */
+export function graphqlDetailRequest(
+  binding: GraphQLBinding,
+  id: string,
+  headers: Record<string, string>,
+): GraphQLRequest {
+  if (!binding.detailQuery) {
+    throw new Error(`GraphQL binding ${binding.app}.${binding.model} has no detailQuery.`);
+  }
+  return {
+    url: binding.baseUrl,
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({
+      query: binding.detailQuery,
+      variables: buildVariables(binding, {}, id),
+    }),
+  };
+}
+
+/** A GraphQL response is `{ data, errors }`; surface errors, else return `data`. */
+export function graphqlData(body: unknown): unknown {
+  const payload = body as { data?: unknown; errors?: { message?: string }[] } | null;
+  if (payload?.errors && payload.errors.length) {
+    throw new Error(
+      `GraphQL error: ${payload.errors.map((e) => e.message ?? "unknown").join("; ")}`,
+    );
+  }
+  return payload?.data;
+}
+
+/** Extract the item array from a GraphQL list response. */
+export function graphqlListItems(binding: GraphQLBinding, body: unknown): unknown {
+  return getPath(graphqlData(body), binding.itemsPath);
+}
+
+/** Extract the detail object from a GraphQL detail response. */
+export function graphqlDetailItem(binding: GraphQLBinding, body: unknown): unknown {
+  return getPath(graphqlData(body), binding.detailPath ?? binding.itemsPath);
+}

package/src/external/handler.ts

@@ -0,0 +1,207 @@
+/**
+ * The proxy core — one pure(ish) function from a rastack request to a rastack
+ * response, given the bindings and injected effects (`fetch`, cache, clock,
+ * auth). This is the "work" the user's Lambda does; the mini service inside
+ * `rastack dev` and the deployed Lambda are both thin adapters that parse an
+ * HTTP request into {@link RastackRequest}, call {@link handleExternalRequest},
+ * and serialise the result.
+ *
+ * Responsibilities, in order:
+ *   1. Resolve the binding for `app.model` (404 if none — not an external model).
+ *   2. Serve a fresh cache entry without any upstream call (the cache is the
+ *      whole point of the proxy).
+ *   3. Otherwise call the upstream (REST or GraphQL), using a conditional
+ *      `If-None-Match` when we hold an ETag so a `304` costs no rate-limit.
+ *   4. Normalise into the DRF envelope / detail row, cache it, and return it.
+ *
+ * Auth (the GitHub/Expo token from Secrets Manager in prod, an env var in dev)
+ * is injected by `deps.authHeaders`, so **no credential is ever hard-coded here**.
+ */
+
+import { cacheKey, isFresh, type ProxyCache } from "./cache";
+import { toDetail, toListEnvelope } from "./envelope";
+import {
+  graphqlDetailItem,
+  graphqlDetailRequest,
+  graphqlListItems,
+  graphqlListRequest,
+} from "./graphql";
+import {
+  restDetailRequest,
+  restListItems,
+  restListRequest,
+  type UpstreamRequest,
+} from "./rest";
+import {
+  findBinding,
+  type FetchLike,
+  type ResourceBinding,
+  type ResourceResolver,
+} from "./types";
+import { firstParam } from "./util";
+
+export interface RastackRequest {
+  app: string;
+  model: string;
+  /** Present for a detail request (`/…/{model}/{id}/`). */
+  id?: string;
+  query: Record<string, string[]>;
+}
+
+export interface RastackResponse {
+  status: number;
+  body: unknown;
+  /** Whether this response was served from cache without an upstream call. */
+  cached: boolean;
+}
+
+export interface HandlerDeps {
+  fetch: FetchLike;
+  cache: ProxyCache;
+  now: () => number;
+  /**
+   * Resolve upstream auth/headers for an app — e.g. `{ Authorization: "Bearer …" }`.
+   * Reads Secrets Manager in the Lambda; reads env vars in `rastack dev`.
+   */
+  authHeaders?: (app: string) => Record<string, string> | Promise<Record<string, string>>;
+  /**
+   * Named resolvers for {@link ResolverBinding}s — the app plugs in transports
+   * the core doesn't ship (e.g. an AWS SDK resolver), keeping the core
+   * dependency-free.
+   */
+  resolvers?: Record<string, ResourceResolver>;
+}
+
+const DEFAULT_TTL_MS = 60_000;
+
+function pageParams(query: Record<string, string[]>): { page: number; pageSize: number } {
+  const page = Math.max(1, parseInt(firstParam(query, "page") ?? "1", 10) || 1);
+  const pageSize = Math.max(
+    1,
+    parseInt(firstParam(query, "page_size") ?? "20", 10) || 20,
+  );
+  return { page, pageSize };
+}
+
+async function upstreamHeaders(
+  binding: ResourceBinding,
+  deps: HandlerDeps,
+): Promise<Record<string, string>> {
+  const auth = deps.authHeaders ? await deps.authHeaders(binding.app) : {};
+  return { ...(binding.headers ?? {}), ...auth };
+}
+
+/** Fetch + parse an upstream request, applying a conditional ETag when supplied. */
+async function callUpstream(
+  req: UpstreamRequest | { url: string; method: "POST"; headers: Record<string, string>; body: string },
+  deps: HandlerDeps,
+  etag?: string,
+): Promise<{ status: number; body: unknown; etag?: string }> {
+  const headers = { ...req.headers };
+  if (etag) headers["If-None-Match"] = etag;
+  const res = await deps.fetch(req.url, {
+    method: req.method,
+    headers,
+    body: "body" in req ? req.body : undefined,
+  });
+  if (res.status === 304) return { status: 304, body: undefined, etag };
+  const nextEtag = res.headers.get("etag") ?? undefined;
+  const body = res.status === 204 ? null : await res.json();
+  return { status: res.status, body, etag: nextEtag };
+}
+
+/** Handle one rastack request against the external bindings. */
+export async function handleExternalRequest(
+  req: RastackRequest,
+  bindings: ResourceBinding[],
+  deps: HandlerDeps,
+): Promise<RastackResponse> {
+  const binding = findBinding(bindings, req.app, req.model);
+  if (!binding) {
+    return { status: 404, body: { detail: `No external binding for ${req.app}.${req.model}.` }, cached: false };
+  }
+
+  const ttl = binding.ttlMs ?? DEFAULT_TTL_MS;
+  const pk = binding.primaryKey ?? "id";
+  const key = cacheKey(req.app, req.model, req.id, req.query);
+  const now = deps.now();
+
+  const hit = deps.cache.get(key);
+  if (hit && isFresh(hit, ttl, now)) {
+    return { status: 200, body: hit.value, cached: true };
+  }
+
+  const headers = await upstreamHeaders(binding, deps);
+  const isDetail = req.id != null;
+
+  try {
+    // Resolver transport: no HTTP — call the injected resolver, normalise, cache.
+    if (binding.transport === "resolver") {
+      const resolver = deps.resolvers?.[binding.resolver];
+      if (!resolver) {
+        return {
+          status: 501,
+          body: { detail: `No resolver "${binding.resolver}" registered for ${req.app}.${req.model}.` },
+          cached: false,
+        };
+      }
+      const data = await resolver({ app: req.app, model: req.model, id: req.id, query: req.query });
+      let value: unknown;
+      if (isDetail) {
+        value = toDetail(data, pk, binding.fields);
+        if (value == null) return { status: 404, body: { detail: "Not found" }, cached: false };
+      } else {
+        const { page, pageSize } = pageParams(req.query);
+        value = toListEnvelope(data, { page, pageSize, primaryKey: pk, fields: binding.fields });
+      }
+      deps.cache.set(key, { value, storedAt: now });
+      return { status: 200, body: value, cached: false };
+    }
+
+    // Build the upstream request for this transport + list/detail shape.
+    const upstream =
+      binding.transport === "rest"
+        ? isDetail
+          ? restDetailRequest(binding, req.id!, headers)
+          : restListRequest(binding, req.query, headers)
+        : isDetail
+          ? graphqlDetailRequest(binding, req.id!, headers)
+          : graphqlListRequest(binding, req.query, headers);
+
+    const result = await callUpstream(upstream, deps, hit?.etag);
+
+    // A revalidated ETag: refresh the stored timestamp and serve the cache.
+    if (result.status === 304 && hit) {
+      deps.cache.set(key, { ...hit, storedAt: now });
+      return { status: 200, body: hit.value, cached: true };
+    }
+    if (result.status >= 400) {
+      return { status: result.status, body: result.body ?? { detail: "Upstream error." }, cached: false };
+    }
+
+    // Extract the item(s) for this transport and normalise into the contract.
+    let value: unknown;
+    if (isDetail) {
+      const item =
+        binding.transport === "rest"
+          ? result.body
+          : graphqlDetailItem(binding, result.body);
+      value = toDetail(item, pk, binding.fields);
+      if (value == null) return { status: 404, body: { detail: "Not found" }, cached: false };
+    } else {
+      const items =
+        binding.transport === "rest"
+          ? restListItems(binding, result.body)
+          : graphqlListItems(binding, result.body);
+      const { page, pageSize } = pageParams(req.query);
+      value = toListEnvelope(items, { page, pageSize, primaryKey: pk, fields: binding.fields });
+    }
+
+    deps.cache.set(key, { value, storedAt: now, etag: result.etag });
+    return { status: 200, body: value, cached: false };
+  } catch (err) {
+    // A stale cache entry is better than a hard failure while iterating.
+    if (hit) return { status: 200, body: hit.value, cached: true };
+    return { status: 502, body: { detail: (err as Error).message }, cached: false };
+  }
+}

package/src/external/index.ts

@@ -0,0 +1,25 @@
+/**
+ * `rastack` external-API proxy core.
+ *
+ * Serves external REST/GraphQL APIs (GitHub, Expo, AWS) over the rastack
+ * `/api/{app}/v1/{model}/` contract so the *normal typed hooks* consume them
+ * unchanged: caches responses, injects auth, and normalises upstream payloads
+ * into the DRF envelope. Transport-agnostic and effect-injected, so the identical
+ * core runs in the deployed Lambda and in the mini service inside `rastack dev`.
+ */
+
+export * from "./types";
+export * from "./cache";
+export * from "./envelope";
+export * from "./rest";
+export * from "./graphql";
+export * from "./route";
+export * from "./service";
+export * from "./lambda";
+export {
+  handleExternalRequest,
+  type RastackRequest,
+  type RastackResponse,
+  type HandlerDeps,
+} from "./handler";
+export { getPath } from "./util";

package/src/external/lambda.ts

@@ -0,0 +1,108 @@
+/**
+ * The AWS Lambda adapter — the deployed twin of the `rastack dev` mini service.
+ *
+ * Both are thin shells over the same pure {@link handleExternalRequest} core:
+ * parse the incoming request into a {@link RastackRequest}, run the handler,
+ * serialise the result. The differences are injected, not branched:
+ *   • **auth** — dev reads `GITHUB_TOKEN` from the environment; the Lambda's
+ *     `deps.authHeaders` reads AWS Secrets Manager (the app supplies that
+ *     closure, so no AWS SDK import leaks into the framework).
+ *   • **cache** — dev uses an in-process `Map`; the Lambda can pass a
+ *     DynamoDB/ElastiCache-backed {@link ProxyCache} for cross-invocation hits.
+ *
+ * Authn/z is handled *in front* by an API Gateway Cognito authorizer, so by the
+ * time an event reaches here the caller's JWT is already verified; this adapter
+ * only serves data. It accepts both API Gateway payload formats (HTTP API v2 and
+ * REST/proxy v1), so it drops into either integration.
+ */
+
+import { handleExternalRequest, type HandlerDeps } from "./handler";
+import { parseApiPath } from "./route";
+import type { ResourceBinding } from "./types";
+
+/** The subset of an API Gateway event this adapter reads (v1 and v2 tolerant). */
+export interface ApiGatewayEvent {
+  /** HTTP API (payload v2). */
+  rawPath?: string;
+  rawQueryString?: string;
+  requestContext?: { http?: { method?: string } };
+  /** REST API / proxy (payload v1). */
+  path?: string;
+  httpMethod?: string;
+  queryStringParameters?: Record<string, string | undefined> | null;
+  multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+}
+
+export interface ApiGatewayResult {
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+const JSON_HEADERS = {
+  "Content-Type": "application/json; charset=utf-8",
+  "Cache-Control": "no-store",
+} as const;
+
+/** Reconstruct the request URL (path + query) from either payload format. */
+export function eventToUrl(event: ApiGatewayEvent): string {
+  if (event.rawPath != null) {
+    const qs = event.rawQueryString ? `?${event.rawQueryString}` : "";
+    return `${event.rawPath}${qs}`;
+  }
+  const path = event.path ?? "/";
+  const search = new URLSearchParams();
+  const multi = event.multiValueQueryStringParameters;
+  if (multi) {
+    for (const [key, values] of Object.entries(multi)) {
+      for (const v of values ?? []) if (v != null) search.append(key, v);
+    }
+  } else if (event.queryStringParameters) {
+    for (const [key, v] of Object.entries(event.queryStringParameters)) {
+      if (v != null) search.append(key, v);
+    }
+  }
+  const qs = search.toString();
+  return `${path}${qs ? `?${qs}` : ""}`;
+}
+
+/** The HTTP method from either payload format (defaults to GET). */
+export function eventMethod(event: ApiGatewayEvent): string {
+  return (event.requestContext?.http?.method ?? event.httpMethod ?? "GET").toUpperCase();
+}
+
+/**
+ * Handle one API Gateway event: parse → run the proxy core → serialise. Returns
+ * a proxy-integration result (`statusCode`/`headers`/`body`) for either format.
+ */
+export async function handleLambdaEvent(
+  event: ApiGatewayEvent,
+  bindings: ResourceBinding[],
+  deps: HandlerDeps,
+): Promise<ApiGatewayResult> {
+  // Reads are open (viewing is public; the authorizer gated the request); the
+  // proxy only serves GET. Anything else is a fast, cheap rejection.
+  if (eventMethod(event) !== "GET") {
+    return {
+      statusCode: 405,
+      headers: JSON_HEADERS,
+      body: JSON.stringify({ detail: "Method not allowed" }),
+    };
+  }
+
+  const req = parseApiPath(eventToUrl(event));
+  if (!req) {
+    return {
+      statusCode: 404,
+      headers: JSON_HEADERS,
+      body: JSON.stringify({ detail: "Not an /api/{app}/v1/{model}/ route." }),
+    };
+  }
+
+  const result = await handleExternalRequest(req, bindings, deps);
+  return {
+    statusCode: result.status,
+    headers: { ...JSON_HEADERS, "X-Rastack-Cache": result.cached ? "hit" : "miss" },
+    body: JSON.stringify(result.body),
+  };
+}

package/src/external/rest.ts

@@ -0,0 +1,60 @@
+/**
+ * Build the upstream HTTP request for a REST-backed resource, and pull the item
+ * array out of the response body. Pure string/URL work — no network — so it is
+ * unit-tested directly.
+ */
+
+import type { RestBinding } from "./types";
+import { firstParam, getPath } from "./util";
+
+export interface UpstreamRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+}
+
+/** The rastack→upstream default query-param names, before a binding overrides them. */
+const DEFAULT_QUERY_MAP = {
+  page: "page",
+  page_size: "per_page",
+  search: "q",
+  order_by: "sort",
+} as const;
+
+/** Build the upstream list request from a rastack list query. */
+export function restListRequest(
+  binding: RestBinding,
+  query: Record<string, string[]>,
+  headers: Record<string, string>,
+): UpstreamRequest {
+  const map = { ...DEFAULT_QUERY_MAP, ...(binding.queryMap ?? {}) };
+  const search = new URLSearchParams();
+  for (const key of ["page", "page_size", "search", "order_by"] as const) {
+    const value = firstParam(query, key);
+    if (value != null && value !== "") search.set(map[key], value);
+  }
+  const qs = search.toString();
+  return {
+    url: `${binding.baseUrl}${binding.listPath}${qs ? `?${qs}` : ""}`,
+    method: "GET",
+    headers,
+  };
+}
+
+/** Build the upstream detail request. Throws if the binding has no detail path. */
+export function restDetailRequest(
+  binding: RestBinding,
+  id: string,
+  headers: Record<string, string>,
+): UpstreamRequest {
+  if (!binding.detailPath) {
+    throw new Error(`REST binding ${binding.app}.${binding.model} has no detailPath.`);
+  }
+  const path = binding.detailPath.replace(/\{id\}/g, encodeURIComponent(id));
+  return { url: `${binding.baseUrl}${path}`, method: "GET", headers };
+}
+
+/** Extract the item array from a REST list body (honours `itemsPath`). */
+export function restListItems(binding: RestBinding, body: unknown): unknown {
+  return getPath(body, binding.itemsPath);
+}

package/src/external/route.ts

@@ -0,0 +1,33 @@
+/**
+ * Parse the rastack REST path both the mini `rastack dev` service and the
+ * deployed Lambda receive into a {@link RastackRequest}. The contract is fixed:
+ *
+ *   /api/{app}/v1/{model}/            → list
+ *   /api/{app}/v1/{model}/{id}/       → detail
+ *
+ * Kept pure and separate from the servers so it is tested without a socket.
+ */
+
+import type { RastackRequest } from "./handler";
+
+/** Parse a request URL (path + optional query) into a rastack request, or null. */
+export function parseApiPath(url: string): RastackRequest | null {
+  const [rawPath, rawQuery = ""] = url.split("?");
+  const segments = rawPath.split("/").filter(Boolean); // api, {app}, v1, {model}, [id]
+  if (segments.length < 4 || segments[0] !== "api" || segments[2] !== "v1") {
+    return null;
+  }
+  const app = decodeURIComponent(segments[1]);
+  const model = decodeURIComponent(segments[3]);
+  const id = segments[4] ? decodeURIComponent(segments[4]) : undefined;
+
+  const query: Record<string, string[]> = {};
+  for (const pair of rawQuery.split("&")) {
+    if (!pair) continue;
+    const eq = pair.indexOf("=");
+    const key = decodeURIComponent(eq === -1 ? pair : pair.slice(0, eq));
+    const value = decodeURIComponent(eq === -1 ? "" : pair.slice(eq + 1)).replace(/\+/g, " ");
+    (query[key] ??= []).push(value);
+  }
+  return { app, model, id, query };
+}