Ch. 7: Bring in the browser

In this chapter the browser becomes a worker. It connects to the engine over WebSocket, calls link::create directly (no REST API Gateway), observes the live click feed from Chapter 5 to update a counter, and registers a user::confirm_destructive_op function the server calls when a delete needs a human’s go-ahead.

Add the workers

A browser worker connects through the rbac-proxy RBAC-gated port, separate from the trusted port your local workers use. The auth worker holds the authentication logic that gates those connections. Uncomment the Ch. 7 block in worker-compose.yaml:

worker-compose.yaml

auth:
  worker: path://./auth
  env_file: ["./.env"]

The env_file gives the worker LINKLY_BROWSER_TOKEN from .env; the scaffold ships dev-token for local work. auth::browser admits a browser only when the token it receives matches, so change this value for anything beyond your machine.

If you’re continuing from the previous chapter you might still be in the channel-client folder. Make sure to cd ..!

Put a proxy in front for browsers

The engine’s port at 49134 is the trusted listener; local workers (link worker, analytics worker) connect there. The browser must not. The rbac-proxy worker opens a separate public port and reverse-proxies to the engine, authenticating every connection and gating every call it makes. Uncomment the Ch. 7 rbac-proxy container:

worker-compose.yaml

rbac-proxy:
  worker: package://rbac-proxy
  version: "latest"
  config_name: rbac-proxy
  config_override:
    host: 127.0.0.1
    port: 3110
    engine_url: ws://127.0.0.1:49134
    rbac:
      auth_function_id: auth::browser
      expose_functions:
        - match("link::create")
        - match("link::request_delete")
        - match("link::click_summary")
        - match("click-streamer::on-click")

Restart Compose so it starts the proxy:

iii call compose::restart

expose_functions is an allowlist of the functions a browser session can call and observe. The tab creates links with link::create, asks for deletes with link::request_delete, reads the starting click total with link::click_summary, and observes the live click feed, click-streamer::on-click. The feed is private (Chapter 5): the engine accepts calls of it only from click-streamer, so the tab can observe it and cannot call it. auth_function_id names a function rbac-proxy invokes on every connection to admit or reject it; you write that next.

Gate connections with an auth function

The auth worker owns connection gating, so the link worker stays focused on links. auth::browser runs once per browser connection: it receives the request’s headers, query_params, and ip_address, and returns the session’s permissions (allow/deny additions, arbitrary context). Throw to reject. Create auth/src/index.ts:

auth/src/index.ts

import { registerWorker } from "iii-sdk";
import { Logger } from "@iii-dev/helpers/observability";

const worker = registerWorker(process.env.III_URL ?? "ws://localhost:49134", {
  workerName: "auth",
});
const logger = new Logger();

worker.registerFunction(
  "auth::browser",
  async (input: {
    headers: Record<string, string>;
    query_params: Record<string, string[]>;
    ip_address: string;
  }) => {
    // Fail closed: no LINKLY_BROWSER_TOKEN set means no browser is admitted.
    const expected = process.env.LINKLY_BROWSER_TOKEN;
    const token = input.query_params.token?.[0];
    if (!expected || token !== expected) {
      throw new Error("unauthorized");
    }
    // Each tab sends a unique session id and registers in its own
    // `browser-<session>` namespace, so the functions two tabs register never
    // collide. Granting only that namespace key keeps a tab out of `default`.
    const session = input.query_params.session?.[0];
    if (!session) {
      throw new Error("missing session");
    }
    return {
      allow_function_registration: true,
      namespaces: {
        [`browser-${session}`]: ["ui::on_click", "user::confirm_destructive_op"],
      },
      context: { source: "browser" },
    };
  },
);

logger.info("auth worker ready");

