rastack 0.0.58 → 0.0.59

package/src/external/types.ts

@@ -0,0 +1,121 @@
+/**
+ * External-API bindings — how a rastack `app.model` is served from an upstream
+ * REST or GraphQL API.
+ *
+ * The stack's own resources are served by the Rust API / WASM engine over the
+ * `/api/{app}/v1/{model}/` contract. An **external** resource (a GitHub repo, an
+ * Expo project, an AWS stack) is served by the proxy instead: it speaks the same
+ * contract to the client, and translates each request into an upstream call,
+ * normalises the response into rastack's DRF-shaped envelope, and caches it.
+ *
+ * One {@link ResourceBinding} describes that translation for a single model. The
+ * proxy core ({@link ./handler}) is a pure function of a request + the bindings +
+ * an injected `fetch`/cache, so the *same* logic runs in the deployed Lambda and
+ * in the mini service inside `rastack dev`.
+ */
+
+/** A minimal `fetch` surface — the global `fetch` satisfies it; tests fake it. */
+export interface FetchResponse {
+  status: number;
+  headers: { get(name: string): string | null };
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+export type FetchLike = (
+  url: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  },
+) => Promise<FetchResponse>;
+
+/** Common binding fields, independent of transport. */
+interface BindingBase {
+  /** The rastack app namespace, e.g. `"github"`. */
+  app: string;
+  /** The rastack model, the `{model}` in `/api/{app}/v1/{model}/`. */
+  model: string;
+  /** The upstream field that is the row's identity. Default `"id"`. */
+  primaryKey?: string;
+  /** Cache TTL in ms for this resource's responses. Default 60_000. */
+  ttlMs?: number;
+  /** Whitelist of upstream fields to project into each row (default: all). */
+  fields?: string[];
+  /** Static headers merged into every upstream request (auth is separate). */
+  headers?: Record<string, string>;
+}
+
+/** Serve a model from an upstream REST endpoint. */
+export interface RestBinding extends BindingBase {
+  transport: "rest";
+  /** Upstream origin, e.g. `"https://api.github.com"`. */
+  baseUrl: string;
+  /** Path to the list, e.g. `"/user/repos"`. */
+  listPath: string;
+  /** Path to a detail; `{id}` is substituted, e.g. `"/repositories/{id}"`. */
+  detailPath?: string;
+  /**
+   * Map rastack list params (`page`, `page_size`, `search`, `order_by`) to the
+   * upstream's own names (`page`, `per_page`, `q`, `sort`). Unmapped params are
+   * dropped, so the upstream never sees rastack-only query keys.
+   */
+  queryMap?: Partial<Record<"page" | "page_size" | "search" | "order_by", string>>;
+  /** Dot path to the array inside the list response (default: the body *is* the array). */
+  itemsPath?: string;
+}
+
+/** Serve a model from an upstream GraphQL endpoint. */
+export interface GraphQLBinding extends BindingBase {
+  transport: "graphql";
+  /** The GraphQL endpoint URL, e.g. `"https://api.expo.dev/graphql"`. */
+  baseUrl: string;
+  /** The list query. Variables are filled from {@link variableMap}. */
+  listQuery: string;
+  /** Dot path into `data` to the array, e.g. `"me.accounts.0.apps"`. */
+  itemsPath: string;
+  /** Optional detail query; `$id` variable is bound to the requested id. */
+  detailQuery?: string;
+  /** Dot path into `data` to the detail object. */
+  detailPath?: string;
+  /** Map rastack params to GraphQL variable names (e.g. `page_size` → `first`). */
+  variableMap?: Partial<Record<"page" | "page_size" | "search" | "order_by" | "id", string>>;
+  /** Static variables merged into every query. */
+  variables?: Record<string, unknown>;
+}
+
+/**
+ * Serve a model from an injected resolver function rather than a plain HTTP
+ * call — for upstreams that need an SDK/signing the proxy core shouldn't import
+ * (AWS SigV4, say). The named resolver is provided via `HandlerDeps.resolvers`,
+ * so the framework stays dependency-free while the app plugs in, e.g., an AWS
+ * CloudFormation resolver. Still consumed through the normal `useData` contract.
+ */
+export interface ResolverBinding extends BindingBase {
+  transport: "resolver";
+  /** Key into `HandlerDeps.resolvers` for the function that produces the data. */
+  resolver: string;
+}
+
+export type ResourceBinding = RestBinding | GraphQLBinding | ResolverBinding;
+
+/**
+ * A resolver produces the upstream data for a {@link ResolverBinding}: an array
+ * for a list request, or a single object for a detail request. Normalisation
+ * into the rastack envelope is done by the core, exactly as for HTTP transports.
+ */
+export type ResourceResolver = (args: {
+  app: string;
+  model: string;
+  id?: string;
+  query: Record<string, string[]>;
+}) => Promise<unknown>;
+
+/** Look a binding up by `app`/`model`. */
+export function findBinding(
+  bindings: ResourceBinding[],
+  app: string,
+  model: string,
+): ResourceBinding | undefined {
+  return bindings.find((b) => b.app === app && b.model === model);
+}

