You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit bc2ffdb
Browse filesBrowse the repository at this point in the historyBrowse files
feat(routes): check SSE and live stream client URLs with typedRoutes (#741)
## Summary
With `routing.typedRoutes` on, the `url` argument of
`connectEventStream()` (`void/sse/client`) and `connectLiveStream()`
(`void/live/client`) is now checked against the app's routes, like
`Link`, router methods and `c.rewrite()`.
Both clients accept:
- one of the app's route URLs, including template literals for dynamic
routes and a query/hash suffix (`` `/api/users/${id}` ``),
- an absolute `http://` or `https://` URL, for a stream on another
origin,
- a `URL` object.
They reject unknown paths, `ws://`/`wss://`, `mailto:`, `tel:`,
same-page `?`/`#` URLs and unchecked `string` values. A string
TypeScript can't check is cast with `as RouteUrl`, which turns the check
off for that URL.
```ts
connectEventStream('/api/logs'); // ok
connectEventStream(`/api/users/${id}`); // ok
connectEventStream('https://example.com/events'); // ok
connectEventStream(path as RouteUrl); // ok, unchecked
connectEventStream('/api/lgos'); // type error
connectLiveStream('wss://example.com/live'); // type error
```
With the flag off, the parameter stays `string | URL`.
Neither client has a base-URL option: a path always resolves against the
page's origin, so route checking applies to every relative string. The
accepted string type (`RequestUrl` in `route-url.ts`) stays internal
rather than being exported from `void/routes`; `Href` was not reused
because it also allows `mailto:`, `tel:` and same-page URLs.
## Docs
- `docs/guide/sse.md`, `docs/guide/live.md`: what `typedRoutes` checks
for the client URL and how to cast.
- `docs/guide/type-safety.md`: "Checked URL strings" list, a paragraph
on stream URLs, and the "What Gets Checked" table.
- `docs/reference/config.md`: `routing.typedRoutes`.
## Tests
- `packages/void/test/integration/route-url-builder.test.ts`: the typed
fixture (generated and package declarations) accepts a known route, a
dynamic template literal, a `RouteUrl`, `http(s)` URLs, a `URL` and a
`RouteUrl` cast; it rejects an unknown path, `ws://`/`wss://`,
`#details` and an unchecked `string`. Reverting the SSE client's
parameter to `string | URL` in `dist` makes the four SSE
`@ts-expect-error` lines fail.
- `packages/void/test/unit/typed-navigation.typecheck.ts`: with the flag
off, both parameters are exactly `string | URL`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/guide/live.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -77,6 +77,8 @@ stream.close();
77
77
78
78
Subscription IDs are scoped to a connection. Reusing an ID replaces its subscription. After reconnecting, the helper restores active subscriptions and sends their latest `eventId` as `lastEventId`.
79
79
80
+
With [`routing.typedRoutes`](../reference/config.md#routing-typedroutes), the URL must match one of your routes or be an `http://` or `https://` URL. Cast a `string` that TypeScript can't check with `as RouteUrl` from `void/routes`. The cast turns off the check for that URL.
81
+
80
82
## Publish
81
83
82
84
Publish from any server-side code that has a Void runtime env:
Copy file name to clipboardExpand all lines: docs/guide/sse.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -141,6 +141,8 @@ stream.close();
141
141
142
142
The client wraps native `EventSource`. It supports cookie credentials and typed event handlers, but it does not support request bodies or arbitrary headers. Use cookie auth, signed URLs, or a fetch-based streaming route when you need custom headers.
143
143
144
+
With [`routing.typedRoutes`](../reference/config.md#routing-typedroutes), the URL must match one of your routes, such as `` `/api/jobs/${id}` ``, or be an `http://` or `https://` URL. Cast a `string` that TypeScript can't check with `as RouteUrl` from `void/routes`. The cast turns off the check for that URL.
145
+
144
146
JSON parsing is the default. Set `parse: 'text'` or pass a custom parser for non-JSON payloads:
[`routing.typedRoutes`](../reference/config.md#routing-typedroutes) checks plain URL strings in `Link`'s `href`, `router.visit()`, `router.prefetch()`, `router.flush()`, `c.rewrite()`, and `useIslandForm()`'s `post()`, `put()`, `patch()`, `delete()`, and `submit()`. Apps created with `void init` have it on. To turn it on in an existing app:
260
+
[`routing.typedRoutes`](../reference/config.md#routing-typedroutes) checks plain URL strings in `Link`'s `href`, `router.visit()`, `router.prefetch()`, `router.flush()`, `c.rewrite()`, `connectEventStream()`, `connectLiveStream()`, and `useIslandForm()`'s `post()`, `put()`, `patch()`, `delete()`, and `submit()`. Apps created with `void init` have it on. To turn it on in an existing app:
261
261
262
262
```ts
263
263
// void.config.ts
@@ -324,6 +324,8 @@ import { routeUrl } from 'void/routes';
324
324
325
325
Links can also point to the current page (`?page=2`, `#comments`) and to `http://`, `https://`, `mailto:`, and `tel:` URLs. Relative paths such as `../settings` are rejected; use the absolute path. A fixed part with spaces or non-ASCII characters can be written as is (`/café menu`) or percent-encoded in uppercase, as `routeUrl()` returns it (`/caf%C3%A9%20menu`). A dynamic segment matches any text, including none, so `/users/:id` also accepts `/users/` and `/users/42/edit`. With a root dynamic page such as `pages/[slug].tsx`, `.vue`, or `.svelte`, a protocol-relative URL like `//example.com` passes too.
326
326
327
+
The [SSE](./sse.md#client) and [live stream](./live.md#subscribe-from-the-browser) clients, `connectEventStream()` and `connectLiveStream()`, take one of your routes or an `http://` or `https://` URL for a stream on another origin. They reject same-page, `mailto:`, `tel:`, and `ws://` URLs. Cast a stream URL that TypeScript can't check with `as RouteUrl`; the cast turns off the check for that URL.
328
+
327
329
`c.redirect()` is not part of that check. It still accepts any string. Build an internal path with `routeUrl()`, or annotate a full path with `satisfies RouteUrl`. With `routing.typedRoutes` on, a path that matches no route is a type error. An external URL stays a plain string:
328
330
329
331
```ts
@@ -395,20 +397,20 @@ Route types update with the dev server. For CI or standalone typechecking, run `
Copy file name to clipboardExpand all lines: docs/reference/config.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -378,7 +378,7 @@ routing: {
378
378
379
379
#### `routing.typedRoutes`
380
380
381
-
Type-check URL strings against your app's routes in `Link`'s `href`, `router.visit()`, `router.prefetch()`, `router.flush()`, `c.rewrite()`, and `useIslandForm()`. Omitted or `false` means off; `void init` turns it on for new apps. It changes types only, not navigation at runtime. Link and router strings may also be same-page queries or hashes, or `http://`, `https://`, `mailto:`, and `tel:` URLs. `useIslandForm()` takes a route URL. `c.redirect()`, `revalidate({ paths })`, and `routing.prerender` stay plain strings until you annotate them. See [Checked URL strings](../guide/type-safety#checked-url-strings).
381
+
Type-check URL strings against your app's routes in `Link`'s `href`, `router.visit()`, `router.prefetch()`, `router.flush()`, `c.rewrite()`, `useIslandForm()`, `connectEventStream()`, and `connectLiveStream()`. Omitted or `false` means off; `void init` turns it on for new apps. It changes types only, not navigation at runtime. Link and router strings may also be same-page queries or hashes, or `http://`, `https://`, `mailto:`, and `tel:` URLs. `useIslandForm()` takes a route URL; `connectEventStream()` and `connectLiveStream()` also take `http://` and `https://` URLs. `c.redirect()`, `revalidate({ paths })`, and `routing.prerender` stay plain strings until you annotate them. See [Checked URL strings](../guide/type-safety#checked-url-strings).
0 commit comments