@jk2908/solas 0.3.8 → 0.4.0

package/dist/internal/browser-router/shared.d.ts

@@ -0,0 +1,169 @@
+import { Solas } from '../../solas.js';
+export declare namespace BrowserRouter {
+    export type Params = Record<string, string>;
+    export type Query = Record<string, string | number | boolean>;
+    export type Path = keyof Solas.Routes & string;
+    type Replace = {
+        replace?: boolean;
+    };
+    export type GoOptions = {
+        replace?: boolean;
+        query?: Query;
+        params?: Params;
+    };
+    /**
+     * These targets are used as-is. They are not matched against the route table,
+     * so this covers normal external URLs and hash-only links
+     */
+    export type ExternalTarget = `${string}:${string}` | `//${string}` | `#${string}`;
+    export function isHashOnlyTarget(target: string): boolean;
+    export function isExternalTarget(target: string, origin: string): boolean;
+    /**
+     * Turn a route pattern into the real path shape a caller can use. In practice,
+     * every ':param' or '*' part becomes a plain string slot
+     *
+     * @example
+     * ```ts
+     * // '/p/:id' becomes '/p/${string}'
+     * // '/test/*' becomes '/test/${string}'
+     * // '/posts' stays '/posts'
+     * ```
+     *
+     * @example
+     * ```ts
+     * type A = ResolvedPath<'/posts/:id'>
+     * // '/posts/${string}'
+     * ```
+     *
+     * @example
+     * ```ts
+     * type B = ResolvedPath<'/docs/*'>
+     * // '/docs/${string}'
+     * ```
+     */
+    export type ResolvedPath<TPath extends string> = TPath extends `${infer Start}:${string}/${infer Rest}` ? `${Start}${string}/${ResolvedPath<Rest>}` : TPath extends `${infer Start}:${string}` ? `${Start}${string}` : TPath extends `${infer Start}*${infer Rest}` ? `${Start}${string}${ResolvedPath<Rest>}` : TPath;
+    /**
+     * Once we have a real path, also allow the usual query-string and hash forms
+     *
+     * @example
+     * ```ts
+     * type A = TargetSuffix<'/posts/123'>
+     * // '/posts/123' | '/posts/123?${string}' | '/posts/123#${string}' | '/posts/123?${string}#${string}'
+     * ```
+     */
+    export type TargetSuffix<TPath extends string> = TPath | `${TPath}?${string}` | `${TPath}#${string}` | `${TPath}?${string}#${string}`;
+    /**
+     * This is the final string form a caller can navigate to. It can be an external
+     * URL, or a concrete URL that matches one of the  known routes
+     *
+     * @example
+     * ```ts
+     * type A = Target
+     * // 'https://example.com'
+     * // '#intro'
+     * // '/posts/123'
+     * // '/posts/123?draft=true'
+     * ```
+     */
+    export type Target = ExternalTarget | TargetSuffix<ResolvedPath<Path>>;
+    /**
+     * Extra options for callers who already have a finished target string
+     *
+     * @example
+     * ```ts
+     * const a: TargetConfig = { query: { page: 2 } }
+     * // params is rejected here because the path is already complete
+     * ```
+     */
+    type TargetConfig = {
+        params?: never;
+        query?: Query;
+    };
+    /**
+     * Extra options for callers who pass a route pattern and params separately.
+     * If the route definition says that route needs params, this type makes
+     * those params required. If the route has no params, it rejects them
+     *
+     * @example
+     * ```ts
+     * // if Solas.Routes['/posts/:id'] is { params: { id: string } }
+     * type A = PatternConfig<'/posts/:id'>
+     * // { query?: Query } & { params: { id: string } }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // if Solas.Routes['/about'] has no params field
+     * type B = PatternConfig<'/about'>
+     * // { query?: Query } & { params?: never }
+     * ```
+     */
+    type PatternConfig<TPath extends Path> = {
+        query?: Query;
+    } & (Solas.Routes[TPath] extends {
+        params: infer TParams extends Params;
+    } ? {
+        params: TParams;
+    } : {
+        params?: never;
+    });
+    /**
+     * Typed <Link /> props, using `href` instead of the internal `to` name
+     *
+     * `query` is always allowed
+     * `params` are only allowed when `href` is a known route pattern
+     *
+     * @example
+     * ```ts
+     * const a: LinkProps = { href: '/posts/:id', params: { id: '123' } }
+     * const b: LinkProps = { href: '/posts/123?draft=true' }
+     * ```
+     */
+    export type LinkProps = ({
+        href: Target;
+    } & TargetConfig) | (keyof Solas.Routes extends never ? never : {
+        [TPath in Path]: {
+            href: TPath;
+        } & PatternConfig<TPath>;
+    }[Path]);
+    /**
+     * Typed input for router.go(), using the same route rules as <Link />
+     *
+     * @example
+     * ```ts
+     * go('/p/post-2')
+     * go('/?foo=bar', { replace: true })
+     * ```
+     *
+     * @example
+     * ```ts
+     * go('/p/:id', { params: { id: 'post-2' }, replace: true })
+     * ```
+     *
+     * The last overload is the fallback for plain `string` values. The
+     * `string extends TTo` check stops that fallback from taking over
+     * when TypeScript already knows the caller passed a more specific
+     * string literal
+     *
+     * @example
+     * ```ts
+     * declare const dynamicPath: string
+     * go(dynamicPath, { replace: true })
+     * ```
+     */
+    export type Go = {
+        <TTo extends Path>(to: TTo, opts?: PatternConfig<TTo> & Replace): Promise<string>;
+        <TTo extends Target>(to: TTo, opts?: TargetConfig & Replace): Promise<string>;
+        <TTo extends string>(to: string extends TTo ? TTo : never, opts?: GoOptions): Promise<string>;
+    };
+    /**
+     * Convert a route pattern and params into a real path string. This is used internally
+     * to implement <Link /> and router.go
+     */
+    export function toTarget(path: string, params?: Record<string, string>, query?: Query): string;
+    export {};
+}
+/**
+ * Apply the base path to a target string when needed
+ */
+export declare function withBase(target: string): string;

