de-shell 0.3.0__tar.gz → 0.4.0__tar.gz

{de_shell-0.3.0 → de_shell-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: de-shell
-Version: 0.3.0
+Version: 0.4.0
 Summary: The Electron + Python desktop-app shell Direct Electron's apps (SpyDE, Ground Crew, Autopilot) are assembled from
 Author-email: Carter Francis <cartsfrancis@gmail.com>
 License: MIT

{de_shell-0.3.0 → de_shell-0.4.0}/de_shell/__init__.py

@@ -20,6 +20,6 @@ from __future__ import annotations
 
 #: The package version — the one place it is written. pyproject.toml reads it
 #: (dynamic version) and the release workflow refuses a tag that disagrees.
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = ["ipc", "log_stream", "process_guard", "debug_flags", "compute"]

de_shell-0.4.0/de_shell/js/main/framing.test.ts

@@ -0,0 +1,125 @@
+/**
+ * framing.test.ts — the encoders against the existing demuxer: whatever
+ * framing.ts writes, stdoutDemux.ts must read back unchanged, whole or split
+ * one byte at a time.
+ *
+ * Run: `node --test de_shell/js/main/framing.test.ts`, or via `npm run test:unit`.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { encodeBinary, encodeMessage } from './framing.ts'
+import { createStdoutDemux } from './stdoutDemux.ts'
+
+type Event =
+  | { kind: 'message'; msg: Record<string, unknown> }
+  | { kind: 'stream'; text: string }
+  | { kind: 'binary'; header: Record<string, unknown>; payload: string }
+
+/** Feed `stream` to a fresh demuxer in `step`-byte slices; return the event trace. */
+function decode(stream: Buffer, step = stream.length || 1): Event[] {
+  const events: Event[] = []
+  const demux = createStdoutDemux({
+    onMessage: (msg) => events.push({ kind: 'message', msg }),
+    onStream: (text) => events.push({ kind: 'stream', text }),
+    onBinary: (header, payload) =>
+      events.push({ kind: 'binary', header, payload: payload.toString('hex') }),
+  })
+  for (let pos = 0; pos < stream.length; pos += step) {
+    demux.push(stream.subarray(pos, pos + step))
+  }
+  return events
+}
+
+/** A whole binary frame as it goes on the wire: prefix, header, then the caller's payload. */
+function frame(header: Record<string, unknown>, payload: Buffer): Buffer {
+  return Buffer.concat([...encodeBinary(header, payload), payload])
+}
+
+function patternPayload(n: number): Buffer {
+  const p = Buffer.allocUnsafe(n)
+  for (let i = 0; i < n; i++) p[i] = i & 0xff // includes 0x0a bytes
+  return p
+}
+
+test('a message is one PLOTAPP line and decodes to the same object', () => {
+  const msg = { type: 'state_update', key: 'clim', value: [0, 255], nested: { ok: true, none: null } }
+  const bytes = encodeMessage(msg)
+  assert.equal(bytes.subarray(0, 8).toString('ascii'), 'PLOTAPP:')
+  assert.equal(bytes.indexOf(0x0a), bytes.length - 1, 'exactly one newline, at the end')
+  assert.deepEqual(decode(bytes), [{ kind: 'message', msg }])
+})
+
+test('a newline inside a string stays escaped, so the message is still one line', () => {
+  const msg = { type: 'status', text: 'line one\nline two\r\n' }
+  const bytes = encodeMessage(msg)
+  assert.equal(bytes.indexOf(0x0a), bytes.length - 1)
+  assert.deepEqual(decode(bytes), [{ kind: 'message', msg }])
+})
+
+test('a frame with an empty payload decodes with an empty payload', () => {
+  assert.deepEqual(decode(frame({ fig_id: 'f3', key: 'spec' }, Buffer.alloc(0))), [
+    { kind: 'binary', header: { fig_id: 'f3', key: 'spec' }, payload: '' },
+  ])
+})
+
+test('a payload holding newlines and PLOTBIN:/PLOTAPP: lookalikes decodes whole, at any chunking', () => {
+  const nasty = Buffer.concat([
+    Buffer.from('\nPLOTBIN:9:9\nPLOTAPP:{}\n', 'ascii'),
+    patternPayload(3000),
+  ])
+  const stream = Buffer.concat([
+    frame({ fig_id: 'f1', key: 'image' }, nasty),
+    encodeMessage({ type: 'done' }),
+  ])
+  const expected: Event[] = [
+    { kind: 'binary', header: { fig_id: 'f1', key: 'image' }, payload: nasty.toString('hex') },
+    { kind: 'message', msg: { type: 'done' } },
+  ]
+  for (const step of [stream.length, 65536, 7, 1]) {
+    assert.deepEqual(decode(stream, step), expected, `diverged at ${step}-byte chunks`)
+  }
+})
+
+test('a non-ASCII header: hlen counts UTF-8 bytes, not characters', () => {
+  const header = { fig_id: 'f', key: 'k', label: 'εxx Å' }
+  const [prefix, head] = encodeBinary(header, Buffer.from([1, 2, 3]))
+  const json = JSON.stringify(header)
+  assert.notEqual(Buffer.byteLength(json, 'utf8'), json.length, 'the fixture must be multi-byte')
+  assert.equal(prefix.toString('ascii'), `PLOTBIN:${Buffer.byteLength(json, 'utf8')}:3\n`)
+  assert.equal(head.toString('utf8'), json)
+  assert.deepEqual(decode(frame(header, Buffer.from([1, 2, 3])), 1), [
+    { kind: 'binary', header, payload: '010203' },
+  ])
+})
+
+test('encodeBinary returns the prefix and header only; the payload is never copied', () => {
+  const payload = patternPayload(64)
+  const parts = encodeBinary({ fig_id: 'f', key: 'k' }, payload)
+  assert.equal(parts.length, 2)
+  assert.ok(!parts.includes(payload))
+  assert.match(parts[0].toString('ascii'), /^PLOTBIN:\d+:64\n$/)
+})
+
+test('the layout is the documented wire format, byte for byte', () => {
+  // PLOTBIN:<hlen>:<plen>\n<header json><payload>, as anyplotlib's
+  // _binary_frame.encode_frame writes it and stdoutDemux.ts parses it.
+  const header = { fig_id: 'f', key: 'k', dims: [2, 2] }
+  const payload = Buffer.from([0, 10, 255, 10])
+  const json = JSON.stringify(header)
+  assert.deepEqual(frame(header, payload), Buffer.concat([
+    Buffer.from(`PLOTBIN:${Buffer.byteLength(json)}:4\n${json}`, 'utf8'),
+    payload,
+  ]))
+  assert.deepEqual(encodeMessage({ type: 'done' }), Buffer.from('PLOTAPP:{"type":"done"}\n', 'utf8'))
+})
+
+test('a non-finite number is refused rather than framed', () => {
+  for (const bad of [NaN, Infinity, -Infinity]) {
+    assert.throws(() => encodeMessage({ type: 'fit', value: bad }), RangeError)
+    assert.throws(
+      () => encodeBinary({ fig_id: 'f', key: 'k', clim: [0, bad] }, Buffer.alloc(0)),
+      RangeError,
+    )
+  }
+  assert.throws(() => encodeMessage({ a: { b: [1, NaN] } }), /non-finite/)
+})

de_shell-0.4.0/de_shell/js/main/framing.ts

@@ -0,0 +1,34 @@
+/**
+ * framing.ts — encoders for the backend wire format; the inverse of
+ * stdoutDemux.ts.
+ *
+ *   PLOTAPP:<json>\n                                  a message
+ *   PLOTBIN:<hlen>:<plen>\n<header json><payload>     a binary frame
+ *
+ * The layout ipc.emit and anyplotlib's _binary_frame.encode_frame write on the
+ * Python side. hlen and plen are byte counts. The JSON text is JSON.stringify's
+ * own (compact, raw UTF-8); every decoder of the format accepts it. Imports
+ * nothing.
+ */
+
+/** JSON.stringify replacer: a non-finite number is not JSON, so refuse it rather than emit null or NaN. */
+function refuseNonFinite(key: string, value: unknown): unknown {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new RangeError(`cannot frame the non-finite number ${value}${key ? ` at key "${key}"` : ''}`)
+  }
+  return value
+}
+
+/** `PLOTAPP:<json>\n`. JSON escapes every newline inside a string, so the message is one line. */
+export function encodeMessage(obj: Record<string, unknown>): Buffer {
+  return Buffer.from(`PLOTAPP:${JSON.stringify(obj, refuseNonFinite)}\n`, 'utf8')
+}
+
+/**
+ * The prefix line and the header bytes of a PLOTBIN frame. The payload is the
+ * caller's Buffer, written as its own chunk after these two, never copied.
+ */
+export function encodeBinary(header: Record<string, unknown>, payload: Buffer): [Buffer, Buffer] {
+  const head = Buffer.from(JSON.stringify(header, refuseNonFinite), 'utf8')
+  return [Buffer.from(`PLOTBIN:${head.length}:${payload.length}\n`, 'ascii'), head]
+}

{de_shell-0.3.0 → de_shell-0.4.0}/de_shell/js/main/index.ts

@@ -22,6 +22,10 @@ export {
 export { recordProblem, recordedProblems } from './problemLog'
 export type { Problem } from './problemLog'
 
+export { createRelay } from './relay'
+export type { Relay, RelayConnection, RelayCloseReason, RelayOptions } from './relay'
+export { encodeMessage, encodeBinary } from './framing'
+
 export {
   initErrorReporting, reportingConfigured, collectDiagnostics, submitReport,
 } from './errorReport'