The client sends the same token as VITE_LINKLY_TOKEN, which you set below. A real deployment would look the token up in a session store; the shape stays the same. The token travels in a query parameter because browsers cannot send custom WebSocket headers. Each tab also sends a unique session id. The engine allows one function per id in a namespace, so two tabs both registering ui::on_click in default would collide. namespaces gives each session its own browser-<session> namespace and permits registration only there: the tab’s functions live in isolation, and it still calls link::* in default through the expose_functions allowlist. Observers follow the session’s grants: a session may observe a function its grants cover, with a target its grants cover, and a private function such as the click feed is observable this way. The tab observes click-streamer::on-click, which expose_functions lists, with ui::on_click, a function in its own namespace, as the target.

Add a server-initiated delete

First give the link worker a link::delete that removes a link from both the database and the state cache. Add it to link/src/index.ts:

link/src/index.ts

worker.registerFunction("link::delete", async (payload: { code: string }) => {
  await worker.call({
    function_id: "database::execute",
    payload: { db: DB, sql: "DELETE FROM links WHERE code = ?", params: [payload.code] },
  });
  await worker.call({
    function_id: "state::delete",
    payload: { scope: "links", key: payload.code },
  });
  logger.info("link deleted", { code: payload.code });
  return { deleted: true };
});

Now add a wrapper that asks the connected browser first, then deletes only if the browser confirms. The server-side worker.call of a browser-registered function is the same primitive you’ve used between server workers, in reverse. This lets us reverse the typical pattern: instead of the browser asking the server for confirmation, the server asks the browser. Other implementations would achieve this with SSE but here it works like normal synchronous code.

link/src/index.ts

worker.registerFunction(
  "link::request_delete",
  async (payload: { code: string; session: string }) => {
    const { confirmed } = await worker.call<
      { code: string; action: string },
      { confirmed: boolean }
    >({
      function_id: "user::confirm_destructive_op",
      // Ask the one tab that owns this session, in its private namespace.
      namespace: `browser-${payload.session}`,
      payload: { code: payload.code, action: `delete link "${payload.code}"` },
    });
    if (!confirmed) {
      return { deleted: false };
    }
    await worker.call({ function_id: "link::delete", payload: { code: payload.code } });
    return { deleted: true };
  },
);

Scaffold the frontend

Initialize a Vite project

From the project root (the folder with worker-compose.yaml), create a Vite + React + TypeScript app. create-vite creates the frontend/ folder for you:

npm create vite@latest frontend -- --template react-ts --no-interactive

--no-interactive makes create-vite skip its questions: it scaffolds frontend/ with its default linter and neither installs nor starts anything, since iii-browser-sdk has to be installed first. npm may first ask “Ok to proceed?” to download create-vite; answer yes.

Now install the dependencies:

cd frontend
npm install
npm install iii-browser-sdk@0.26.0

iii-browser-sdk is pinned to 0.26.0, the same version as the iii-sdk the backend workers pin: the tab uses the 0.26 observe and call API. Each one connects to the engine, never to the other. Then tell the app where the proxy is and which token to send. Create frontend/.env.local; Vite reads it at startup. VITE_LINKLY_TOKEN must equal LINKLY_BROWSER_TOKEN in the project’s .env, and VITE_LINKLY_PROXY_URL uses the rbac-proxy port:

frontend/.env.local

VITE_LINKLY_TOKEN=dev-token
VITE_LINKLY_PROXY_URL=ws://localhost:3110

Setup a client-side worker

Connect the SDK to our iii instance in frontend/src/iii.ts. Note how we’re using a different URL format and port, this goes back to the setup we did with rbac-proxy and RBAC.

src/iii.ts

import { registerWorker } from "iii-browser-sdk";

// Both come from frontend/.env.local.
const TOKEN = import.meta.env.VITE_LINKLY_TOKEN;
const PROXY_URL = import.meta.env.VITE_LINKLY_PROXY_URL;
if (!TOKEN || !PROXY_URL) {
  throw new Error("Set VITE_LINKLY_TOKEN and VITE_LINKLY_PROXY_URL in frontend/.env.local");
}

