@objectstack/spec 0.7.1 → 0.7.2

package/json-schema/system/EventBusConfig.json

@@ -0,0 +1,552 @@
+{
+  "$ref": "#/definitions/EventBusConfig",
+  "definitions": {
+    "EventBusConfig": {
+      "type": "object",
+      "properties": {
+        "persistence": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Enable event persistence"
+            },
+            "retention": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "Days to retain persisted events"
+            },
+            "storage": {
+              "type": "string",
+              "enum": [
+                "database",
+                "file",
+                "s3",
+                "custom"
+              ],
+              "default": "database",
+              "description": "Storage backend for persisted events"
+            }
+          },
+          "required": [
+            "retention"
+          ],
+          "additionalProperties": false,
+          "description": "Event persistence configuration"
+        },
+        "queue": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "default": "events",
+              "description": "Event queue name"
+            },
+            "concurrency": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 10,
+              "description": "Max concurrent event handlers"
+            },
+            "retryPolicy": {
+              "type": "object",
+              "properties": {
+                "maxRetries": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "default": 3,
+                  "description": "Max retries for failed events"
+                },
+                "backoffStrategy": {
+                  "type": "string",
+                  "enum": [
+                    "fixed",
+                    "linear",
+                    "exponential"
+                  ],
+                  "default": "exponential",
+                  "description": "Backoff strategy"
+                },
+                "initialDelayMs": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "default": 1000,
+                  "description": "Initial retry delay"
+                },
+                "maxDelayMs": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "default": 60000,
+                  "description": "Maximum retry delay"
+                }
+              },
+              "additionalProperties": false,
+              "description": "Default retry policy for events"
+            },
+            "deadLetterQueue": {
+              "type": "string",
+              "description": "Dead letter queue name for failed events"
+            },
+            "priorityEnabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Process events based on priority"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Event queue configuration"
+        },
+        "eventSourcing": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Enable event sourcing"
+            },
+            "snapshotInterval": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "default": 100,
+              "description": "Create snapshot every N events"
+            },
+            "snapshotRetention": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "default": 10,
+              "description": "Number of snapshots to retain"
+            },
+            "retention": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "default": 365,
+              "description": "Days to retain events"
+            },
+            "aggregateTypes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Aggregate types to enable event sourcing for"
+            },
+            "storage": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "database",
+                    "file",
+                    "s3",
+                    "eventstore"
+                  ],
+                  "default": "database",
+                  "description": "Storage backend"
+                },
+                "options": {
+                  "type": "object",
+                  "additionalProperties": {},
+                  "description": "Storage-specific options"
+                }
+              },
+              "additionalProperties": false,
+              "description": "Event store configuration"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Event sourcing configuration"
+        },
+        "replay": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Enable event replay capability"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Event replay configuration"
+        },
+        "webhooks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Unique webhook identifier"
+              },
+              "eventPattern": {
+                "type": "string",
+                "description": "Event name pattern (supports wildcards)"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "Webhook endpoint URL"
+              },
+              "method": {
+                "type": "string",
+                "enum": [
+                  "GET",
+                  "POST",
+                  "PUT",
+                  "PATCH"
+                ],
+                "default": "POST",
+                "description": "HTTP method"
+              },
+              "headers": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "description": "HTTP headers"
+              },
+              "authentication": {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "none",
+                      "bearer",
+                      "basic",
+                      "api-key"
+                    ],
+                    "description": "Auth type"
+                  },
+                  "credentials": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string"
+                    },
+                    "description": "Auth credentials"
+                  }
+                },
+                "required": [
+                  "type"
+                ],
+                "additionalProperties": false,
+                "description": "Authentication configuration"
+              },
+              "retryPolicy": {
+                "type": "object",
+                "properties": {
+                  "maxRetries": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "default": 3,
+                    "description": "Max retry attempts"
+                  },
+                  "backoffStrategy": {
+                    "type": "string",
+                    "enum": [
+                      "fixed",
+                      "linear",
+                      "exponential"
+                    ],
+                    "default": "exponential"
+                  },
+                  "initialDelayMs": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "default": 1000,
+                    "description": "Initial retry delay"
+                  },
+                  "maxDelayMs": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "default": 60000,
+                    "description": "Max retry delay"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Retry policy"
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "default": 30000,
+                "description": "Request timeout in milliseconds"
+              },
+              "enabled": {
+                "type": "boolean",
+                "default": true,
+                "description": "Whether webhook is enabled"
+              }
+            },
+            "required": [
+              "eventPattern",
+              "url"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Webhook configurations"
+        },
+        "messageQueue": {
+          "type": "object",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "enum": [
+                "kafka",
+                "rabbitmq",
+                "aws-sqs",
+                "redis-pubsub",
+                "google-pubsub",
+                "azure-service-bus"
+              ],
+              "description": "Message queue provider"
+            },
+            "topic": {
+              "type": "string",
+              "description": "Topic or queue name"
+            },
+            "eventPattern": {
+              "type": "string",
+              "default": "*",
+              "description": "Event name pattern to publish (supports wildcards)"
+            },
+            "partitionKey": {
+              "type": "string",
+              "description": "JSON path for partition key (e.g., \"metadata.tenantId\")"
+            },
+            "format": {
+              "type": "string",
+              "enum": [
+                "json",
+                "avro",
+                "protobuf"
+              ],
+              "default": "json",
+              "description": "Message serialization format"
+            },
+            "includeMetadata": {
+              "type": "boolean",
+              "default": true,
+              "description": "Include event metadata in message"
+            },
+            "compression": {
+              "type": "string",
+              "enum": [
+                "none",
+                "gzip",
+                "snappy",
+                "lz4"
+              ],
+              "default": "none",
+              "description": "Message compression"
+            },
+            "batchSize": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1,
+              "description": "Batch size for publishing"
+            },
+            "flushIntervalMs": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "default": 1000,
+              "description": "Flush interval for batching"
+            }
+          },
+          "required": [
+            "provider",
+            "topic"
+          ],
+          "additionalProperties": false,
+          "description": "Message queue integration"
+        },
+        "realtime": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Enable real-time notifications"
+            },
+            "protocol": {
+              "type": "string",
+              "enum": [
+                "websocket",
+                "sse",
+                "long-polling"
+              ],
+              "default": "websocket",
+              "description": "Real-time protocol"
+            },
+            "eventPattern": {
+              "type": "string",
+              "default": "*",
+              "description": "Event pattern to broadcast"
+            },
+            "userFilter": {
+              "type": "boolean",
+              "default": true,
+              "description": "Filter events by user"
+            },
+            "tenantFilter": {
+              "type": "boolean",
+              "default": true,
+              "description": "Filter events by tenant"
+            },
+            "channels": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Channel name"
+                  },
+                  "eventPattern": {
+                    "type": "string",
+                    "description": "Event pattern for channel"
+                  }
+                },
+                "required": [
+                  "name",
+                  "eventPattern"
+                ],
+                "additionalProperties": false
+              },
+              "description": "Named channels for event broadcasting"
+            },
+            "rateLimit": {
+              "type": "object",
+              "properties": {
+                "maxEventsPerSecond": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "description": "Max events per second per client"
+                },
+                "windowMs": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "default": 1000,
+                  "description": "Rate limit window"
+                }
+              },
+              "required": [
+                "maxEventsPerSecond"
+              ],
+              "additionalProperties": false,
+              "description": "Rate limiting configuration"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Real-time notification configuration"
+        },
+        "eventTypes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 3,
+                "pattern": "^[a-z][a-z0-9_.]*$",
+                "description": "Event type name (lowercase with dots)"
+              },
+              "version": {
+                "type": "string",
+                "default": "1.0.0",
+                "description": "Event schema version"
+              },
+              "schema": {
+                "description": "JSON Schema for event payload validation"
+              },
+              "description": {
+                "type": "string",
+                "description": "Event type description"
+              },
+              "deprecated": {
+                "type": "boolean",
+                "default": false,
+                "description": "Whether this event type is deprecated"
+              },
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Event type tags"
+              }
+            },
+            "required": [
+              "name"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Event type definitions"
+        },
+        "handlers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Unique handler identifier"
+              },
+              "eventName": {
+                "type": "string",
+                "description": "Name of event to handle (supports wildcards like user.*)"
+              },
+              "priority": {
+                "type": "integer",
+                "default": 0,
+                "description": "Execution priority (lower numbers execute first)"
+              },
+              "async": {
+                "type": "boolean",
+                "default": true,
+                "description": "Execute in background (true) or block (false)"
+              },
+              "retry": {
+                "type": "object",
+                "properties": {
+                  "maxRetries": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "default": 3,
+                    "description": "Maximum retry attempts"
+                  },
+                  "backoffMs": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "default": 1000,
+                    "description": "Initial backoff delay"
+                  },
+                  "backoffMultiplier": {
+                    "type": "number",
+                    "exclusiveMinimum": 0,
+                    "default": 2,
+                    "description": "Backoff multiplier"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Retry policy for failed handlers"
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "description": "Handler timeout in milliseconds"
+              }
+            },
+            "required": [
+              "eventName"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Global event handlers"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/system/EventHandler.json

@@ -4,6 +4,10 @@
     "EventHandler": {
       "type": "object",
       "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique handler identifier"
+        },
         "eventName": {
           "type": "string",
           "description": "Name of event to handle (supports wildcards like user.*)"
@@ -17,6 +21,36 @@
           "type": "boolean",
           "default": true,
           "description": "Execute in background (true) or block (false)"
+        },
+        "retry": {
+          "type": "object",
+          "properties": {
+            "maxRetries": {
+              "type": "integer",
+              "minimum": 0,
+              "default": 3,
+              "description": "Maximum retry attempts"
+            },
+            "backoffMs": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "default": 1000,
+              "description": "Initial backoff delay"
+            },
+            "backoffMultiplier": {
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "default": 2,
+              "description": "Backoff multiplier"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Retry policy for failed handlers"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "description": "Handler timeout in milliseconds"
         }
       },
       "required": [