tinytsdk 0.2.0

package/README.md

@@ -0,0 +1,130 @@
+# tinytsdk
+
+JavaScript/TypeScript SDK for the [TinyTrack](https://github.com/jetallavache/tiny-track) monitoring system.
+
+## Packages
+
+| Entry point | Contents |
+|-------------|----------|
+| `tinytsdk` | Core WebSocket client + protocol parser (no framework deps) |
+| `tinytsdk/react` | React components + `TinyTrackProvider` context |
+
+## Installation
+
+```bash
+npm install tinytsdk
+```
+
+## Vanilla JS / TypeScript
+
+```ts
+import { TinyTrackClient, RING_L1 } from 'tinytsdk';
+
+const client = new TinyTrackClient('ws://localhost:4026');
+
+client.on('metrics', m => {
+  console.log(`CPU: ${m.cpu / 100}%  MEM: ${m.mem / 100}%`);
+});
+
+client.on('open', () => {
+  // request history from L1 ring (last 60 samples)
+  client.getHistory(RING_L1, 60);
+  // set push interval to 5 seconds
+  client.setInterval(5000);
+});
+
+client.connect();
+```
+
+### CDN (browser)
+
+```html
+<script type="module">
+  import { TinyTrackClient } from 'https://cdn.jsdelivr.net/npm/tinytsdk/dist/index.esm.js';
+  const client = new TinyTrackClient('ws://your-server:4026');
+  client.on('metrics', m => console.log(m));
+  client.connect();
+</script>
+```
+
+## React
+
+```tsx
+import { TinyTrackProvider, useTinyTrack, MetricsPanel } from 'tinytsdk/react';
+
+function App() {
+  return (
+    <TinyTrackProvider url="ws://localhost:4026">
+      <Dashboard />
+    </TinyTrackProvider>
+  );
+}
+
+function Dashboard() {
+  const { metrics, connected } = useTinyTrack();
+  return (
+    <>
+      <p>Status: {connected ? 'connected' : 'disconnected'}</p>
+      <MetricsPanel />
+    </>
+  );
+}
+```
+
+## API
+
+### `TinyTrackClient`
+
+```ts
+const client = new TinyTrackClient(url, options?);
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `reconnect` | boolean | `true` | Auto-reconnect on close |
+| `reconnectDelay` | number | `2000` | Delay between reconnects (ms) |
+| `maxRetries` | number | `0` | Max retries (0 = unlimited) |
+| `path` | string | `'/websocket'` | WebSocket path |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Open WebSocket connection |
+| `disconnect()` | Close connection |
+| `getSnapshot()` | Request current metrics snapshot |
+| `getStats()` | Request ring buffer statistics |
+| `setInterval(ms)` | Change push interval |
+| `getHistory(level, maxCount?, fromTs?, toTs?)` | Request historical data |
+| `subscribe(level, intervalMs?)` | Subscribe to a ring level |
+| `on(event, fn)` / `off(event, fn)` | Add/remove event listener |
+
+**Events:** `open`, `close`, `error`, `metrics`, `config`, `ack`, `stats`, `history`
+
+### Metrics fields (`TtMetrics`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timestamp` | number | ms since epoch |
+| `cpu` | number | CPU usage × 100 (e.g. 5000 = 50%) |
+| `mem` | number | Memory usage × 100 |
+| `netRx` / `netTx` | number | Network bytes/sec |
+| `load1` / `load5` / `load15` | number | Load average × 100 |
+| `nrRunning` / `nrTotal` | number | Process counts |
+| `duUsage` | number | Disk usage × 100 |
+| `duTotal` / `duFree` | number | Disk bytes |
+
+### Ring levels
+
+| Constant | Value | Resolution | Retention |
+|----------|-------|------------|-----------|
+| `RING_L1` | 1 | 1 second | 1 hour |
+| `RING_L2` | 2 | 1 minute | 24 hours |
+| `RING_L3` | 3 | 1 hour | 7 days |
+
+## Development
+
+```bash
+npm test          # run tests
+npm run build     # build dist/
+```

package/dist/client.d.ts

@@ -0,0 +1,58 @@
+/**
+ * TinyTrackClient — WebSocket client for the tinytrack gateway.
+ *
+ * Usage:
+ *   const client = new TinyTrackClient('ws://localhost:4026');
+ *   client.on('metrics', m => console.log(m.cpu / 100, '%'));
+ *   client.connect();
+ */
+import { RING_L1, RING_L2, RING_L3, TtMetrics, TtConfig, TtAck, TtStats, TtHistoryResp, TtSysInfo } from './proto.js';
+export type { TtMetrics, TtConfig, TtAck, TtStats, TtHistoryResp, TtSysInfo };
+export { RING_L1, RING_L2, RING_L3 };
+export type ClientEventMap = {
+    open: [];
+    close: [code: number, reason: string];
+    error: [err: Event];
+    metrics: [m: TtMetrics];
+    config: [c: TtConfig];
+    ack: [a: TtAck];
+    stats: [s: TtStats];
+    history: [r: TtHistoryResp];
+    sysinfo: [s: TtSysInfo];
+};
+type Listener<K extends keyof ClientEventMap> = (...args: ClientEventMap[K]) => void;
+export interface TinyTrackClientOptions {
+    /** Auto-reconnect on close. Default: true */
+    reconnect?: boolean;
+    /** Reconnect delay ms. Default: 2000 */
+    reconnectDelay?: number;
+    /** Max reconnect attempts (0 = unlimited). Default: 0 */
+    maxRetries?: number;
+    /** WebSocket path. Default: '/websocket' */
+    path?: string;
+}
+export declare class TinyTrackClient {
+    private url;
+    private opts;
+    private ws;
+    private listeners;
+    private retries;
+    private _closed;
+    constructor(url: string, opts?: TinyTrackClientOptions);
+    connect(): this;
+    disconnect(): void;
+    get connected(): boolean;
+    getSnapshot(): void;
+    getStats(): void;
+    getSysInfo(): void;
+    setInterval(ms: number): void;
+    start(): void;
+    stop(): void;
+    getHistory(level: number, maxCount?: number, fromTs?: number, toTs?: number): void;
+    subscribe(level: number, intervalMs?: number): void;
+    on<K extends keyof ClientEventMap>(event: K, fn: Listener<K>): this;
+    off<K extends keyof ClientEventMap>(event: K, fn: Listener<K>): this;
+    private _open;
+    private _send;
+    private _emit;
+}

package/dist/index.cjs.js

@@ -0,0 +1,382 @@
+'use strict';
+
+/**
+ * TinyTrack binary protocol parser (v1 + v2).
+ *
+ * Wire format (big-endian):
+ *   [magic:1][version:1][type:1][length:2][timestamp:4][checksum:1] + payload
+ *
+ * tt_metrics payload (52 bytes, little-endian packed struct):
+ *   timestamp:8  cpu:2  mem:2  net_rx:4  net_tx:4
+ *   load1:2  load5:2  load15:2  nr_running:4  nr_total:4
+ *   du_usage:2  du_total:8  du_free:8
+ */
+const PROTO_MAGIC = 0xaa;
+const HEADER_SIZE = 10;
+// Packet types
+const PKT_METRICS = 0x01;
+const PKT_CONFIG = 0x02;
+const PKT_CMD = 0x04;
+const PKT_ACK = 0x05;
+const PKT_HISTORY_REQ = 0x10;
+const PKT_HISTORY_RESP = 0x11;
+const PKT_SUBSCRIBE = 0x12;
+const PKT_RING_STATS = 0x13;
+const PKT_SYS_INFO = 0x14;
+// Ring levels
+const RING_L1 = 0x01;
+const RING_L2 = 0x02;
+const RING_L3 = 0x03;
+// Commands
+const CMD_SET_INTERVAL = 0x01;
+const CMD_GET_SNAPSHOT = 0x03;
+const CMD_GET_RING_STATS = 0x10;
+const CMD_GET_SYS_INFO = 0x11;
+const CMD_START = 0x12;
+const CMD_STOP = 0x13;
+/** Parse the 10-byte header. Returns null if buffer is too short or magic is wrong. */
+function parseHeader(buf, offset = 0) {
+    if (buf.byteLength - offset < HEADER_SIZE)
+        return null;
+    const v = new DataView(buf, offset);
+    if (v.getUint8(0) !== PROTO_MAGIC)
+        return null;
+    const version = v.getUint8(1);
+    const type = v.getUint8(2);
+    const length = v.getUint16(3, false); // big-endian
+    const timestamp = v.getUint32(5, false);
+    if (buf.byteLength - offset < HEADER_SIZE + length)
+        return null;
+    return {
+        type,
+        version,
+        timestamp,
+        payload: new DataView(buf, offset + HEADER_SIZE, length),
+    };
+}
+/** Parse PKT_METRICS payload (52 bytes, little-endian). */
+function parseMetrics(p) {
+    // uint64 LE: lo word at offset 0, hi word at offset 4
+    const tsLo = p.getUint32(0, true);
+    const tsHi = p.getUint32(4, true);
+    const timestamp = tsHi * 0x100000000 + tsLo;
+    return {
+        timestamp,
+        cpu: p.getUint16(8, true),
+        mem: p.getUint16(10, true),
+        netRx: p.getUint32(12, true),
+        netTx: p.getUint32(16, true),
+        load1: p.getUint16(20, true),
+        load5: p.getUint16(22, true),
+        load15: p.getUint16(24, true),
+        nrRunning: p.getUint32(26, true),
+        nrTotal: p.getUint32(30, true),
+        duUsage: p.getUint16(34, true),
+        duTotal: readUint64LE(p, 36),
+        duFree: readUint64LE(p, 44),
+    };
+}
+/** Parse PKT_CONFIG payload (5 bytes). */
+function parseConfig(p) {
+    return {
+        intervalMs: p.getUint32(0, false),
+        alertsEnabled: p.getUint8(4) !== 0,
+    };
+}
+/** Parse PKT_ACK payload (2 bytes). */
+function parseAck(p) {
+    return { cmdType: p.getUint8(0), status: p.getUint8(1) };
+}
+/** Parse PKT_STATS payload (75 bytes = 3 × 25). */
+function parseStats(p) {
+    return {
+        l1: parseRingStat(p, 0),
+        l2: parseRingStat(p, 29),
+        l3: parseRingStat(p, 58),
+    };
+}
+/** Parse PKT_HISTORY_RESP payload. */
+function parseHistoryResp(p) {
+    const level = p.getUint8(0);
+    const count = p.getUint16(1, false);
+    const flags = p.getUint8(3);
+    const samples = [];
+    for (let i = 0; i < count; i++) {
+        const off = 4 + i * 52;
+        samples.push(parseMetrics(new DataView(p.buffer, p.byteOffset + off, 52)));
+    }
+    return { level, count, last: (flags & 0x01) !== 0, samples };
+}
+/** Parse PKT_SYS_INFO payload (168 bytes). */
+function parseSysInfo(p) {
+    const dec = new TextDecoder();
+    const hostname = dec.decode(new Uint8Array(p.buffer, p.byteOffset, 64)).replace(/\0.*/, '');
+    const osType = dec.decode(new Uint8Array(p.buffer, p.byteOffset + 64, 64)).replace(/\0.*/, '');
+    return {
+        hostname,
+        osType,
+        uptimeSec: readUint64BE(p, 128), // server: htobe64
+        slotsL1: p.getUint32(136, false), // server: htonl (BE)
+        slotsL2: p.getUint32(140, false),
+        slotsL3: p.getUint32(144, false),
+        intervalMs: p.getUint32(148, false),
+        aggL2Ms: p.getUint32(152, false),
+        aggL3Ms: p.getUint32(156, false),
+    };
+}
+// ---------------------------------------------------------------------------
+// Command builders
+// ---------------------------------------------------------------------------
+function buildCmd(cmdType, arg = 0) {
+    const buf = new ArrayBuffer(HEADER_SIZE + 9);
+    const h = new DataView(buf);
+    const ts = Math.floor(Date.now() / 1000);
+    h.setUint8(0, PROTO_MAGIC);
+    h.setUint8(1, 0x01); // v1
+    h.setUint8(2, PKT_CMD);
+    h.setUint16(3, 9, false);
+    h.setUint32(5, ts, false);
+    h.setUint8(9, calcChecksum(h));
+    // payload
+    h.setUint8(10, cmdType);
+    h.setUint32(11, arg, false);
+    return buf;
+}
+function buildHistoryReq(level, maxCount = 0, fromTs = 0, toTs = 0) {
+    const buf = new ArrayBuffer(HEADER_SIZE + 19);
+    const h = new DataView(buf);
+    const ts = Math.floor(Date.now() / 1000);
+    h.setUint8(0, PROTO_MAGIC);
+    h.setUint8(1, 0x02); // v2
+    h.setUint8(2, PKT_HISTORY_REQ);
+    h.setUint16(3, 19, false);
+    h.setUint32(5, ts, false);
+    h.setUint8(9, calcChecksum(h));
+    // payload: level(1) from_ts(8) to_ts(8) max_count(2)
+    h.setUint8(10, level);
+    writeUint64BE(h, 11, fromTs);
+    writeUint64BE(h, 19, toTs);
+    h.setUint16(27, maxCount, false);
+    return buf;
+}
+function buildSubscribe(level, intervalMs = 0) {
+    const buf = new ArrayBuffer(HEADER_SIZE + 6);
+    const h = new DataView(buf);
+    const ts = Math.floor(Date.now() / 1000);
+    h.setUint8(0, PROTO_MAGIC);
+    h.setUint8(1, 0x02);
+    h.setUint8(2, PKT_SUBSCRIBE);
+    h.setUint16(3, 6, false);
+    h.setUint32(5, ts, false);
+    h.setUint8(9, calcChecksum(h));
+    h.setUint8(10, level);
+    h.setUint32(11, intervalMs, false);
+    h.setUint8(15, 0);
+    return buf;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function calcChecksum(h) {
+    let cs = 0;
+    for (let i = 0; i < 9; i++)
+        cs ^= h.getUint8(i);
+    return cs;
+}
+function parseRingStat(p, off) {
+    return {
+        level: p.getUint8(off),
+        capacity: p.getUint32(off + 1, false), // htonl (BE)
+        head: p.getUint32(off + 5, false), // htonl (BE)
+        filled: p.getUint32(off + 9, false), // htonl (BE)
+        firstTs: readUint64LE(p, off + 13), // no hton, native LE
+        lastTs: readUint64LE(p, off + 21), // no hton, native LE
+    };
+}
+function readUint64LE(v, off) {
+    const lo = v.getUint32(off, true);
+    const hi = v.getUint32(off + 4, true);
+    return hi * 0x100000000 + lo;
+}
+function readUint64BE(v, off) {
+    const hi = v.getUint32(off, false);
+    const lo = v.getUint32(off + 4, false);
+    return hi * 0x100000000 + lo;
+}
+function writeUint64BE(v, off, val) {
+    const hi = Math.floor(val / 0x100000000);
+    const lo = val >>> 0;
+    v.setUint32(off, hi, false);
+    v.setUint32(off + 4, lo, false);
+}
+
+/**
+ * TinyTrackClient — WebSocket client for the tinytrack gateway.
+ *
+ * Usage:
+ *   const client = new TinyTrackClient('ws://localhost:4026');
+ *   client.on('metrics', m => console.log(m.cpu / 100, '%'));
+ *   client.connect();
+ */
+class TinyTrackClient {
+    constructor(url, opts = {}) {
+        var _a, _b, _c, _d;
+        this.ws = null;
+        this.listeners = new Map();
+        this.retries = 0;
+        this._closed = false;
+        // Normalise: strip trailing path, we'll append opts.path
+        this.url = url.replace(/\/websocket\/?$/, '');
+        this.opts = {
+            reconnect: (_a = opts.reconnect) !== null && _a !== void 0 ? _a : true,
+            reconnectDelay: (_b = opts.reconnectDelay) !== null && _b !== void 0 ? _b : 2000,
+            maxRetries: (_c = opts.maxRetries) !== null && _c !== void 0 ? _c : 0,
+            path: (_d = opts.path) !== null && _d !== void 0 ? _d : '/websocket',
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    connect() {
+        this._closed = false;
+        this._open();
+        return this;
+    }
+    disconnect() {
+        var _a;
+        this._closed = true;
+        (_a = this.ws) === null || _a === void 0 ? void 0 : _a.close();
+        this.ws = null;
+    }
+    get connected() {
+        var _a;
+        return ((_a = this.ws) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN;
+    }
+    // ---------------------------------------------------------------------------
+    // Commands
+    // ---------------------------------------------------------------------------
+    getSnapshot() {
+        this._send(buildCmd(CMD_GET_SNAPSHOT));
+    }
+    getStats() {
+        this._send(buildCmd(CMD_GET_RING_STATS));
+    }
+    getSysInfo() {
+        this._send(buildCmd(CMD_GET_SYS_INFO));
+    }
+    setInterval(ms) {
+        this._send(buildCmd(CMD_SET_INTERVAL, ms));
+    }
+    start() {
+        this._send(buildCmd(CMD_START));
+    }
+    stop() {
+        this._send(buildCmd(CMD_STOP));
+    }
+    getHistory(level, maxCount = 60, fromTs = 0, toTs = 0) {
+        this._send(buildHistoryReq(level, maxCount, fromTs, toTs));
+    }
+    subscribe(level, intervalMs = 0) {
+        this._send(buildSubscribe(level, intervalMs));
+    }
+    // ---------------------------------------------------------------------------
+    // Events
+    // ---------------------------------------------------------------------------
+    on(event, fn) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        this.listeners.get(event).add(fn);
+        return this;
+    }
+    off(event, fn) {
+        var _a;
+        (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.delete(fn);
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    _open() {
+        const wsUrl = this.url + this.opts.path;
+        const ws = new WebSocket(wsUrl);
+        ws.binaryType = 'arraybuffer';
+        this.ws = ws;
+        ws.onopen = () => {
+            this.retries = 0;
+            this._emit('open');
+        };
+        ws.onclose = (e) => {
+            this._emit('close', e.code, e.reason);
+            if (!this._closed && this.opts.reconnect) {
+                const max = this.opts.maxRetries;
+                if (max === 0 || this.retries < max) {
+                    this.retries++;
+                    setTimeout(() => this._open(), this.opts.reconnectDelay);
+                }
+            }
+        };
+        ws.onerror = (e) => this._emit('error', e);
+        ws.onmessage = (e) => {
+            const frame = parseHeader(e.data);
+            if (!frame)
+                return;
+            switch (frame.type) {
+                case PKT_METRICS:
+                    this._emit('metrics', parseMetrics(frame.payload));
+                    break;
+                case PKT_CONFIG:
+                    this._emit('config', parseConfig(frame.payload));
+                    break;
+                case PKT_ACK:
+                    this._emit('ack', parseAck(frame.payload));
+                    break;
+                case PKT_RING_STATS:
+                    this._emit('stats', parseStats(frame.payload));
+                    break;
+                case PKT_HISTORY_RESP:
+                    this._emit('history', parseHistoryResp(frame.payload));
+                    break;
+                case PKT_SYS_INFO:
+                    this._emit('sysinfo', parseSysInfo(frame.payload));
+                    break;
+            }
+        };
+    }
+    _send(buf) {
+        var _a;
+        if (((_a = this.ws) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN) {
+            this.ws.send(buf);
+        }
+    }
+    _emit(event, ...args) {
+        var _a;
+        (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.forEach((fn) => fn(...args));
+    }
+}
+
+exports.CMD_GET_RING_STATS = CMD_GET_RING_STATS;
+exports.CMD_GET_SNAPSHOT = CMD_GET_SNAPSHOT;
+exports.CMD_GET_SYS_INFO = CMD_GET_SYS_INFO;
+exports.CMD_SET_INTERVAL = CMD_SET_INTERVAL;
+exports.CMD_START = CMD_START;
+exports.CMD_STOP = CMD_STOP;
+exports.PKT_ACK = PKT_ACK;
+exports.PKT_CONFIG = PKT_CONFIG;
+exports.PKT_HISTORY_RESP = PKT_HISTORY_RESP;
+exports.PKT_METRICS = PKT_METRICS;
+exports.PKT_RING_STATS = PKT_RING_STATS;
+exports.PKT_SYS_INFO = PKT_SYS_INFO;
+exports.RING_L1 = RING_L1;
+exports.RING_L2 = RING_L2;
+exports.RING_L3 = RING_L3;
+exports.TinyTrackClient = TinyTrackClient;
+exports.buildCmd = buildCmd;
+exports.buildHistoryReq = buildHistoryReq;
+exports.buildSubscribe = buildSubscribe;
+exports.parseAck = parseAck;
+exports.parseConfig = parseConfig;
+exports.parseHeader = parseHeader;
+exports.parseHistoryResp = parseHistoryResp;
+exports.parseMetrics = parseMetrics;
+exports.parseStats = parseStats;
+exports.parseSysInfo = parseSysInfo;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { TinyTrackClient } from './client.js';
+export type { TinyTrackClientOptions, ClientEventMap } from './client.js';
+export type { TtMetrics, TtConfig, TtAck, TtStats, TtHistoryResp, TtSysInfo } from './client.js';
+export { RING_L1, RING_L2, RING_L3, PKT_METRICS, PKT_CONFIG, PKT_ACK, PKT_RING_STATS, PKT_HISTORY_RESP, PKT_SYS_INFO, CMD_GET_SNAPSHOT, CMD_GET_RING_STATS, CMD_GET_SYS_INFO, CMD_SET_INTERVAL, CMD_START, CMD_STOP, buildCmd, buildHistoryReq, buildSubscribe, parseHeader, parseMetrics, parseConfig, parseAck, parseStats, parseHistoryResp, parseSysInfo, } from './proto.js';