// A per-tab id. The tab registers its functions in `browser-<SESSION>`, so two
// open tabs never collide on `ui::on_click` or `user::confirm_destructive_op`.
export const SESSION = crypto.randomUUID();

export const worker = registerWorker(
  `${PROXY_URL}?token=${encodeURIComponent(TOKEN)}&session=${SESSION}`,
  { namespace: `browser-${SESSION}` },
);

Create the application

We’ll build src/App.tsx in pieces. You can replace the template’s src/App.tsx with the code samples below.

Add imports

First the imports and types: Click is what click-streamer::on-click returns for each click, and Summary is what link::click_summary returns.

src/App.tsx

import { useEffect, useState } from "react";
import { worker, SESSION } from "./iii.js";

type Click = { id: number; code: string; clicked_at: string };
type Summary = { total: number; last_id: number };

Add client-side state

Open the component and declare its state: the form fields, the newly created link, and the live click counter.

src/App.tsx

export default function App() {
  const [url, setUrl] = useState('')
  const [code, setCode] = useState('')
  const [created, setCreated] = useState<{ code: string; url: string } | null>(null)
  const [clicks, setClicks] = useState(0)
  const [latest, setLatest] = useState<Click | null>(null)

Count clicks live

Observe the click-streamer::on-click feed from Chapter 5. The tab is a worker like any other, so it listens the same way watch.ts did: it registers a function (ui::on_click) and observes the feed with it, then reads the starting total with link::click_summary. The feed is registered in default and the tab in its own namespace, so the observer names the feed’s namespace. Two details keep the counter correct:

Observe first, then read. A click that lands between the two is still delivered. Clicks that arrive before the read returns wait in early. The read’s last_id tells the tab which clicks the total already includes, and the tab remembers each later click id it counts. The queue delivers several clicks at once, so they can arrive out of order, and nothing is counted twice or skipped.
Read again after a reconnect. Clicks sent while the tab was disconnected are not replayed, but the stored total is always current.

The cleanup removes the observer and the function on unmount:

src/App.tsx

useEffect(() => {
  let lastId = 0; // clicks up to this id are already in the total that was read
  const counted = new Set<number>(); // clicks above lastId already counted
  let ready = false; // false until the read lands
  const early: Click[] = [];

  function apply(click: Click) {
    // Already in the total, or counted before: clicks can arrive out of order.
    if (click.id <= lastId || counted.has(click.id)) return;
    counted.add(click.id);
    setClicks((n) => n + 1);
    setLatest(click);
  }

  async function sync() {
    ready = false;
    const summary = await worker.call<Record<string, never>, Summary>({
      function_id: "link::click_summary",
      // This tab is in its own namespace; link::click_summary lives in `default`.
      namespace: "default",
      payload: {},
    });
    lastId = summary.last_id;
    counted.clear();
    setClicks(summary.total);
    ready = true;
    early.splice(0).forEach(apply);
  }

  const fn = worker.registerFunction("ui::on_click", async ({ output: click }: { output: Click }) => {
    if (ready) apply(click);
    else early.push(click);
    return null;
  });
  // The feed lives in `default`. The target, ui::on_click, lives in this tab's
  // namespace, which observe fills in from the worker's namespace.
  const listener = worker.observe(
    { function_id: "click-streamer::on-click", namespace: "default", capture: ["output"] },
    "ui::on_click",
  );
  // ready() rejects when the observe is refused, for example FORBIDDEN when
  // the feed is missing from expose_functions or TOO_MANY_LISTENERS from the
  // Ch. 5 cap.
  listener.ready().then(sync, (err) => console.error("live clicks unavailable:", err));
  const stopListening = worker.addConnectionStateListener((state) => {
    if (state === "connected") sync();
  });
  return () => {
    stopListening();
    listener.dispose();
    fn.unregister();
  };
}, []);

Create a function

Register the function the server calls back when it needs human confirmation. It shows a native prompt and returns the user’s decision:

This function registers and runs the exact same as other functions did in previous chapters. Except for managing auth and permissions there is no functional difference between client side and server side.

src/App.tsx

useEffect(() => {
  const fn = worker.registerFunction(
    "user::confirm_destructive_op",
    async (data: { action: string; code: string }) => {
      const confirmed = window.confirm(`Confirm: ${data.action}?`);
      return { confirmed };
    },
  );
  return () => fn.unregister();
}, []);

Create links directly, no gateways

Submit the form by calling link::create directly.

There is no fetch or REST API in the way here, the client worker in the browser works the exact same as every other worker.

src/App.tsx

async function onSubmit(e: React.FormEvent) {
  e.preventDefault();
  const link = await worker.call<{ url: string; code?: string }, { code: string; url: string }>({
    function_id: "link::create",
    // This tab is in its own namespace; link::create lives in `default`.
    namespace: "default",
    payload: { url, code: code || undefined },
  });
  setCreated(link);
  setUrl("");
  setCode("");
}

Create the UI

Finally, the UI: a link shortener form, the last-created link, and the live click counter.

src/App.tsx

  return (
    <main>
      <h1>Linkly</h1>

      <form onSubmit={onSubmit}>
        <label>URL <input value={url} onChange={(e) => setUrl(e.target.value)} required /></label>
        <label>Code (optional) <input value={code} onChange={(e) => setCode(e.target.value)} /></label>
        <button type="submit">Shorten</button>
      </form>

      {created && (
        <p>
          Created <code>{created.code}</code> → <code>{created.url}</code>.
        </p>
      )}

      <section>
        <h2>Live clicks: {clicks}</h2>
        {latest && (
          <p>Last: <code>{latest.code}</code> at <code>{latest.clicked_at}</code></p>
        )}
      </section>

      <footer>
        <small>This tab is session <code>{SESSION}</code>.</small>
      </footer>
    </main>
  )
}

