dsh-plugin-dshm 0.0.0-stage → 0.1.0

package/lib/protocol/schema/dmp-v1/events.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dmp://v1/events.schema.json",
+  "title": "DMP v1 subscription events",
+  "description": "'ev.data' by 'ev.kind'. 'x-dmp-events' maps each kind to the watch method that emits it.",
+  "x-dmp-events": {
+    "workspace.upsert":   { "watch": "sessions.watch" },
+    "workspace.remove":   { "watch": "sessions.watch" },
+    "session.upsert":     { "watch": "sessions.watch" },
+    "session.remove":     { "watch": "sessions.watch" },
+    "timeline.upsert":    { "watch": "session.watch" },
+    "timeline.remove":    { "watch": "session.watch" },
+    "timeline.delta":     { "watch": "session.watch", "cap": "timeline.stream" },
+    "session.update":     { "watch": "session.watch" },
+    "interaction.open":   { "watch": "session.watch" },
+    "interaction.close":  { "watch": "session.watch" },
+    "queue.update":       { "watch": "session.watch" },
+    "session.reset":      { "watch": "session.watch" },
+    "jobs.replace":       { "watch": "jobs.watch" },
+    "job.output":         { "watch": "job.watch" },
+    "job.status":         { "watch": "job.watch" },
+    "devices.replace":    { "watch": "devices.watch" }
+  },
+  "$defs": {
+    "workspace.upsert": {
+      "type": "object", "additionalProperties": false, "required": ["workspace"],
+      "properties": { "workspace": { "$ref": "models.schema.json#/$defs/Workspace" } }
+    },
+    "workspace.remove": {
+      "type": "object", "additionalProperties": false, "required": ["workspaceId"],
+      "properties": { "workspaceId": { "$ref": "common.schema.json#/$defs/Id" } }
+    },
+    "session.upsert": {
+      "type": "object", "additionalProperties": false, "required": ["session"],
+      "properties": { "session": { "$ref": "models.schema.json#/$defs/SessionSummary" } }
+    },
+    "session.remove": {
+      "type": "object", "additionalProperties": false, "required": ["sessionId"],
+      "properties": { "sessionId": { "$ref": "common.schema.json#/$defs/Id" } }
+    },
+    "timeline.upsert": {
+      "type": "object", "additionalProperties": false, "required": ["item", "throughSeq"],
+      "properties": {
+        "item": { "$ref": "models.schema.json#/$defs/TimelineItem" },
+        "throughSeq": { "description": "Fully delivered checkpoint. Hold the previous watermark until the final projected change of a native sequence; item.seq may be higher meanwhile.", "$ref": "common.schema.json#/$defs/Seq" }
+      }
+    },
+    "timeline.remove": {
+      "type": "object", "additionalProperties": false, "required": ["itemId", "throughSeq"],
+      "properties": {
+        "itemId": { "$ref": "common.schema.json#/$defs/Id" },
+        "throughSeq": { "description": "Fully delivered checkpoint; advance only after every projected change through this sequence has been sent.", "$ref": "common.schema.json#/$defs/Seq" }
+      }
+    },
+    "timeline.delta": {
+      "description": "Ephemeral streaming text; does not advance throughSeq.",
+      "type": "object", "additionalProperties": false, "required": ["itemId", "field", "append"],
+      "properties": {
+        "itemId": { "$ref": "common.schema.json#/$defs/Id" },
+        "field": { "const": "text" },
+        "append": { "type": "string" }
+      }
+    },
+    "session.update": {
+      "type": "object", "additionalProperties": false, "required": ["session"],
+      "properties": { "session": { "$ref": "models.schema.json#/$defs/SessionDetail" } }
+    },
+    "interaction.open": {
+      "type": "object", "additionalProperties": false, "required": ["interaction"],
+      "properties": { "interaction": { "$ref": "models.schema.json#/$defs/Interaction" } }
+    },
+    "interaction.close": {
+      "type": "object", "additionalProperties": false, "required": ["interactionId", "reason"],
+      "properties": {
+        "interactionId": { "$ref": "common.schema.json#/$defs/Id" },
+        "reason": { "enum": ["answered", "cancelled", "expired"] }
+      }
+    },
+    "queue.update": {
+      "type": "object", "additionalProperties": false, "required": ["queue"],
+      "properties": { "queue": { "type": "array", "items": { "$ref": "models.schema.json#/$defs/QueueItem" } } }
+    },
+    "session.reset": {
+      "type": "object", "additionalProperties": false, "required": ["reason"],
+      "properties": { "reason": { "x-dmp-open-enum": true, "enum": ["rewritten", "removed", "dsh-restarted"] } }
+    },
+    "jobs.replace": {
+      "type": "object", "additionalProperties": false, "required": ["jobs"],
+      "properties": { "jobs": { "type": "array", "items": { "$ref": "models.schema.json#/$defs/Job" } } }
+    },
+    "job.output": {
+      "type": "object", "additionalProperties": false, "required": ["chunks", "next"],
+      "properties": {
+        "chunks": { "type": "array", "items": { "$ref": "models.schema.json#/$defs/JobChunk" } },
+        "next": { "description": "Byte offset after the last chunk.", "type": "integer", "minimum": 0 }
+      }
+    },
+    "job.status": {
+      "type": "object", "additionalProperties": false, "required": ["job"],
+      "properties": { "job": { "$ref": "models.schema.json#/$defs/Job" } }
+    },
+    "devices.replace": {
+      "type": "object", "additionalProperties": false, "required": ["devices"],
+      "properties": { "devices": { "type": "array", "items": { "$ref": "models.schema.json#/$defs/Device" } } }
+    }
+  }
+}

