@mhome/artifact-protocol 1.1.1 → 1.2.0

package/README.md

@@ -6,7 +6,10 @@ The crate is the source of truth for the `meow-artifact://v1/` URI format and it
 immutable image, audio, video, and file metadata. The published schema and conformance
 fixtures are intended for non-Rust runtimes.
 
-The crate also defines the transport-neutral `/artifact/resolve` request and response.
+The crate also defines the transport-neutral `/artifact/resolve`, `/artifact/put`, and
+`/artifact/upload/prepare` request and response contracts. The upload preparation
+contract keeps large artifact bytes on an authenticated HTTP data plane instead of
+embedding them in a control-plane message.
 Delivery is an explicit `DATA_URL` or `SIGNED_URL` union; a signed URL may point to a
 cloud object store or an authenticated local streaming endpoint.
 

package/fixtures/artifact-upload.conformance.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "valid": [
+    {
+      "name": "audio-upload-request",
+      "value": {
+        "kind": "AUDIO",
+        "mimeType": "audio/ogg",
+        "sizeBytes": 10800000,
+        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "durationMillis": 3600000
+      }
+    },
+    {
+      "name": "upload-response",
+      "value": {
+        "uploadId": "upload-1",
+        "url": "http://127.0.0.1:3210/artifact/v1/upload/signed-grant",
+        "headers": {
+          "content-type": "audio/ogg",
+          "content-length": "10800000",
+          "x-meow-content-sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "expiresAtUnixMs": 1700000000000
+      }
+    }
+  ],
+  "invalid": [
+    {
+      "name": "uppercase-hash",
+      "value": {
+        "kind": "AUDIO",
+        "mimeType": "audio/ogg",
+        "sizeBytes": 42,
+        "sha256": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+      }
+    },
+    {
+      "name": "non-http-upload-url",
+      "value": {
+        "uploadId": "upload-1",
+        "url": "file:///tmp/upload",
+        "headers": {},
+        "expiresAtUnixMs": 1700000000000
+      }
+    }
+  ]
+}

package/manifest/artifact.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.artifact.v1",
-  "contractVersion": "1.1.1",
+  "contractVersion": "1.2.0",
   "uriPrefix": "meow-artifact://v1/",
   "kinds": ["image", "audio", "video", "file"],
   "resolve": {
@@ -12,5 +12,10 @@
     "target": "/artifact/put",
     "schema": "schema/artifact-put.v1.schema.json",
     "schemaVersion": 1
+  },
+  "uploadPrepare": {
+    "target": "/artifact/upload/prepare",
+    "schema": "schema/artifact-upload.v1.schema.json",
+    "schemaVersion": 1
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/artifact-protocol",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Build-time protocol artifacts for mhome.artifact",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,15 +1,17 @@
 {
   "protocol": "mhome.artifact",
-  "contractVersion": "1.1.1",
+  "contractVersion": "1.2.0",
   "manifest": "manifest/artifact.v1.json",
   "schemas": {
     "artifactMetadata": "schema/artifact-metadata.v1.schema.json",
     "artifactResolve": "schema/artifact-resolve.v1.schema.json",
-    "artifactPut": "schema/artifact-put.v1.schema.json"
+    "artifactPut": "schema/artifact-put.v1.schema.json",
+    "artifactUpload": "schema/artifact-upload.v1.schema.json"
   },
   "fixtures": {
     "artifactReference": "fixtures/artifact-reference.conformance.json",
     "artifactResolve": "fixtures/artifact-resolve.conformance.json",
-    "artifactPut": "fixtures/artifact-put.conformance.json"
+    "artifactPut": "fixtures/artifact-put.conformance.json",
+    "artifactUpload": "fixtures/artifact-upload.conformance.json"
   }
 }

package/schema/artifact-upload.v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mhome.ai/schema/artifact-upload.v1.schema.json",
+  "title": "mHome Artifact Upload v1",
+  "oneOf": [
+    { "$ref": "#/$defs/request" },
+    { "$ref": "#/$defs/response" }
+  ],
+  "$defs": {
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "mimeType", "sizeBytes", "sha256"],
+      "properties": {
+        "kind": { "enum": ["IMAGE", "AUDIO", "VIDEO", "FILE"] },
+        "mimeType": { "type": "string", "minLength": 3, "maxLength": 255 },
+        "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "durationMillis": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["uploadId", "url", "headers", "expiresAtUnixMs"],
+      "properties": {
+        "uploadId": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "pattern": "^https?://" },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "expiresAtUnixMs": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
+      }
+    }
+  }
+}