package/dist/internal/browser-router/shared.js

@@ -0,0 +1,71 @@
+import { BasePath } from '../../utils/base-path.js';
+const BASE_PATH = BasePath.normalise(import.meta.env.BASE_URL);
+export { BrowserRouter };
+var BrowserRouter;
+(function (BrowserRouter) {
+    function isHashOnlyTarget(target) {
+        return target.startsWith('#');
+    }
+    BrowserRouter.isHashOnlyTarget = isHashOnlyTarget;
+    function isExternalTarget(target, origin) {
+        if (isHashOnlyTarget(target))
+            return false;
+        try {
+            return new URL(target, origin).origin !== origin;
+        }
+        catch {
+            return false;
+        }
+    }
+    BrowserRouter.isExternalTarget = isExternalTarget;
+    /**
+     * Convert a route pattern and params into a real path string. This is used internally
+     * to implement <Link /> and router.go
+     */
+    function toTarget(path, params, query) {
+        const used = new Set();
+        let to = path.replaceAll(/:([A-Za-z0-9_]+)/g, (_, key) => {
+            const value = params?.[key];
+            if (value == null) {
+                throw new Error(`[Link]: missing route param: ${key}`);
+            }
+            used.add(key);
+            return encodeURIComponent(value);
+        });
+        if (to.includes('*')) {
+            const remaining = Object.entries(params ?? {}).filter(([key]) => !used.has(key));
+            if (remaining.length !== 1) {
+                throw new Error('[Link]: wildcard routes require exactly one unmatched param');
+            }
+            to = to.replace('*', remaining[0][1].split('/').map(encodeURIComponent).join('/'));
+        }
+        if (!query)
+            return withBase(to);
+        const hashIndex = to.indexOf('#');
+        const hash = hashIndex >= 0 ? to.slice(hashIndex) : '';
+        const pathWithSearch = hashIndex >= 0 ? to.slice(0, hashIndex) : to;
+        const searchIndex = pathWithSearch.indexOf('?');
+        const pathname = searchIndex >= 0 ? pathWithSearch.slice(0, searchIndex) : pathWithSearch;
+        const currentSearch = searchIndex >= 0 ? pathWithSearch.slice(searchIndex + 1) : '';
+        const search = new URLSearchParams(currentSearch);
+        for (const [key, value] of Object.entries(query)) {
+            search.set(key, String(value));
+        }
+        const value = search.toString();
+        return withBase(`${pathname}${value.length > 0 ? `?${value}` : ''}${hash}`);
+    }
+    BrowserRouter.toTarget = toTarget;
+})(BrowserRouter || (BrowserRouter = {}));
+/**
+ * Apply the base path to a target string when needed
+ */
+export function withBase(target) {
+    if (BrowserRouter.isHashOnlyTarget(target))
+        return target;
+    if (target.startsWith('//') || /^[A-Za-z][A-Za-z\d+.-]*:/.test(target))
+        return target;
+    const suffixIndex = target.search(/[?#]/);
+    const pathname = suffixIndex === -1 ? target : target.slice(0, suffixIndex);
+    const suffix = suffixIndex === -1 ? '' : target.slice(suffixIndex);
+    return `${BasePath.apply(pathname || '/', BASE_PATH)}${suffix}`;
+}

package/dist/internal/browser-router/use-router.d.ts

@@ -1,5 +1,5 @@
 export declare function useRouter(): {
-    go: import("./router.js").BrowserRouter.Go;
+    go: import("./shared.js").BrowserRouter.Go;
     prefetch: (path: string) => void;
     isNavigating: boolean;
     url: {

package/dist/internal/codegen/environments.js

@@ -8,18 +8,19 @@ export function writeRSCEntry() {
 		${AUTOGEN_MSG}
 
 		import { createHandler } from '${Solas.Config.PKG_NAME}/env/rsc'
-		import { Prerender } from '${Solas.Config.PKG_NAME}/prerender'
 		import { Solas } from '${Solas.Config.PKG_NAME}'
 
 		import { manifest } from './manifest.js'
 		import { importMap } from './maps.js'
 		import { config } from './config.js'
 
-		const artifactManifest = await Prerender.Artifact.loadManifest(Solas.Config.OUT_DIR)
+		const runtimeManifest = await Solas.Runtime.loadManifest(Solas.Config.OUT_DIR)
 
-		export default createHandler(config, manifest, importMap, artifactManifest)
+		export default createHandler(config, manifest, importMap, runtimeManifest)
 
-		import.meta.hot?.accept()
+		if (import.meta.hot) {
+			import.meta.hot.accept()
+		}
 	`;
 }
 /**

package/dist/internal/env/rsc.d.ts

@@ -1,7 +1,7 @@
 import type { ReactFormState } from 'react-dom/client';
 import type { ImportMap, Manifest, RuntimeConfig } from '../../types.js';
+import { Solas } from '../../solas.js';
 import { Metadata } from '../metadata.js';
-import { Prerender } from '../prerender.js';
 export type RscPayload = {
     returnValue?: {
         ok: boolean;
@@ -20,6 +20,6 @@ export type RscPayload = {
  * route manifest, and import map to build the router once, then returns an object
  * with a fetch method that handles requests
  */
-export declare function createHandler(config: RuntimeConfig, manifest: Manifest, importMap: ImportMap, artifactManifest?: Prerender.Artifact.Manifest | null): {
+export declare function createHandler(config: RuntimeConfig, manifest: Manifest, importMap: ImportMap, runtimeManifest?: Solas.Runtime.Manifest | null): {
     fetch(req: Request): Promise<Response>;
 };

package/dist/internal/env/rsc.js

@@ -1,5 +1,7 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import path from 'node:path';
 import { renderToReadableStream } from '@vitejs/plugin-rsc/rsc';
+import { BasePath } from '../../utils/base-path.js';
 import { Logger } from '../../utils/logger.js';
 import { Solas } from '../../solas.js';
 import { createHttpRouter } from '../http-router/create-http-router.js';
@@ -15,6 +17,22 @@ import DefaultErr from '../ui/defaults/error.js';
 import { RequestContext } from './request-context.js';
 import { getKnownDigest, isKnownError } from './utils.js';
 const logger = new Logger();
+const BASE_PATH = BasePath.normalise(import.meta.env.BASE_URL);
+function resolveFilePath(root, relativePath) {
+    try {
+        const decodedPath = decodeURIComponent(relativePath);
+        if (!decodedPath)
+            return new Response('Forbidden', { status: 403 });
+        const filePath = path.resolve(root, decodedPath);
+        if (filePath !== root && !filePath.startsWith(`${root}${path.sep}`)) {
+            return new Response('Forbidden', { status: 403 });
+        }
+        return filePath;
+    }
+    catch {
+        return new Response('Bad Request', { status: 400 });
+    }
+}
 /**
  * Create the streamed RSC payload and response metadata for a single request.
  * Resolves the route match, collects metadata, and returns the stream,
@@ -24,9 +42,8 @@ async function createPayload(req, manifest, importMap, baseMetadata, returnValue
     const resolver = new Resolver(manifest, importMap);
     const prerender = req.headers.get(`x-${Solas.Config.SLUG}-prerender`) === '1';
     const url = new URL(req.url);
-    const pathname = url.pathname.endsWith('/') && url.pathname !== '/'
-        ? url.pathname.slice(0, -1)
-        : url.pathname;
+    const routedPath = BasePath.strip(url.pathname, BASE_PATH) ?? url.pathname;
+    const pathname = routedPath.endsWith('/') && routedPath !== '/' ? routedPath.slice(0, -1) : routedPath;
     const match = resolver.enhance(resolver.reconcile(pathname, req[Solas.Config.REQUEST_META_KEY].match, req[Solas.Config.REQUEST_META_KEY].error));
     // if there's no match then no user supplied error boundary
     // has been found, and we should server render a default
@@ -141,7 +158,12 @@ async function createPayload(req, manifest, importMap, baseMetadata, returnValue
  * route manifest, and import map to build the router once, then returns an object
  * with a fetch method that handles requests
  */
-export function createHandler(config, manifest, importMap, artifactManifest = null) {
+export function createHandler(config, manifest, importMap, runtimeManifest = null) {
+    const CLIENT_OUTPUT_DIR = path.resolve(Solas.Config.OUT_DIR, 'client');
+    // vite emits solas-controlled assets under dist/client/_solas
+    const SOLAS_ASSETS_DIR = path.resolve(CLIENT_OUTPUT_DIR, Solas.Config.ASSETS_DIR);
+    // requests for /_solas and /_solas/* are reserved
+    const SOLAS_ASSETS_URL_ROOT = `/${Solas.Config.ASSETS_DIR}`;
     const prerenderPathMode = config.trailingSlash === 'always' ? 'always' : 'never';
     /**
      * Create the HTTP response for a single incoming request. Runs actions when needed,
@@ -154,8 +176,12 @@ export function createHandler(config, manifest, importMap, artifactManifest = nu
             temporaryReferences: undefined,
             returnValue: undefined,
         };
-        if (req[Solas.Config.REQUEST_META_KEY].action)
-            opts = await processActionRequest(req);
+        if (req[Solas.Config.REQUEST_META_KEY].action) {
+            opts = await processActionRequest(req, {
+                trustedOrigins: config.trustedOrigins,
+                url: config.url,
+            });
+        }
         const { stream: rscStream, status, ppr, } = await createPayload(req, manifest, importMap, config.metadata, opts.returnValue, opts.formState, opts.temporaryReferences);
         const stream = await rscStream;
         if (!req.headers.get('accept')?.includes('text/html')) {
@@ -191,10 +217,10 @@ export function createHandler(config, manifest, importMap, artifactManifest = nu
             });
         }
         try {
-            const artifactManifestEntry = runtimePpr
-                ? (artifactManifest?.[lookupPath] ?? null)
+            const artifactEntry = runtimePpr
+                ? (runtimeManifest?.artifacts[lookupPath] ?? null)
                 : null;
-            const tryPrelude = artifactManifestEntry?.mode === 'ppr';
+            const tryPrelude = artifactEntry?.mode === 'ppr';
             if (tryPrelude) {
                 const postponedState = await Prerender.Artifact.loadPostponedState(Solas.Config.OUT_DIR, lookupPath);
                 const prelude = await Prerender.Artifact.loadPrelude(Solas.Config.OUT_DIR, lookupPath);
@@ -234,8 +260,8 @@ export function createHandler(config, manifest, importMap, artifactManifest = nu
             });
         }
         catch (err) {
-            // resume/ssr can be the first place react surfaces an http exception from abort(...),
-            // after the initial rsc pass was streamed without request error state. Rerun once
+            // resume/ssr can be the first place React surfaces an HttpException from abort(...),
+            // after the initial RSC pass was streamed without request error state. Rerun once
             // with that error attached so createPayload rebuilds the same route through its
             // nearest matching HttpExceptionBoundary. If request meta already has an error
             // or the error is not an HttpException, then this is a real failure
@@ -272,35 +298,69 @@ export function createHandler(config, manifest, importMap, artifactManifest = nu
     return {
         async fetch(req) {
             const url = new URL(req.url);
-            const accept = req.headers.get('accept') ?? '';
             const method = req.method.toUpperCase();
-            const canonicalPath = config.trailingSlash === 'ignore'
-                ? url.pathname
-                : normalisePathname(url.pathname, config.trailingSlash);
-            if ((method === 'GET' || method === 'HEAD') &&
+            // fast path
+            if (method !== 'GET' && method !== 'HEAD')
+                return httpRouter.fetch(req);
+            const accept = req.headers.get('accept') ?? '';
+            const routedPath = BasePath.strip(url.pathname, BASE_PATH);
+            const canonicalPath = routedPath == null
+                ? null
+                : config.trailingSlash === 'ignore'
+                    ? routedPath
+                    : normalisePathname(routedPath, config.trailingSlash);
+            const canonicalPathname = canonicalPath == null ? null : BasePath.apply(canonicalPath, BASE_PATH);
+            if (canonicalPathname != null &&
+                (method === 'GET' || method === 'HEAD') &&
                 config.trailingSlash !== 'ignore' &&
-                canonicalPath !== url.pathname) {
-                url.pathname = canonicalPath;
+                canonicalPathname !== url.pathname) {
+                url.pathname = canonicalPathname;
                 return Response.redirect(url.toString(), 308);
             }
+            // block the bare /_solas namespace; only concrete solas asset files
+            // under /_solas/* are valid
+            if (routedPath === SOLAS_ASSETS_URL_ROOT) {
+                return new Response('Forbidden', { status: 403 });
+            }
+            if (routedPath?.startsWith(`${SOLAS_ASSETS_URL_ROOT}/`)) {
+                const resolvedPath = resolveFilePath(SOLAS_ASSETS_DIR, routedPath.slice(`${SOLAS_ASSETS_URL_ROOT}/`.length));
+                // pass through bad-request or forbidden responses from path resolution
+                if (resolvedPath instanceof Response)
+                    return resolvedPath;
+                return HttpRouter.serveStatic(resolvedPath, req, config.precompress, {
+                    'Cache-Control': 'public, immutable, max-age=31536000',
+                });
+            }
+            if (routedPath && runtimeManifest?.publicFiles.has(routedPath)) {
+                const resolvedPath = resolveFilePath(CLIENT_OUTPUT_DIR, routedPath.slice(1));
+                // pass through bad-request or forbidden responses from path resolution
+                if (resolvedPath instanceof Response)
+                    return resolvedPath;
+                return HttpRouter.serveStatic(resolvedPath, req, config.precompress);
+            }
             // fully prerendered html can be served straight from disk for normal
             // document requests, but build-time artifact requests must bypass
             // this shortcut so they still render fresh output
-            if (!import.meta.env.DEV &&
+            if (canonicalPath != null &&
+                !import.meta.env.DEV &&
                 accept.includes('text/html') &&
                 req.headers.get(`x-${Solas.Config.SLUG}-prerender-artifact`) !== '1') {
                 // turn the request path into the normal route shape we use for artifact lookups
                 const lookupPath = normalisePathname(canonicalPath, prerenderPathMode);
                 // only full prerender routes have a saved html file we can serve directly
-                const prerenderPath = artifactManifest?.[lookupPath]?.mode === 'full'
+                const prerenderPath = runtimeManifest?.artifacts[lookupPath]?.mode === 'full'
                     ? Prerender.Artifact.getFilePath(Solas.Config.OUT_DIR, lookupPath, Prerender.Artifact.FULL_PRERENDER_FILENAME)
                     : null;
                 if (prerenderPath) {
-                    const res = await HttpRouter.serve(prerenderPath, req, config.precompress, {
-                        // avoid shared or proxy caching unless users opt into public caching later
+                    const res = await HttpRouter.serveStatic(prerenderPath, req, config.precompress, {
+                        // keep prerendered html out of shared caches unless users opt into explicit public caching
+                        // default to private, no-store for now
+                        // @todo: public caching?
                         'Cache-Control': 'private, no-store',
                         'Content-Type': 'text/html; charset=utf-8',
                     });
+                    // only a missing prerendered file should fall back to normal request handling
+                    // any other static-file response should be returned as-is
                     if (res.status !== 404)
                         return res;
                 }

package/dist/internal/http-router/create-http-router.d.ts

@@ -3,4 +3,4 @@ import { HttpRouter } from './router.js';
 /**
  * Create the HTTP router from the generated manifest and import map
  */
-export declare function createHttpRouter(config: Pick<PluginConfig, 'precompress' | 'trailingSlash'>, manifest: Manifest, importMap: ImportMap, rsc: (req: SolasRequest) => Response | Promise<Response>): HttpRouter;
+export declare function createHttpRouter(config: Pick<PluginConfig, 'trailingSlash' | 'trustedOrigins' | 'url'>, manifest: Manifest, importMap: ImportMap, rsc: (req: SolasRequest) => Response | Promise<Response>): HttpRouter;

package/dist/internal/http-router/create-http-router.js

@@ -49,9 +49,11 @@ function mergeMiddlewares(left, right) {
 export function createHttpRouter(config, manifest, importMap, rsc) {
     const router = new HttpRouter({
         trailingSlash: config.trailingSlash,
+        csrf: {
+            trustedOrigins: config.trustedOrigins,
+            url: config.url,
+        },
     });
-    // static assets stay outside route middleware conventions and are registered once
-    router.add('/assets/*', 'GET', HttpRouter.static(config));
     for (const [, group] of createHandlerGroups(manifest)) {
         if (!Array.isArray(group)) {
             if ('paths' in group) {

package/dist/internal/http-router/router.d.ts

@@ -1,4 +1,5 @@
-import type { HttpMethod, PluginConfig, SolasRequest } from '../../types.js';
+import type { PluginConfig, SolasRequest } from '../../types.js';
+import { CsrfConfig } from '../server/csrf.js';
 export declare namespace HttpRouter {
     type Params = Record<string, string | string[]>;
     type Handler = (req: SolasRequest) => Response | Promise<Response>;
@@ -24,6 +25,7 @@ export declare namespace HttpRouter {
     };
     type Options = {
         trailingSlash?: NonNullable<PluginConfig['trailingSlash']>;
+        csrf?: CsrfConfig;
     };
     type Registry = {
         static: Map<string, Route>;
@@ -56,24 +58,12 @@ export declare class HttpRouter {
      * Register a route handler
      */
     add(path: string, method: string, handler: HttpRouter.Handler, params?: string[], middleware?: HttpRouter.Middleware[]): this;
-    /**
-     * Match a path and method, returning params and route
-     */
-    match(path: string, method: HttpMethod): {
-        route: HttpRouter.Route;
-        params: HttpRouter.Params;
-    } | null;
     /**
      * Handle an incoming request
      */
     fetch(req: Request): Promise<Response>;
-    /**
-     * Serve static assets from the output directory
-     * @note generated /assets/* handlers bypass +middleware conventions
-     */
-    static static(config: PluginConfig): (req: Request) => Promise<Response>;
     /**
      * Serve a file with optional compression content negotiation
      */
-    static serve(filePath: string, req: Request, precompress?: boolean, headers?: Record<string, string>): Promise<Response>;
+    static serveStatic(filePath: string, req: Request, precompress?: boolean, headers?: Record<string, string>): Promise<Response>;
 }