rosefc 0.0.0-stage → 0.2.0

package/src/runtime/lorawan.ts

@@ -0,0 +1,149 @@
+// LoRaWAN PHYPayload parser (v1.0.x / v1.1 on the wire, structural).
+//
+// Zero-dependency, Buffer-free (Uint8Array + DataView only) so the same module
+// is safe in the browser bundle and in a prerender - it reads bytes, never
+// touches the network or a key. The FRMPayload of a data frame is
+// application-encrypted (AES-128 with AppSKey); this module returns it raw -
+// decrypting is the app's business, because the key is the app's secret.
+//
+//   PHYPayload = MHDR(1) | MACPayload | MIC(4)
+//   data frame MACPayload = DevAddr(4,LE) FCtrl(1) FCnt(2,LE) FOpts(0-15) [FPort(1)] FRMPayload
+
+export type LoRaWANMessageType =
+  | 'join-request'
+  | 'join-accept'
+  | 'unconfirmed-data-up'
+  | 'unconfirmed-data-down'
+  | 'confirmed-data-up'
+  | 'confirmed-data-down'
+  | 'proprietary';
+
+export interface LoRaWANDataFrame {
+  kind: 'data';
+  mtype: LoRaWANMessageType;
+  major: 0 | 1;
+  devAddr: string; // 8 hex chars, the little-endian word as LoRaWAN prints it
+  fctrl: { adr: boolean; adrAckReq: boolean; ack: boolean; classB: boolean; fOptsLen: number };
+  fCnt: number;
+  fOpts: Uint8Array | null;
+  fPort: number | null; // null when the frame carries no port byte
+  frmPayload: Uint8Array | null; // still encrypted; null when absent
+  mic: Uint8Array;
+}
+
+export interface LoRaWANJoinRequest {
+  kind: 'join-request';
+  major: 0 | 1;
+  appEUI: string; // 16 hex chars
+  devEUI: string; // 16 hex chars
+  devNonce: number;
+  mic: Uint8Array;
+}
+
+export interface LoRaWANJoinAccept {
+  kind: 'join-accept';
+  major: 0 | 1;
+  appNonce: string; // 6 hex chars
+  netID: string; // 6 hex chars
+  devAddr: string; // 8 hex chars
+  mic: Uint8Array;
+}
+
+export type LoRaWANFrame = LoRaWANDataFrame | LoRaWANJoinRequest | LoRaWANJoinAccept;
+
+const MTYPES: Record<number, LoRaWANMessageType> = {
+  0: 'join-request',
+  1: 'join-accept',
+  2: 'unconfirmed-data-up',
+  3: 'unconfirmed-data-down',
+  4: 'confirmed-data-up',
+  5: 'confirmed-data-down',
+  6: 'proprietary',
+  7: 'proprietary',
+};
+
+const HEX = '0123456789ABCDEF';
+function hex(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i++) {
+    out += HEX[bytes[i] >> 4] + HEX[bytes[i] & 0x0f];
+  }
+  return out;
+}
+
+/**
+ * Parse a LoRaWAN PHYPayload. Returns null for anything that is not a
+ * well-formed frame (too short for its own headers, a truncated MIC).
+ * Throws nothing - a gateway loop must never die on one bad datagram.
+ */
+export function parseLoRaWAN(frame: Uint8Array): LoRaWANFrame | null {
+  if (!frame || frame.length < 5) return null;
+  const mhdr = frame[0];
+  const mtype = MTYPES[(mhdr >> 5) & 0x07];
+  const major = (mhdr & 0x03) as 0 | 1;
+  if (major > 1) return null;
+  const body = frame.subarray(1, frame.length - 4);
+  const mic = frame.subarray(frame.length - 4);
+  if (body.length < 1) return null;
+  const dv = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+
+  if (mtype === 'join-request') {
+    if (body.length !== 18) return null;
+    return {
+      kind: 'join-request',
+      major,
+      appEUI: hex(body.subarray(0, 8)),
+      devEUI: hex(body.subarray(8, 16)),
+      devNonce: dv.getUint16(17, true),
+      mic,
+    };
+  }
+
+  if (mtype === 'join-accept') {
+    if (body.length < 12) return null;
+    return {
+      kind: 'join-accept',
+      major,
+      appNonce: hex(body.subarray(0, 3)),
+      netID: hex(body.subarray(3, 6)),
+      devAddr: hex(body.subarray(6, 10)),
+      mic,
+    };
+  }
+
+  // data frames (up/down, confirmed or not)
+  if (body.length < 7) return null;
+  const devAddr = hex(body.subarray(0, 4));
+  const fctrlB = body[4];
+  const fOptsLen = fctrlB & 0x0f;
+  const fCnt = dv.getUint16(6, true);
+  let p = 7;
+  if (p + fOptsLen > body.length) return null;
+  const fOpts = fOptsLen > 0 ? body.subarray(p, p + fOptsLen) : null;
+  p += fOptsLen;
+  let fPort: number | null = null;
+  let frmPayload: Uint8Array | null = null;
+  if (p < body.length) {
+    fPort = body[p];
+    p += 1;
+    if (p < body.length) frmPayload = body.subarray(p);
+  }
+  return {
+    kind: 'data',
+    mtype,
+    major,
+    devAddr,
+    fctrl: {
+      adr: (fctrlB & 0x80) !== 0,
+      adrAckReq: (fctrlB & 0x40) !== 0,
+      ack: (fctrlB & 0x20) !== 0,
+      classB: (fctrlB & 0x10) !== 0,
+      fOptsLen,
+    },
+    fCnt,
+    fOpts,
+    fPort,
+    frmPayload,
+    mic,
+  };
+}