package/lib/protocol/schema/dmp-v1/frames.schema.json

@@ -0,0 +1,280 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dmp://v1/frames.schema.json",
+  "title": "DMP v1 text frames",
+  "description": "Every JSON WebSocket frame, split by direction (both directions use t='hello'). 'req.params', 'res.result' and 'ev.data' are further validated against methods/events schemas by method name or event kind.",
+  "$defs": {
+    "ServerFrame": {
+      "description": "Bridge → phone.",
+      "type": "object",
+      "required": ["t"],
+      "properties": { "t": { "type": "string" } },
+      "discriminator": { "propertyName": "t" },
+      "oneOf": [
+        { "$ref": "#/$defs/ServerHello" },
+        { "$ref": "#/$defs/AuthChallenge" },
+        { "$ref": "#/$defs/PairResult" },
+        { "$ref": "#/$defs/AuthOk" },
+        { "$ref": "#/$defs/Res" },
+        { "$ref": "#/$defs/Ev" },
+        { "$ref": "#/$defs/Err" },
+        { "$ref": "#/$defs/StreamAck" },
+        { "$ref": "#/$defs/StreamAbort" },
+        { "$ref": "#/$defs/Ping" },
+        { "$ref": "#/$defs/Pong" }
+      ]
+    },
+
+    "ClientFrame": {
+      "description": "Phone → bridge.",
+      "type": "object",
+      "required": ["t"],
+      "properties": { "t": { "type": "string" } },
+      "discriminator": { "propertyName": "t" },
+      "oneOf": [
+        { "$ref": "#/$defs/ClientHello" },
+        { "$ref": "#/$defs/PairRequest" },
+        { "$ref": "#/$defs/AuthResponse" },
+        { "$ref": "#/$defs/Req" },
+        { "$ref": "#/$defs/Cancel" },
+        { "$ref": "#/$defs/StreamAck" },
+        { "$ref": "#/$defs/StreamAbort" },
+        { "$ref": "#/$defs/Ping" },
+        { "$ref": "#/$defs/Pong" }
+      ]
+    },
+
+    "ServerHello": {
+      "description": "Bridge → phone, first frame after TLS.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "v", "host", "bridge", "dsh", "caps", "limits"],
+      "properties": {
+        "t": { "const": "hello" },
+        "v": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1 } },
+        "host": { "$ref": "models.schema.json#/$defs/HostInfo" },
+        "bridge": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["version", "instanceId"],
+          "properties": {
+            "version": { "type": "string" },
+            "instanceId": { "description": "Random id of this bridge process; changes on every restart. Lets the app tell whether in-memory state such as the creation ledger survived a reconnect.", "$ref": "common.schema.json#/$defs/Id" }
+          }
+        },
+        "dsh": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "version": { "type": "string" },
+            "status": { "enum": ["ok", "incompatible", "unavailable"] }
+          }
+        },
+        "caps": { "type": "array", "uniqueItems": true, "items": { "$ref": "common.schema.json#/$defs/Capability" } },
+        "limits": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["maxTextFrameBytes", "maxChunkBytes", "streamWindowBytes"],
+          "properties": {
+            "maxTextFrameBytes": { "type": "integer", "minimum": 65536 },
+            "maxChunkBytes": { "type": "integer", "minimum": 4096 },
+            "streamWindowBytes": { "type": "integer", "minimum": 65536 }
+          }
+        }
+      }
+    },
+
+    "ClientHello": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "v", "app"],
+      "properties": {
+        "t": { "const": "hello" },
+        "v": { "type": "integer", "minimum": 1 },
+        "app": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["version", "build", "platform"],
+          "properties": {
+            "version": { "type": "string" },
+            "build": { "type": "string" },
+            "platform": { "enum": ["ios", "ipados"] }
+          }
+        },
+        "caps": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+
+    "AuthChallenge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "nonce"],
+      "properties": {
+        "t": { "const": "auth.challenge" },
+        "nonce": { "description": "32 random bytes, base64url.", "$ref": "common.schema.json#/$defs/Base64Url" }
+      }
+    },
+
+    "PairRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "otp", "devicePublicKey", "deviceName", "deviceModel", "secureEnclave"],
+      "properties": {
+        "t": { "const": "pair.request" },
+        "otp": { "$ref": "common.schema.json#/$defs/Base64Url" },
+        "devicePublicKey": { "description": "P-256 public key, SPKI DER, base64.", "$ref": "common.schema.json#/$defs/Base64" },
+        "deviceName": { "type": "string", "maxLength": 128 },
+        "deviceModel": { "type": "string", "maxLength": 64 },
+        "secureEnclave": { "type": "boolean" }
+      }
+    },
+
+    "PairResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "deviceId", "hostId"],
+      "properties": {
+        "t": { "const": "pair.result" },
+        "deviceId": { "$ref": "common.schema.json#/$defs/Id" },
+        "hostId": { "$ref": "common.schema.json#/$defs/Id" }
+      }
+    },
+
+    "AuthResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "deviceId", "sig"],
+      "properties": {
+        "t": { "const": "auth.response" },
+        "deviceId": { "$ref": "common.schema.json#/$defs/Id" },
+        "sig": { "description": "ECDSA P-256 SHA-256, DER, base64. See dmp-v1.md §2.", "$ref": "common.schema.json#/$defs/Base64" }
+      }
+    },
+
+    "AuthOk": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "deviceId", "connectionId", "via"],
+      "properties": {
+        "t": { "const": "auth.ok" },
+        "deviceId": { "$ref": "common.schema.json#/$defs/Id" },
+        "connectionId": { "$ref": "common.schema.json#/$defs/Id" },
+        "via": { "enum": ["lan", "tailscale", "other"] }
+      }
+    },
+
+    "Req": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "id", "method", "params"],
+      "properties": {
+        "t": { "const": "req" },
+        "id": { "type": "integer", "minimum": 1 },
+        "method": { "type": "string", "pattern": "^[a-z]+(\\.[a-zA-Z]+)*$" },
+        "params": { "type": "object" }
+      }
+    },
+
+    "Res": {
+      "type": "object",
+      "required": ["t"],
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["t", "id", "ok", "result"],
+          "properties": {
+            "t": { "const": "res" },
+            "id": { "type": "integer", "minimum": 1 },
+            "ok": { "const": true },
+            "result": { "type": "object" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["t", "id", "ok", "error"],
+          "properties": {
+            "t": { "const": "res" },
+            "id": { "type": "integer", "minimum": 1 },
+            "ok": { "const": false },
+            "error": { "$ref": "common.schema.json#/$defs/Error" }
+          }
+        }
+      ],
+      "properties": { "t": { "const": "res" } }
+    },
+
+    "Cancel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "id"],
+      "properties": {
+        "t": { "const": "cancel" },
+        "id": { "type": "integer", "minimum": 1 }
+      }
+    },
+
+    "Ev": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "sub", "kind", "data"],
+      "properties": {
+        "t": { "const": "ev" },
+        "sub": { "$ref": "common.schema.json#/$defs/Id" },
+        "kind": { "type": "string", "pattern": "^[a-z]+\\.[a-z]+$" },
+        "data": { "type": "object" }
+      }
+    },
+
+    "Err": {
+      "description": "Connection-level error, sent before closing (e.g. during handshake). Request errors use res.ok=false instead.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "code", "message", "retryable"],
+      "properties": {
+        "t": { "const": "err" },
+        "code": { "$ref": "common.schema.json#/$defs/ErrorCode" },
+        "message": { "type": "string" },
+        "retryable": { "type": "boolean" }
+      }
+    },
+
+    "StreamAck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "streamId", "bytes"],
+      "properties": {
+        "t": { "const": "stream.ack" },
+        "streamId": { "type": "integer", "minimum": 1, "maximum": 4294967295 },
+        "bytes": { "description": "Cumulative bytes received.", "type": "integer", "minimum": 0 }
+      }
+    },
+
+    "StreamAbort": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t", "streamId", "code"],
+      "properties": {
+        "t": { "const": "stream.abort" },
+        "streamId": { "type": "integer", "minimum": 1, "maximum": 4294967295 },
+        "code": { "$ref": "common.schema.json#/$defs/ErrorCode" }
+      }
+    },
+
+    "Ping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t"],
+      "properties": { "t": { "const": "ping" } }
+    },
+
+    "Pong": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["t"],
+      "properties": { "t": { "const": "pong" } }
+    }
+  }
+}