@everystack/server 0.2.12 → 0.2.13

package/README.md

@@ -16,6 +16,7 @@ pnpm add @everystack/server
 | `@everystack/server/db` | SST Resource-linked database connection |
 | `@everystack/server/ssr` | Expo web SSR bundle serving |
 | `@everystack/server/image` | On-demand image resizing via Sharp |
+| `@everystack/server/media` | Fingerprinted media asset URL resolver |
 | `@everystack/server/migrate` | Drizzle migration runner |
 | `@everystack/server/worker` | SQS job queue consumer |
 | `@everystack/server/stubs` | esbuild bundling helpers for client packages |
@@ -212,6 +213,60 @@ Validates URL query params into transform options:
 | `q` | 1–100 | Quality |
 | `dpr` | 1–3 | Device pixel ratio (multiplies w/h) |
 
+## Media Assets (`@everystack/server/media`)
+
+Resolves logical media asset paths to fingerprinted CDN URLs. During `everystack update`, media assets are uploaded with content-hash suffixes (e.g., `logo-a1b2c3d4.png`) and a `media-manifest.json` is written to the media bucket. This module loads that manifest and resolves URLs at runtime.
+
+### `createMediaResolver(config)`
+
+```typescript
+import { createMediaResolver } from '@everystack/server/media';
+
+const media = createMediaResolver({
+  bucket: Resource.Media.name,  // S3 bucket with media-manifest.json
+  cdnUrl: process.env.CDN_URL,  // CDN base URL (no trailing slash)
+  ttlMs: 60_000,                // Manifest cache TTL (default: 1 minute)
+});
+```
+
+### `resolve(logicalPath)`
+
+Async. Returns the fingerprinted CDN URL. Falls back to the logical path if the manifest is unavailable or the path isn't mapped.
+
+```typescript
+const logoUrl = await media.resolve('email/logo.png');
+// → "https://cdn.example.com/email/logo-a1b2c3d4.png"
+```
+
+### `resolveSync(logicalPath)`
+
+Sync. Uses the cached manifest only. Returns `null` if no manifest has been loaded yet.
+
+```typescript
+const url = media.resolveSync('og/default.png');
+// → "https://cdn.example.com/og/default-f6e5d4c3.png" or null
+```
+
+### `preload()`
+
+Loads the manifest during Lambda init. Call this in `createLambdaHandler`'s `init` to amortize the S3 call across all requests.
+
+```typescript
+export const handler = createLambdaHandler({
+  init: async () => {
+    await media.preload();
+    return { api };
+  },
+  // ...
+});
+```
+
+**Caching behavior:**
+- Manifest cached in module scope across warm Lambda invocations
+- After TTL expires, revalidates via `HeadObject` ETag comparison (one cheap HEAD call)
+- Full re-fetch only when the manifest content changes
+- S3 errors return stale cache gracefully
+
 ## Migrations (`@everystack/server/migrate`)
 
 ### `runMigrations(db, migrationsFolder)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -51,6 +51,10 @@
     "./kvs": {
       "types": "./src/kvs.ts",
       "default": "./src/kvs.ts"
+    },
+    "./media": {
+      "types": "./src/media.ts",
+      "default": "./src/media.ts"
     }
   },
   "scripts": {

package/src/media.ts

@@ -0,0 +1,126 @@
+/**
+ * @everystack/server/media — Fingerprinted media asset URL resolver.
+ *
+ * Loads the media manifest from S3 and resolves logical asset names
+ * to fingerprinted CDN URLs. Lazy-loaded, cached with TTL for
+ * revalidation on new deploys.
+ *
+ * Usage:
+ *   const media = createMediaResolver({ bucket: Resource.Media.name, cdnUrl: process.env.CDN_URL });
+ *   await media.preload();
+ *   const url = await media.resolve('email/logo.png');
+ *   // → "https://cdn.example.com/email/logo-a1b2c3d4.png"
+ */
+
+export interface MediaManifest {
+  version: number;
+  generatedAt: string;
+  files: Record<string, string>;
+}
+
+export interface MediaResolverConfig {
+  /** S3 bucket name for media assets. */
+  bucket: string;
+  /** AWS region (defaults to process.env.AWS_REGION). */
+  region?: string;
+  /** CDN base URL (e.g., 'https://cdn.example.com'). No trailing slash. */
+  cdnUrl?: string;
+  /** Manifest TTL in milliseconds. Default: 60_000 (1 minute). */
+  ttlMs?: number;
+}
+
+interface CachedManifest {
+  manifest: MediaManifest;
+  etag: string;
+  loadedAt: number;
+}
+
+export function createMediaResolver(config: MediaResolverConfig): MediaResolver {
+  const {
+    bucket,
+    ttlMs = 60_000,
+  } = config;
+  const region = config.region || process.env.AWS_REGION;
+  const cdnUrl = (config.cdnUrl || '').replace(/\/$/, '');
+
+  let cached: CachedManifest | null = null;
+
+  async function loadManifest(): Promise<MediaManifest | null> {
+    const now = Date.now();
+
+    if (cached && (now - cached.loadedAt) < ttlMs) {
+      return cached.manifest;
+    }
+
+    try {
+      const { S3Client, GetObjectCommand, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+      const client = new S3Client({ region });
+
+      // ETag-based revalidation: cheap HEAD instead of full GET
+      if (cached) {
+        const head = await client.send(new HeadObjectCommand({
+          Bucket: bucket,
+          Key: 'media-manifest.json',
+        }));
+        if (head.ETag === cached.etag) {
+          cached.loadedAt = now;
+          return cached.manifest;
+        }
+      }
+
+      const response = await client.send(new GetObjectCommand({
+        Bucket: bucket,
+        Key: 'media-manifest.json',
+      }));
+      if (!response.Body) return cached?.manifest ?? null;
+
+      const bytes = await response.Body.transformToByteArray();
+      const manifest: MediaManifest = JSON.parse(
+        Buffer.from(bytes).toString('utf8'),
+      );
+
+      cached = {
+        manifest,
+        etag: response.ETag || '',
+        loadedAt: now,
+      };
+      return manifest;
+    } catch {
+      // S3 error — return stale cache if available
+      return cached?.manifest ?? null;
+    }
+  }
+
+  return {
+    async resolve(logicalPath: string): Promise<string> {
+      const manifest = await loadManifest();
+      const resolved = manifest?.files[logicalPath] ?? logicalPath;
+      return cdnUrl ? `${cdnUrl}/${resolved}` : `/${resolved}`;
+    },
+
+    resolveSync(logicalPath: string): string | null {
+      if (!cached) return null;
+      const resolved = cached.manifest.files[logicalPath] ?? logicalPath;
+      return cdnUrl ? `${cdnUrl}/${resolved}` : `/${resolved}`;
+    },
+
+    async preload(): Promise<void> {
+      await loadManifest();
+    },
+
+    clearCache(): void {
+      cached = null;
+    },
+  };
+}
+
+export interface MediaResolver {
+  /** Resolve a logical media path to a fingerprinted CDN URL. Falls back to logical path if manifest unavailable. */
+  resolve(logicalPath: string): Promise<string>;
+  /** Sync resolve from cached manifest. Returns null if no manifest cached. */
+  resolveSync(logicalPath: string): string | null;
+  /** Pre-load the manifest. Call during Lambda init. */
+  preload(): Promise<void>;
+  /** Clear the cached manifest (for testing). */
+  clearCache(): void;
+}

package/src/plugin.ts

@@ -504,6 +504,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
               ctx,
               db, schema: ctx.schema,
               eq, and, or, gt, lt, gte, lte, ne, count, sum, avg, sql, desc, asc,
+              current_user: payloadUser ?? null,
               ...models,
               ...authHelpers,
             };
@@ -519,8 +520,10 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
 
           let result: unknown;
 
-          if (payloadUser && options.pgSettings) {
-            const settings = options.pgSettings(payloadUser);
+          if (options.pgSettings) {
+            // Always apply pgSettings when configured — enforces RLS.
+            // Without a logged-in user, pgSettings(null) returns anon role settings.
+            const settings = options.pgSettings(payloadUser ?? null);
 
             async function applySettings(tx: any) {
               const role = settings['role'];
@@ -538,7 +541,6 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
             }
 
             if (sandbox) {
-              // pgSettings + sandbox: apply settings, eval, capture result, rollback
               try {
                 await ctx.db.transaction(async (tx: any) => {
                   await applySettings(tx);
@@ -549,14 +551,12 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
                 if (err !== SANDBOX_ROLLBACK) throw err;
               }
             } else {
-              // pgSettings without sandbox: normal transaction
               result = await ctx.db.transaction(async (tx: any) => {
                 await applySettings(tx);
                 return evalExpression(tx);
               });
             }
           } else if (sandbox) {
-            // Sandbox without auth: wrap in transaction and rollback
             try {
               await ctx.db.transaction(async (tx: any) => {
                 result = await evalExpression(tx);
@@ -569,8 +569,21 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
             result = await evalExpression(ctx.db);
           }
 
+          // Safe-serialize: handle circular refs, Symbols, and complex objects
+          // that Lambda can't JSON.stringify (e.g. Drizzle schema objects)
+          let safeResult: unknown;
+          try {
+            JSON.stringify(result);
+            safeResult = result;
+          } catch {
+            // Not JSON-serializable — return a useful string representation
+            safeResult = typeof result === 'object' && result !== null
+              ? `[${result.constructor?.name ?? 'Object'}: keys=${Object.keys(result).join(', ')}]`
+              : String(result);
+          }
+
           // Build response with optional auth side-channel
-          const response: Record<string, unknown> = { result };
+          const response: Record<string, unknown> = { result: safeResult };
           if (authSignal.changed) {
             response._auth = { user: authSignal.user };
           }