package/src/external/util.ts

@@ -0,0 +1,57 @@
+/** Small pure helpers shared by the proxy core. */
+
+/**
+ * Read a value at a dot path (`"me.accounts.0.apps"`) out of a JSON value.
+ * Numeric segments index arrays. Returns `undefined` for any missing hop, so
+ * callers can default gracefully rather than throw on a shape they didn't get.
+ */
+export function getPath(value: unknown, path: string | undefined): unknown {
+  if (!path) return value;
+  let cur: unknown = value;
+  for (const segment of path.split(".")) {
+    if (cur == null) return undefined;
+    if (Array.isArray(cur)) {
+      const idx = Number(segment);
+      cur = Number.isInteger(idx) ? cur[idx] : undefined;
+    } else if (typeof cur === "object") {
+      cur = (cur as Record<string, unknown>)[segment];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+/** Keep only `fields` on a row (plus always its `id`). No-op when unset. */
+export function projectFields(
+  row: Record<string, unknown>,
+  fields: string[] | undefined,
+): Record<string, unknown> {
+  if (!fields || !fields.length) return row;
+  const out: Record<string, unknown> = {};
+  if ("id" in row) out.id = row.id;
+  for (const f of fields) if (f in row) out[f] = row[f];
+  return out;
+}
+
+/**
+ * Ensure a row carries an `id` (the rastack detail-URL key). If the upstream's
+ * identity lives under a different `primaryKey`, mirror it onto `id`.
+ */
+export function ensureId(
+  row: Record<string, unknown>,
+  primaryKey: string,
+): Record<string, unknown> {
+  if (primaryKey !== "id" && row.id === undefined && row[primaryKey] !== undefined) {
+    return { ...row, id: row[primaryKey] };
+  }
+  return row;
+}
+
+/** First value for a key in a parsed query (`{ page: ["2"] }` → `"2"`). */
+export function firstParam(
+  query: Record<string, string[]>,
+  key: string,
+): string | undefined {
+  return query[key]?.[0];
+}

package/src/rastack-dev.ts

@@ -321,6 +321,17 @@ async function runMetroMode(args: DevArgs, cwd: string): Promise<void> {
   server.on("upgrade", (req, socket, head) =>
     proxyUpgrade(req, socket as net.Socket, head, metroPort),
   );
+  server.on("error", (err: NodeJS.ErrnoException) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(
+        `\n  ✗ Port ${args.port} is already in use — is \`rastack dev\` already running?\n` +
+          `    Stop it, or pick another port: rastack dev --port <n>\n`,
+      );
+    } else {
+      console.error(`\n  ✗ dev server error: ${err.message}`);
+    }
+    stop(1);
+  });
 
   server.listen(args.port, () => {
     const url = `http://localhost:${args.port}`;

package/src/rastack-wasm-build.ts

@@ -6,7 +6,7 @@
  *
  * Pipeline:
  *   1. cargo build -p rastack-wasm --release --target wasm32-unknown-unknown
- *   2. wasm-bindgen --target web  → tools/wasm/rastack_wasm.js + rastack_wasm_bg.wasm
+ *   2. wasm-bindgen --target web  → wasm/rastack_wasm.js + rastack_wasm_bg.wasm
  *   3. wasm-opt -Oz (if available) to shrink the binary
  *
  * This is invoked by the release CI (to bundle a prebuilt engine into the npm
@@ -20,9 +20,9 @@ import { spawnSync } from "child_process";
 import fs from "fs";
 import path from "path";
 
-const repoRoot = path.resolve(__dirname, "..", "..");
-const rustDir = path.join(repoRoot, "rust");
-const outDir = path.join(repoRoot, "tools", "wasm");
+const repoRoot = path.resolve(__dirname, "..");
+const rustDir = path.join(repoRoot, "engine");
+const outDir = path.join(repoRoot, "wasm");
 const wasmPath = path.join(
   rustDir,
   "target",
@@ -78,7 +78,7 @@ export function buildWasm(): void {
     rustDir,
   );
 
-  console.log("→ wasm-bindgen → tools/wasm/");
+  console.log("→ wasm-bindgen → wasm/");
   run("wasm-bindgen", [
     "--target",
     "web",
@@ -105,7 +105,7 @@ export function buildWasm(): void {
   }
 
   const size = fs.statSync(path.join(outDir, "rastack_wasm_bg.wasm")).size;
-  console.log(`✓ wasm engine built: tools/wasm/ (${(size / 1024).toFixed(0)} KB)`);
+  console.log(`✓ wasm engine built: wasm/ (${(size / 1024).toFixed(0)} KB)`);
 }
 
 if (require.main === module) {

package/jest.config.cjs

@@ -1,12 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  testMatch: ['**/test/**/*.spec.ts'],
-  moduleFileExtensions: ['ts', 'js'],
-  // Let executed test fixtures import the package by its published subpath
-  // names, the same way a consumer would (the resource compiler resolves these
-  // via its own ts.Program; these mappings are for code jest actually runs).
-  moduleNameMapper: {
-    '^rastack/tokens$': '<rootDir>/tokens.ts',
-  },
-};

package/test/auth.spec.ts

@@ -1,207 +0,0 @@
-/**
- * Tests for the `rastack/auth` core — the client-side mirror of the access
- * rules `rastack-api-core` enforces (see `rust/rastack-api-core/tests/access.rs`
- * for the server side of the same matrix). The semantics here must track the
- * Rust `check_permission` / `enforced_owner` exactly: `can()` answers "would
- * the server accept this request?", so the components can limit the paths they
- * expose instead of surfacing 401s.
- */
-
-import {
-  anonymousAuth,
-  authFromClaims,
-  bypassesRls,
-  can,
-  canActOnRow,
-  isAdmin,
-  ownsRow,
-  policyFromManifest,
-  policyFromOpenApi,
-  trustedAuth,
-  userAuth,
-  type ResourcePolicy,
-} from "../auth/core";
-
-const rls: ResourcePolicy = {
-  permission: "authenticated",
-  access: { ownerField: "owner", scope: "owner", adminGroups: ["staff"] },
-};
-
-describe("rastack/auth — the permission gate (can)", () => {
-  it("defaults to authenticated — secure by default, like the server", () => {
-    expect(can(anonymousAuth(), {}, "list")).toBe(false);
-    expect(can(anonymousAuth(), undefined, "create")).toBe(false);
-    expect(can(userAuth("u1"), {}, "list")).toBe(true);
-    expect(can(userAuth("u1"), undefined, "delete")).toBe(true);
-  });
-
-  it("public admits everyone, for every action", () => {
-    const policy: ResourcePolicy = { permission: "public" };
-    for (const action of [
-      "list",
-      "retrieve",
-      "create",
-      "update",
-      "delete",
-    ] as const) {
-      expect(can(anonymousAuth(), policy, action)).toBe(true);
-    }
-  });
-
-  it("authenticatedOrReadOnly admits anonymous reads but not writes", () => {
-    const policy: ResourcePolicy = { permission: "authenticatedOrReadOnly" };
-    expect(can(anonymousAuth(), policy, "list")).toBe(true);
-    expect(can(anonymousAuth(), policy, "retrieve")).toBe(true);
-    expect(can(anonymousAuth(), policy, "create")).toBe(false);
-    expect(can(anonymousAuth(), policy, "update")).toBe(false);
-    expect(can(anonymousAuth(), policy, "delete")).toBe(false);
-    expect(can(userAuth("u1"), policy, "delete")).toBe(true);
-  });
-
-  it("row-secured resources need a subject (the server answers 401 without one)", () => {
-    // Authenticated but subject-less — e.g. a machine token without `sub`.
-    const noSub = { authenticated: true, groups: [] };
-    expect(can(noSub, rls, "list")).toBe(false);
-    expect(can(userAuth("u1"), rls, "list")).toBe(true);
-    // A configured admin group bypasses row-level security.
-    expect(can({ ...noSub, groups: ["staff"] }, rls, "list")).toBe(true);
-  });
-
-  it("trusted contexts (dev without auth) pass everything", () => {
-    expect(can(trustedAuth(), rls, "delete")).toBe(true);
-  });
-
-  it("a missing identity gates nothing — the server stays the enforcer", () => {
-    expect(can(undefined, rls, "delete")).toBe(true);
-    expect(can(null, { permission: "authenticated" }, "create")).toBe(true);
-  });
-});
-
-describe("rastack/auth — row-level security helpers", () => {
-  const mine = { id: 1, owner: "u1" };
-  const theirs = { id: 2, owner: "u2" };
-
-  it("owners own their rows; others don't", () => {
-    expect(ownsRow(userAuth("u1"), rls, mine)).toBe(true);
-    expect(ownsRow(userAuth("u1"), rls, theirs)).toBe(false);
-  });
-
-  it("admin groups and trusted contexts bypass the owner filter", () => {
-    expect(bypassesRls(userAuth("u1", ["staff"]), rls)).toBe(true);
-    expect(ownsRow(userAuth("u1", ["staff"]), rls, theirs)).toBe(true);
-    expect(ownsRow(trustedAuth(), rls, theirs)).toBe(true);
-    expect(bypassesRls(userAuth("u1", ["other"]), rls)).toBe(false);
-  });
-
-  it("unsecured resources are owned by everyone", () => {
-    expect(ownsRow(userAuth("u1"), {}, theirs)).toBe(true);
-  });
-
-  it("canActOnRow combines the gate and ownership", () => {
-    expect(canActOnRow(userAuth("u1"), rls, "update", mine)).toBe(true);
-    expect(canActOnRow(userAuth("u1"), rls, "update", theirs)).toBe(false);
-    expect(canActOnRow(anonymousAuth(), rls, "update", mine)).toBe(false);
-  });
-});
-
-describe("rastack/auth — group-owned datasets", () => {
-  // A group dataset: rows belong to a team, physically partitioned per group.
-  const grouped: ResourcePolicy = {
-    permission: "authenticated",
-    access: { groupField: "team", scope: "group", adminGroups: ["staff"] },
-  };
-  const blueRow = { id: 1, team: "blue" };
-
-  it("members read; identities in no group can read (empty) but never write", () => {
-    const dana = userAuth("dana", ["blue"]);
-    const loner = userAuth("lonnie", []);
-    expect(can(dana, grouped, "list")).toBe(true);
-    expect(can(dana, grouped, "create")).toBe(true);
-    // Reads outside any group just come back empty — but a write can never
-    // succeed, so the UI shouldn't offer it.
-    expect(can(loner, grouped, "list")).toBe(true);
-    expect(can(loner, grouped, "create")).toBe(false);
-    expect(can(loner, grouped, "delete")).toBe(false);
-  });
-
-  it("row membership mirrors the server's group guard", () => {
-    expect(ownsRow(userAuth("dana", ["blue"]), grouped, blueRow)).toBe(true);
-    expect(ownsRow(userAuth("erin", ["green"]), grouped, blueRow)).toBe(false);
-    expect(
-      canActOnRow(userAuth("erin", ["green"]), grouped, "update", blueRow),
-    ).toBe(false);
-    // adminGroups members act across groups.
-    expect(ownsRow(userAuth("sam", ["staff"]), grouped, blueRow)).toBe(true);
-  });
-
-  it("owner + group guards both apply when a policy carries both", () => {
-    const both: ResourcePolicy = {
-      access: { ownerField: "owner", groupField: "team" },
-    };
-    const row = { id: 1, owner: "dana", team: "blue" };
-    expect(ownsRow(userAuth("dana", ["blue"]), both, row)).toBe(true);
-    expect(ownsRow(userAuth("dana", ["green"]), both, row)).toBe(false);
-    expect(ownsRow(userAuth("erin", ["blue"]), both, row)).toBe(false);
-  });
-
-  it("isAdmin is the scope-driven admin role", () => {
-    expect(isAdmin(userAuth("sam", ["staff"]), grouped)).toBe(true);
-    expect(isAdmin(userAuth("dana", ["blue"]), grouped)).toBe(false);
-    expect(isAdmin(trustedAuth(), grouped)).toBe(true);
-  });
-});
-
-describe("rastack/auth — building an identity", () => {
-  it("authFromClaims reads sub and cognito:groups from a decoded token", () => {
-    const auth = authFromClaims({
-      sub: "u1",
-      "cognito:groups": ["staff", 42],
-      email: "x@y.z",
-    });
-    expect(auth).toEqual({ authenticated: true, sub: "u1", groups: ["staff"] });
-    expect(authFromClaims({}).authenticated).toBe(false);
-  });
-});
-
-describe("rastack/auth — policy lookup", () => {
-  const manifest = {
-    resources: [
-      { app: "airports", model: "airport", fields: [] },
-      {
-        app: "airports",
-        model: "itinerary",
-        fields: [],
-        permission: "authenticated",
-        access: { ownerField: "owner", scope: "owner", adminGroups: ["staff"] },
-      },
-    ],
-  };
-
-  it("policyFromManifest extracts permission + access", () => {
-    expect(policyFromManifest(manifest, "airports.itinerary")).toEqual(rls);
-    expect(
-      policyFromManifest(manifest, { app: "airports", model: "airport" }),
-    ).toEqual({});
-    expect(policyFromManifest(manifest, "airports.missing")).toBeUndefined();
-    // Accepts the JSON string form the provider may hold.
-    expect(
-      policyFromManifest(JSON.stringify(manifest), "airports.itinerary"),
-    ).toEqual(rls);
-  });
-
-  it("policyFromOpenApi reads the x-rastack-permission / x-rastack-access stamps", () => {
-    const doc = {
-      paths: {
-        "/api/airports/v1/itinerary/": {
-          get: {
-            operationId: "listItinerary",
-            "x-rastack-permission": "authenticated",
-            "x-rastack-access": rls.access,
-          },
-        },
-      },
-    };
-    expect(policyFromOpenApi(doc, "airports.itinerary")).toEqual(rls);
-    expect(policyFromOpenApi(doc, "airports.airport")).toBeUndefined();
-  });
-});