See it work

Start the UI:

npm run dev

Open your browser, Vite typically hosts local websites at http://localhost:5173.

Shorten a link, then watch the clicks arrive in real time

Shorten a link from the form, then visit http://localhost:3111/s/<code> a few times. You’ll see the “Live clicks” counter go up in real time. Reload the tab and the counter starts from the stored total, not from zero.

Request user confirmation directly from the backend

Copy the session id the tab prints, then call the delete for one of your links, naming that session so the server calls back the right tab:

iii call link::request_delete code=<code> session=<session from the tab>

That tab shows a confirm prompt, and the server deletes only after you click OK. The session names the tab’s namespace, so the server asks exactly the browser that owns it, never another tab.

Conclusion

The client is a worker that is exactly the same as every other worker. We connected it through an RBAC-gated port (via rbac-proxy) that uses an auth function to admit it because the browser isn’t trusted like our other workers. However any other worker can be gated this same way. Once everything is set up our client calls server functions directly, observes a server function for live updates, and registers functions the server calls back, all on the same iii bus as the rest of Linkly.

​Add the workers

​Put a proxy in front for browsers

​Gate connections with an auth function

​Add a server-initiated delete

​Scaffold the frontend

​Initialize a Vite project

​Setup a client-side worker

​Create the application

​Add imports

​Add client-side state

​Count clicks live

​Create a function

​Create links directly, no gateways

​Create the UI

​See it work

​Shorten a link, then watch the clicks arrive in real time

​Request user confirmation directly from the backend

​Conclusion

Add the workers

Put a proxy in front for browsers

Gate connections with an auth function

Add a server-initiated delete

Scaffold the frontend

Initialize a Vite project

Setup a client-side worker

Create the application

Add imports

Add client-side state

Count clicks live

Create a function

Create links directly, no gateways

Create the UI

See it work

Shorten a link, then watch the clicks arrive in real time

Request user confirmation directly from the backend

Conclusion