lowlander 0.4.0 → 0.6.0

package/server/wshandler.ts

@@ -2,9 +2,13 @@ import DataPack from 'edinburgh/datapack';
 import { warpsocket, Socket, StreamTypeBase, pushModel, ServerProxy, logLevel } from './server.js';
 import { SERVER_MESSAGES, CLIENT_MESSAGES } from './protocol.js';
 import * as E from 'edinburgh';
+import type { HttpRequest, HttpResponse } from 'warpsocket';
 
 let mainApi: object | undefined;
 
+/** @internal Used by the dashboard module to introspect the user's API. */
+export function getMainApi(): object | undefined { return mainApi; }
+
 export const socketProxies = new Map<number, Map<number, any>>(); // {socketId: {proxyId: proxyObject}}
 
 export interface Request {
@@ -26,16 +30,40 @@ function sendError(socketId: number, requestId: number, message: string) {
     send(socketId, requestId, SERVER_MESSAGES.error, message);
 }
 
-export async function handleStart(apiFile: any) {
+let dashboardPassword = '';
+/** @internal Used by the dashboard module to authenticate requests. */
+export function getPassword(): string { return dashboardPassword; }
+
+export async function handleStart(arg: any) {
+    const { apiFile, password } = arg;
+    dashboardPassword = password;
     if (logLevel >= 1) console.log('[lowlander] Worker started, loading', apiFile);
     mainApi = await import(apiFile);
 }
 
+export async function handleHttpRequest(req: HttpRequest, res: HttpResponse): Promise<void> {
+    const handler = (mainApi as any)?.handleHttpRequest;
+    if (typeof handler === 'function') {
+        return handler(req, res);
+    }
+    res.statusCode = 404;
+    res.setHeader('content-type', 'text/plain');
+    res.end('Not found');
+}
+
 
 export async function handleBinaryMessage(message: Uint8Array, socketId: number) {
+    if (logLevel >= 2) console.log('[lowlander] handleBinaryMessage socket', socketId, 'bytes', message.length, 'hex', Array.from(message.slice(0, 16)).map(b => b.toString(16).padStart(2,'0')).join(' '));
     const pack = new DataPack(message);
-    const requestId = pack.readPositiveInt();
-    const type = pack.readNumber();
+    let requestId: number;
+    let type: number;
+    try {
+        requestId = pack.readPositiveInt();
+        type = pack.readNumber();
+    } catch (e: any) {
+        console.error('[lowlander] Failed to parse message header:', e.message, 'hex:', Array.from(message.slice(0, 16)).map(b => b.toString(16).padStart(2,'0')).join(' '));
+        return;
+    }
 
     if (type === CLIENT_MESSAGES.cancel) {
         // Delete server proxy object, if any
@@ -81,7 +109,16 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
         // Obtain function reference
         const methodName = pack.readString();
         let func = (api as any)[methodName];
-        if (typeof func !== 'function' || methodName.startsWith('_')) {
+        // `_dashboard` is the one underscore-prefixed name reserved for the
+        // dashboard module; everything else with a leading underscore is private.
+        // Also block: classes (typeof === 'function' but not callable as plain
+        // function), and Object.prototype methods accessible via prototype chain.
+        if (
+            typeof func !== 'function' ||
+            (methodName.startsWith('_') && methodName !== '_dashboard') ||
+            Function.prototype.toString.call(func).trimStart().startsWith('class ') ||
+            Object.prototype.hasOwnProperty.call(Object.prototype, methodName)
+        ) {
             return sendError(socketId, requestId, `Method not found: ${methodName}`);
         }
 
@@ -107,15 +144,21 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
                 // Result processing/serialization should be within the transaction, as it may involve (lazy) loading models.
                 // The actual socket send remains deferred until after commit.
 
-                if (response instanceof ServerProxy) {
+                // NOTE: Use duck-typing instead of instanceof for ServerProxy and StreamTypeBase,
+                // because api.js and wshandler.js each bundle their own copy of server.ts,
+                // so instanceof checks across those two bundles always return false.
+                // E.Model is safe to use because edinburgh is externalized (shared).
+                if (response !== null && typeof response === 'object' && 'api' in response && 'value' in response) {
+                    const serverProxyResponse = response as ServerProxy<any, any>;
                     let proxies = socketProxies.get(socketId);
                     if (!proxies) socketProxies.set(socketId, proxies = new Map());
                     if (logLevel >= 3) console.log('[lowlander] Setting proxy id', requestId, 'for socket', socketId);
-                    proxies.set(requestId, response.api);
+                    proxies.set(requestId, serverProxyResponse.api);
 
-                    if (response.value instanceof StreamTypeBase) {
-                        const StreamType = response.value.constructor as typeof StreamTypeBase<any>;
-                        const instance = response.value._instance;
+                    if (serverProxyResponse.value !== null && typeof serverProxyResponse.value === 'object' && (serverProxyResponse.value as any)._instance instanceof E.Model) {
+                        const streamValue = serverProxyResponse.value as unknown as StreamTypeBase<any>;
+                        const StreamType = streamValue.constructor as typeof StreamTypeBase<any>;
+                        const instance = streamValue._instance;
 
                         const virtualSocketId = warpsocket.createVirtualSocket(socketId, DataPack.createUint8Array(requestId, SERVER_MESSAGES.model_data));
                         virtualSocketIds.push(virtualSocketId);
@@ -124,12 +167,13 @@ export async function handleBinaryMessage(message: Uint8Array, socketId: number)
                         const cacheMs = StreamType.cache !== undefined ? StreamType.cache * 1000 : undefined;
                         pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response_proxy_model, virtualSocketIds, instance.getPrimaryKeyHash() + StreamType.id, cacheMs);
                     } else {
-                        pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response_proxy, response.value, virtualSocketIds);
+                        pendingPacket = DataPack.createUint8Array(requestId, SERVER_MESSAGES.response_proxy, serverProxyResponse.value, virtualSocketIds);
                     }
 
-                } else if (response instanceof StreamTypeBase) {
-                    const StreamType = response.constructor as typeof StreamTypeBase<any>;
-                    const instance = response._instance;
+                } else if (response !== null && typeof response === 'object' && (response as any)._instance instanceof E.Model) {
+                    const streamResponse = response as unknown as StreamTypeBase<any>;
+                    const StreamType = streamResponse.constructor as typeof StreamTypeBase<any>;
+                    const instance = streamResponse._instance;
 
                     // Create a virtual socket for the model updates, prefixed by requestId + 'd'
                     const virtualSocketId = warpsocket.createVirtualSocket(socketId, DataPack.createUint8Array(requestId, SERVER_MESSAGES.model_data));

package/skill/SKILL.md

@@ -25,17 +25,29 @@ This library is built on top of a number of libraries by the same author:
 
 Lowlander glues these together and adds real-time partial data synchronization and type-safe RPCs to provide a framework for rapidly building performant full-stack (database included!) web applications.
 
+## Example project
+
+An example project is included in `examples/helloworld`. To run it:
+
+```bash
+npm run example
+```
+
+Opens at http://localhost:8080 with the Aberdeen dashboard at http://localhost:8080/_dashboard (password printed to console on start).
+
+This is what the example dashboard looks like:
+
+![dashboard screenshot](dashboard_screenshot.png)
+
 ## Tutorial
 
 ### Project Setup
 
 ```bash
-bun init
-bun add lowlander aberdeen edinburgh
+npm init
+npm add lowlander aberdeen edinburgh
 ```
 
-(npm should also work for all of this.)
-
 Create the project structure:
 
 ```
@@ -150,6 +162,24 @@ const PersonStream = createStreamType(Person, fields, { cache: 30 }); // cache f
 
 After a stream with caching goes out of scope, the server keeps it alive for that many seconds, so that if the same stream is requested again with the same parameters, it can be reused instantly without re-sending initial data or re-subscribing to updates. Cached stream rpcs also deduplicate within that time window, so if the same stream is requested multiple times while it's still active or cached, only one stream is created on the server and shared among all requests.
 
+#### Virtual (computed) fields
+
+Plain getter properties on the model can be selected like any other field. Lowlander detects them and re-evaluates on each commit; an update is pushed only when the getter's return value actually changes:
+
+```ts
+const Person = E.defineModel('Person', class {
+    name = E.field(E.string);
+    age  = E.field(E.number);
+    get greeting() { return `Hi, I'm ${this.name} and I'm ${this.age}!`; }
+}, { pk: 'name' });
+
+const PersonStream = createStreamType(Person, {
+    greeting: true,
+});
+```
+
+On every model update, `greeting` will be invoked for both the old and new data, to check for changes. So avoid doing expensive operations in these getters.
+
 ### ServerProxy for Stateful APIs
 
 Wrap a class instance to expose per-connection stateful methods:
@@ -339,10 +369,50 @@ Set the `LOWLANDER_LOG_LEVEL` environment variable to a number from 0 to 3:
 
 Set `EDINBURGH_LOG_LEVEL` similarly for Edinburgh internals.
 
+### Dashboard
+
+Lowlander ships with an optional admin/developer dashboard for inspecting
+Edinburgh models, browsing index rows, listing RPC methods, viewing source
+code, and peeking at warpsocket debug state (channels, sockets, workers,
+KV). It's a single self-contained HTML bundle.
+
+To enable it:
+
+1. Re-export `_dashboard` from your top-level API module:
+
+   ```ts
+   // server/api.ts
+   export { _dashboard } from "lowlander/dashboard";
+   ```
+
+2. Serve the bundled HTML by calling `serveDashboard(res)` from a
+   `warpsocket` `handleHttpRequest` export:
+
+   ```ts
+   import type { HttpRequest, HttpResponse } from "warpsocket";
+   import { serveDashboard } from "lowlander/dashboard";
+
+   export function handleHttpRequest(req: HttpRequest, res: HttpResponse) {
+       if (req.url === '/_dashboard' || req.url.startsWith('/_dashboard?')) {
+           return serveDashboard(res);
+       }
+       // … serve your own static files …
+   }
+   ```
+
+3. On first server start (per warpsocket KV namespace), a random password
+   is generated and printed to the console. Override with the
+   `LOWLANDER_DASHBOARD_PASSWORD` env var.
+
+The dashboard prompts for the websocket URL (defaults to the current host)
+and password on first load, then stores them in localStorage.
+
 ## Server API Reference
 
 The following is auto-generated from `server/server.ts`:
 
+### [getStreamTypesForModel](getStreamTypesForModel.md) · function
+
 ### [createStreamType](createStreamType.md) · function
 
 Creates a stream type for reactive model streaming to clients with automatic updates.
@@ -369,7 +439,7 @@ Starts the Lowlander WebSocket server.
 
 ### StreamTypeBase · abstract class
 
-[object Object],[object Object],[object Object]
+Base class for stream types created by .
 
 **Type Parameters:**
 
@@ -377,7 +447,7 @@ Starts the Lowlander WebSocket server.
 
 #### StreamTypeBase.fields · static property
 
-**Type:** `{ [key: string]: number | true; }`
+**Type:** `{ [key: string]: number | boolean; }`
 
 #### StreamTypeBase.id · static property
 
@@ -446,29 +516,9 @@ Transforms server-side API objects to client-side proxy objects with type-safe R
 WebSocket connection to a Lowlander server with type-safe RPC, automatic reconnection,
 and reactive updates.
 
-#### connection.ws · property
-
-**Type:** `WebSocket`
-
-#### connection.activeRequests · property
-
-**Type:** `Map<number, ActiveRequest>`
-
-#### connection.requestCounter · property
-
-**Type:** `number`
-
-#### connection.reconnectAttempts · property
-
-**Type:** `number`
-
-#### connection.onlineProxy · property
-
-**Type:** `ValueRef<boolean>`
+#### connection.[A.OPAQUE] · getter
 
-#### connection.streamCache · property
-
-**Type:** `Map<string, StreamCacheEntry>`
+**Type:** `true`
 
 #### connection.api · property
 
@@ -484,29 +534,10 @@ Returns the current connection status. Reactive in Aberdeen scopes.
 
 **Signature:** `() => boolean`
 
-#### connection.connect · method
-
-**Signature:** `() => void`
-
-#### connection.reconnect · method
-
-**Signature:** `() => void`
-
-#### [connection.pruneCommitIds](Connection_pruneCommitIds.md) · method
-
-#### connection.cancelRequest · method
-
-**Signature:** `(request: ActiveRequest) => void`
+#### connection.getError · method
 
-**Parameters:**
-
-- `request: ActiveRequest`
-
-#### connection.startLinger · method
-
-**Signature:** `(cached: StreamCacheEntry) => void`
+Returns the last WebSocket error message, or `undefined` if there is none.
+Clears automatically when the connection comes online. Reactive in Aberdeen scopes.
 
-**Parameters:**
-
-- `cached: StreamCacheEntry`
+**Signature:** `() => string`
 

package/skill/getStreamTypesForModel.md

@@ -0,0 +1,7 @@
+### getStreamTypesForModel · function
+
+**Signature:** `(Model: AnyModelClass) => readonly (typeof StreamTypeBase<unknown>)[]`
+
+**Parameters:**
+
+- `Model: E.AnyModelClass`

package/skill/Connection_pruneCommitIds.md

@@ -1,8 +0,0 @@
-#### connection.pruneCommitIds · method
-
-**Signature:** `(request: ActiveRequest, maxCommitId: number) => void`
-
-**Parameters:**
-
-- `request: ActiveRequest`
-- `maxCommitId: number`