@opensoha/contracts 0.1.19 → 0.1.21

package/network/network-ingest-event.schema.json

@@ -10,7 +10,7 @@
     "schemaVersion": { "const": "network-ingest/v1alpha1" },
     "batchId": { "$ref": "#/$defs/Identifier" },
     "producerId": { "$ref": "#/$defs/Identifier" },
-    "producerKind": { "enum": ["endpoint", "gateway", "freeradius", "network-control"] },
+    "producerKind": { "enum": ["endpoint", "gateway", "freeradius", "network-control", "proxy"] },
     "sentAt": { "type": "string", "format": "date-time" },
     "events": {
       "type": "array",
@@ -207,7 +207,8 @@
             "radius.accounting",
             "network.flow.aggregate",
             "network.connection.summary",
-            "proxy.flow.aggregate"
+            "proxy.flow.aggregate",
+            "proxy.runtime.sample"
           ]
         },
         "sequence": { "type": "integer", "minimum": 0 },
@@ -221,7 +222,8 @@
             { "$ref": "#/$defs/RadiusAccounting" },
             { "$ref": "#/$defs/FlowAggregate" },
             { "$ref": "#/$defs/ConnectionSummary" },
-            { "$ref": "#/$defs/ProxyFlowAggregate" }
+            { "$ref": "#/$defs/ProxyFlowAggregate" },
+            { "$ref": "#/$defs/ProxyRuntimeSample" }
           ]
         }
       },
@@ -302,6 +304,10 @@
         {
           "if": { "properties": { "type": { "const": "proxy.flow.aggregate" } }, "required": ["type"] },
           "then": { "properties": { "payload": { "$ref": "#/$defs/ProxyFlowAggregate" } } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "proxy.runtime.sample" } }, "required": ["type"] },
+          "then": { "properties": { "payload": { "$ref": "#/$defs/ProxyRuntimeSample" } } }
         }
       ]
     },
@@ -410,6 +416,18 @@
         "downloadBytes": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 },
         "activeConnections": { "type": "integer", "minimum": 0, "maximum": 1000000 }
       }
+    },
+    "ProxyRuntimeSample": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["engine", "uptimeSeconds", "uploadTotal", "downloadTotal"],
+      "properties": {
+        "engine": { "enum": ["mihomo", "sing-box", "v2ray"] },
+        "uptimeSeconds": { "type": "integer", "minimum": 0 },
+        "uploadTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "downloadTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "activeConnections": { "type": "integer", "minimum": 0, "maximum": 1000000 }
+      }
     }
   }
 }

package/network/network-runtime-protocol.schema.json

@@ -42,7 +42,7 @@
     },
     "producerId": { "$ref": "#/$defs/Identifier" },
     "runtimeId": { "$ref": "#/$defs/Identifier" },