package/src/types/rosefd.d.ts

@@ -0,0 +1,327 @@
+
+/// <reference lib="dom" />
+/// <reference types="node" />
+type Getter<T> = () => T;
+
+/** A store shared by every request in this process (and, with a transport, every worker). */
+interface Store<T> {
+  get(): T;
+  set(v: T): void;
+  update(fn: (v: T) => T): void;
+}
+
+/** Declare reactive state. Server-rendered into the document, resumed by the client with zero hydration. */
+declare function $state<T>(initial: T): Getter<T>;
+
+/** Write reactive state by key - the same write the generated setter performs. */
+declare function $setState<T>(key: string, value: T): void;
+
+/**
+ * Computed state: compiles to a plain getter over the signals the expression
+ * reads, so every read recomputes - no subscription machinery, never
+ * serialized. Top-level declarations only. The expression is Rosefd syntax
+ * (bare state reads are callified at compile time), so it checks as `any`.
+ */
+declare function $derived(expr: any): Getter<any>;
+
+/** Like $state, but every write mirrors to localStorage (JSON, `rosefd:` prefix) and boot re-seeds from it. */
+declare function $persist<T>(initial: T): Getter<T>;
+
+/**
+ * Declaration form: `let x = $kv(() => expensive(), 60)`. The compiler turns
+ * it into seeded $state backed by the server-side memo - the value arrives
+ * with the first render and every request inside the TTL shares one compute.
+ */
+declare function $kv<T>(compute: () => T | Promise<T>, ttlSeconds?: number): Getter<T>;
+
+
+declare function $data<T>(fn: () => T | Promise<T>): Getter<T>;
+
+/** The per-request bag filled by `pages/_middleware.rose` (auth, db, cache). */
+declare function getContext<T = Record<string, unknown>>(): T;
+
+// The parsed query string of the request being rendered (`?page=2&q=x` -> `{ page: '2', q: 'x' }`).
+declare function $query(): Record<string, string>;
+
+
+declare function $t(key: string, vars?: Record<string, string | number>): string;
+
+/** 'rtl' for a right-to-left locale (ar, he, fa, ur, ...), 'ltr' otherwise. */
+declare function localeDir(lang: string): string;
+
+
+declare function ensureLocale(lang: string): Promise<void>;
+
+/** Merge a dictionary that arrived at runtime (a fetched pack, or your own import()). */
+declare function loadLocale(lang: string, dict: Record<string, string>): void;
+
+/** A named, process-wide store. Values must be JSON-serializable. */
+declare function $store<T>(name: string, initial: T): Store<T>;
+
+/** Parse the request's cookies (server) or this document's (client). */
+declare function $cookies(request?: Request): Record<string, string>;
+
+/** Build a Set-Cookie value with the safe defaults: HttpOnly, SameSite=Lax, Path=/, 7 days. */
+declare function $sessionCookie(
+  name: string,
+  value: string,
+  opts?: { path?: string; maxAge?: number; sameSite?: 'Strict' | 'Lax' | 'None'; secure?: boolean; httpOnly?: boolean }
+): string;
+
+/** Run once after the client has adopted the server's DOM. */
+declare function onMount(fn: () => void): void;
+
+/** Register a teardown for the next navigation. */
+declare function onCleanup(fn: () => void): void;
+
+declare function $effect(fn: () => void | (() => void)): () => void;
+
+/** Re-render the current route in place - `$data` re-runs, zero requests. */
+declare function refresh(): Promise<void>;
+
+/** HTML-escape a value into a string (the same escape the template markers use). */
+declare function esc(v: unknown): string;
+
+/** Call a server action by name; the response is adopted in place. */
+declare function $action(name: string, e?: Event): Promise<void>;
+
+
+declare class ActionError extends Error {
+  code: number;
+  field?: string;
+  constructor(message: string, code?: number, field?: string);
+}
+
+/** What the dispatch seeds into state when an action fails (what `$actionError()` returns). */
+interface ActionErrorInfo {
+  action: string;
+  message: string;
+  code: number;
+  field?: string;
+}
+
+// The failure of the action that produced the response being rendered, or null.
+declare function $actionError(): ActionErrorInfo | null;
+
+// An incremental patch: an action's return value may map a state key to an OPERATION instead of a whole replacement.
+declare function $append(value: unknown): unknown;
+declare function $prepend(value: unknown): unknown;
+declare function $merge(value: Record<string, unknown>): unknown;
+
+/** Whether a state key already holds a value (what `$data` checks before fetching). */
+declare function hasState(key: string): boolean;
+
+/** The best dictionary for an Accept-Language header (null when none matches). */
+declare function bestLocale(header: string | null | undefined): string | null;
+
+// === Globals the compiler injects when a route uses them ===
+// These live on globalThis in the built bundle; declaring them here keeps
+// `rosefd check` honest about code that reaches for them directly.
+
+declare var __rosefdAuth: {
+  hashPassword(pw: string): string;
+  verifyPassword(pw: string, hash: string): boolean;
+  signSession(data: Record<string, unknown>, secret: string, ttlSeconds?: number): string;
+  verifySession<T = Record<string, unknown>>(token: string, secret: string): T | null;
+  csrfToken(secret: string, sessionId: string): string;
+  verifyCsrf(token: string, secret: string, sessionId: string): boolean;
+};
+
+declare var __rosefdKvApi: {
+  kv: {
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttlSeconds?: number): void;
+    del(key: string): void;
+    has(key: string): boolean;
+  };
+  kvMemo: typeof $kv;
+};
+
+interface RosefdContentEntry {
+  slug: string;
+  title?: string;
+  date?: string;
+  tags?: string[];
+  excerpt?: string;
+  body: string;
+  html?: string;
+  toc?: unknown[];
+  readingTime?: number;
+  wordCount?: number;
+  [key: string]: unknown;
+}
+
+declare var __rosefdContent: {
+  list(coll: string, filter?: { tag: string }): Array<Record<string, unknown>>;
+  rss(coll: string, opts: { title: string; origin: string; description: string }): string;
+  get(coll: string, slug: string, vars?: Record<string, string>): RosefdContentEntry | null;
+};
+
+declare var __rosefdExtras: {
+  v: {
+    validate(body: Record<string, unknown>, rules: Record<string, string[]>): {
+      ok: boolean;
+      errors: Record<string, string>;
+      values: Record<string, unknown>;
+    };
+  };
+};
+
+/** Named view transitions: `globalThis.__rosefdTransitions.pulse = (el, ms) => () => {}` - used by `transition:pulse` in templates. */
+declare var __rosefdTransitions: Record<string, (el: HTMLElement, duration: number) => () => void>;
+
+
+declare function redirect(path: string, status?: 301 | 302 | 303 | 307 | 308): never;
+
+
+declare function notFound(): never;
+
+// === Network listeners (isomorphic) ===
+// On the server these open real sockets when the serve worker boots
+// (`__startNetwork`); on the client every handle is an inert no-op, so a page
+// that opens a listener hydrates without a ReferenceError.
+
+/** The sender of a UDP datagram (what `rinfo` carries in `onMessage`). */
+interface RemoteInfo {
+  address: string;
+  family: string;
+  port: number;
+  size: number;
+}
+
+interface UDPSocket {
+  send(msg: Buffer, port: number, host?: string): void;
+  close(): void;
+  address(): { port: number; host: string; family: string };
+  joinMulticast(multicastAddress: string): void;
+  leaveMulticast(multicastAddress: string): void;
+}
+
+/**
+ * Listen for UDP datagrams (LoRa gateways, sensor feeds) from inside a Rosefd
+ * app. Only registers the spec; the framework binds it at serve-worker boot, so
+ * a build/prerender never opens a socket.
+ */
+declare function $udp(
+  port: number,
+  opts?: {
+    host?: string;
+    onMessage?: (msg: Buffer, rinfo: RemoteInfo) => void;
+    onError?: (err: Error) => void;
+  }
+): UDPSocket;
+
+interface TCPsocket {
+  write(data: string | Buffer): void;
+  end(data?: string | Buffer): void;
+  destroy(): void;
+  on(event: 'data', fn: (data: Buffer) => void): void;
+  on(event: 'close', fn: () => void): void;
+  on(event: 'error', fn: (err: Error) => void): void;
+  readonly remoteAddress?: string;
+}
+
+interface TCPServer {
+  close(): void;
+  address(): { port: number; host: string };
+}
+
+/**
+ * A TCP server (a number, or opts with onConnection) or a TCP client (a host
+ * string, or opts with onConnect). Same register-at-boot discipline as $udp.
+ */
+declare function $tcp(
+  portOrHost: number | string,
+  opts?: {
+    port?: number;
+    host?: string;
+    idleTimeout?: number;
+    onConnection?: (socket: TCPsocket) => void;
+    onData?: (socket: TCPsocket, data: Buffer) => void;
+    onIdle?: (socket: TCPsocket) => void;
+    onConnect?: () => void;
+    onClose?: () => void;
+    onError?: (err: Error) => void;
+  }
+): TCPServer | TCPsocket;
+
+interface Listener {
+  close(): void;
+  address(): { port: number; host: string };
+}
+
+/** General-port listener: protocol 'http' | 'websocket' | 'udp' | 'tcp' (default 'http'). */
+declare function $listen(
+  port: number,
+  opts?: {
+    protocol?: 'http' | 'websocket' | 'udp' | 'tcp';
+    host?: string;
+    onConnection?: (socket: unknown) => void;
+    onData?: (data: Buffer, remote: unknown) => void;
+  }
+): Listener;
+
+/** One connection served by a `$websocket` server. */
+interface WebSocket {
+  send(data: string | Buffer): void;
+  close(): void;
+  on(event: 'message', fn: (data: string | Buffer) => void): void;
+  on(event: 'close', fn: () => void): void;
+  on(event: 'error', fn: (err: Error) => void): void;
+  readonly remoteAddress?: string;
+}
+
+interface WebSocketServer {
+  close(): void;
+  clients(): WebSocket[];
+  broadcast(data: string | Buffer): void;
+}
+
+/**
+ * A zero-dependency RFC 6455 WebSocket server on its own port. The returned
+ * facade stays live: broadcast()/close() reach the bound server whenever the
+ * app calls them (on the client the facade is an inert no-op).
+ */
+declare function $websocket(
+  port: number,
+  opts?: {
+    host?: string;
+    path?: string;
+    pingInterval?: number;
+    onConnection?: (ws: WebSocket) => void;
+    onMessage?: (ws: WebSocket, data: string | Buffer) => void;
+    onClose?: (ws: WebSocket) => void;
+    onError?: (err: Error) => void;
+  }
+): WebSocketServer;
+
+interface MQTTClient {
+  connect(): Promise<void>;
+  disconnect(): void;
+  subscribe(topic: string, opts?: { qos?: 0 | 1 | 2 }): void;
+  unsubscribe(topic: string): void;
+  publish(topic: string, message: string | Buffer, opts?: { qos?: 0 | 1 | 2; retain?: boolean }): void;
+  readonly connected: boolean;
+}
+
+/**
+ * A zero-dependency MQTT 3.1.1 client (QoS 0/1). `broker` is a URL like
+ * `mqtt://localhost:1883`. Packets sent before CONNACK queue and flush on
+ * connect. On the client the facade is an inert no-op.
+ */
+declare function $mqtt(
+  broker: string,
+  opts?: {
+    clientId?: string;
+    username?: string;
+    password?: string;
+    keepalive?: number;
+    clean?: boolean;
+    reconnect?: boolean;
+    reconnectDelay?: number;
+    reconnectMax?: number;
+    onConnect?: () => void;
+    onMessage?: (topic: string, message: Buffer) => void;
+    onError?: (err: Error) => void;
+  }
+): MQTTClient;

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.