-    "runtimeKind": { "enum": ["endpoint", "gateway", "nas"] },
+    "runtimeKind": { "enum": ["endpoint", "gateway", "nas", "proxy"] },
     "occurredAt": { "type": "string", "format": "date-time" },
     "expiresAt": { "type": "string", "format": "date-time" },
     "payload": {
@@ -712,7 +712,7 @@
           "minItems": 1,
           "maxItems": 32,
           "uniqueItems": true,
-          "items": { "enum": ["wireguard", "mihomo", "route-coordinator", "dns-coordinator", "managed-vpn-v1", "vpn-probe-v1", "vpn-metrics-v1"] }
+          "items": { "enum": ["wireguard", "mihomo", "route-coordinator", "dns-coordinator", "managed-vpn-v1", "vpn-probe-v1", "vpn-metrics-v1", "proxy-runtime-v1"] }
         }
       },
       "allOf": [{

package/network/proxy-runtime.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/network/proxy-runtime.schema.json",
+  "title": "OpenSoha Proxy Runtime Message",
+  "description": "Messages on the authenticated proxy runtime channel. Configuration content is delivered only to the enrolled runtime and is never returned by management reads.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "runtimeId", "messageType", "occurredAt", "payload"],
+  "properties": {
+    "schemaVersion": { "const": "proxy-runtime/v1alpha1" },
+    "runtimeId": { "$ref": "#/$defs/Identifier" },
+    "messageType": { "enum": ["configuration.desired", "configuration.applied", "observation", "connections.snapshot", "connection.close.request", "connection.close.result"] },
+    "occurredAt": { "type": "string", "format": "date-time" },
+    "payload": {
+      "oneOf": [
+        { "$ref": "#/$defs/ConfigurationDesired" },
+        { "$ref": "#/$defs/ConfigurationApplied" },
+        { "$ref": "#/$defs/Observation" },
+        { "$ref": "#/$defs/ConnectionsSnapshot" },
+        { "$ref": "#/$defs/ConnectionCloseRequest" },
+        { "$ref": "#/$defs/ConnectionCloseResult" }
+      ]
+    }
+  },
+  "allOf": [
+    { "if": { "properties": { "messageType": { "const": "configuration.desired" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConfigurationDesired" } } } },
+    { "if": { "properties": { "messageType": { "const": "configuration.applied" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConfigurationApplied" } } } },
+    { "if": { "properties": { "messageType": { "const": "observation" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/Observation" } } } },
+    { "if": { "properties": { "messageType": { "const": "connections.snapshot" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConnectionsSnapshot" } } } },
+    { "if": { "properties": { "messageType": { "const": "connection.close.request" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConnectionCloseRequest" } } } },
+    { "if": { "properties": { "messageType": { "const": "connection.close.result" } }, "required": ["messageType"] }, "then": { "properties": { "payload": { "$ref": "#/$defs/ConnectionCloseResult" } } } }
+  ],
+  "$defs": {
+    "Identifier": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" },
+    "Engine": { "enum": ["mihomo", "sing-box", "v2ray"] },
+    "Hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "ConfigurationDesired": {
+      "type": "object", "additionalProperties": false,
+      "required": ["revision", "engine", "enabled", "contentHash", "content", "validUntil"],
+      "properties": {
+        "revision": { "type": "integer", "minimum": 1 },
+        "engine": { "$ref": "#/$defs/Engine" },
+        "enabled": { "type": "boolean" },
+        "contentHash": { "$ref": "#/$defs/Hash" },
+        "content": { "type": "string", "minLength": 1, "maxLength": 1048576, "writeOnly": true },
+        "validUntil": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ConfigurationApplied": {
+      "type": "object", "additionalProperties": false,
+      "required": ["revision", "status", "readbackHash"],
+      "properties": {
+        "revision": { "type": "integer", "minimum": 1 },
+        "status": { "enum": ["applied", "rejected", "rolled-back"] },
+        "readbackHash": { "$ref": "#/$defs/Hash" },
+        "reasonCode": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    },
+    "Observation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["engine", "engineVersion", "health", "capabilities", "uptimeSeconds", "uploadTotal", "downloadTotal"],
+      "properties": {
+        "engine": { "$ref": "#/$defs/Engine" },
+        "engineVersion": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "health": { "enum": ["healthy", "degraded", "unhealthy"] },
+        "capabilities": { "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "enum": ["traffic", "connections", "close_connection"] } },
+        "reasonCode": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "uptimeSeconds": { "type": "integer", "minimum": 0 },
+        "uploadTotal": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 },
+        "downloadTotal": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 },
+        "activeConnections": { "type": "integer", "minimum": 0, "maximum": 1000000 }
+      }
+    },
+    "Connection": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "destination", "network", "uploadBytes", "downloadBytes"],
+      "properties": {
+        "id": { "$ref": "#/$defs/Identifier" },
+        "destination": { "type": "string", "minLength": 1, "maxLength": 253 },
+        "network": { "enum": ["tcp", "udp", "other"] },
+        "uploadBytes": { "type": "integer", "minimum": 0 },
+        "downloadBytes": { "type": "integer", "minimum": 0 },
+        "startedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ConnectionsSnapshot": {
+      "type": "object", "additionalProperties": false,
+      "required": ["engine", "connections"],
+      "properties": {
+        "engine": { "enum": ["mihomo", "sing-box"] },
+        "connections": { "type": "array", "maxItems": 200, "items": { "$ref": "#/$defs/Connection" } }
+      }
+    },
+    "ConnectionCloseRequest": {
+      "type": "object", "additionalProperties": false,
+      "required": ["commandId", "connectionId", "expiresAt"],
+      "properties": {
+        "commandId": { "$ref": "#/$defs/Identifier" },
+        "connectionId": { "$ref": "#/$defs/Identifier" },
+        "expiresAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ConnectionCloseResult": {
+      "type": "object", "additionalProperties": false,
+      "required": ["commandId", "status"],
+      "properties": {
+        "commandId": { "$ref": "#/$defs/Identifier" },
+        "status": { "enum": ["closed", "not-found", "failed"] },
+        "reasonCode": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    }
+  }
+}

package/network/schema.go

@@ -11,6 +11,9 @@ var (
 
 	//go:embed network-radius-accounting.schema.json
 	radiusAccountingSchema []byte
+
+	//go:embed proxy-runtime.schema.json
+	proxyRuntimeSchema []byte
 )
 
 func RuntimeProtocolSchema() []byte {
@@ -24,3 +27,7 @@ func IngestEventSchema() []byte {
 func RadiusAccountingSchema() []byte {
 	return append([]byte(nil), radiusAccountingSchema...)
 }
+
+func ProxyRuntimeSchema() []byte {
+	return append([]byte(nil), proxyRuntimeSchema...)
+}