async-matrix 2.1.0-x86_64-linux → 3.0.1-x86_64-linux

data/lib/protocol/matrix/schema/registry.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "yaml"
+require "json"
+require "json_schemer"
+require "pathname"
+
+module Protocol
+  module Matrix
+    module Schema
+      # Loads and indexes Matrix event schemas from the official matrix-org/matrix-spec
+      # YAML files bundled in data/matrix-spec/event-schemas/schema/.
+      #
+      # Schemas are loaded lazily on first access and cached for the lifetime of the
+      # process. Each schema is a JSONSchemer::Schema instance that resolves relative
+      # $ref paths (e.g. core-event-schema/room_event.yaml) via a file-based resolver.
+      #
+      #   registry = Protocol::Matrix::Schema::Registry.instance
+      #   registry["m.room.message"]                         # => JSONSchemer::Schema
+      #   registry.variant("m.room.message", "m.text")       # => JSONSchemer::Schema
+      #   registry.event_types                                # => ["m.accepted_terms", ...]
+      #
+      class Registry
+        # Custom format validators for Matrix-specific format hints.
+        MATRIX_FORMATS = {
+          "mx-user-id"         => ->(value, _schema) { value.is_a?(String) && value.match?(/\A@[^:]+:.+\z/) },
+          "mx-room-id"         => ->(value, _schema) { value.is_a?(String) && value.match?(/\A![^:]+:.+\z/) },
+          "mx-event-id"        => ->(value, _schema) { value.is_a?(String) && value.match?(/\A\$/) },
+          "mx-room-alias"      => ->(value, _schema) { value.is_a?(String) && value.match?(/\A#[^:]+:.+\z/) },
+          "mx-server-name"     => ->(value, _schema) { value.is_a?(String) && !value.empty? },
+          "mx-unpadded-base64" => ->(value, _schema) { value.is_a?(String) && value.match?(/\A[A-Za-z0-9+\/]*\z/) },
+        }.freeze
+
+        GEM_ROOT = File.expand_path("../../../..", __dir__)
+        SCHEMA_DIR = File.join(
+          GEM_ROOT,
+          "data",
+          "matrix-spec",
+          "event-schemas",
+          "schema",
+        )
+
+        @instance = nil
+
+        class << self
+          # Returns the singleton Registry instance, creating it on first access.
+          def instance
+            @instance ||= new
+          end
+
+          # Reset the singleton (useful for testing).
+          def reset!
+            @instance = nil
+          end
+        end
+
+        def initialize
+          @schemas = {}
+          @variants = {}
+          @loaded = false
+        end
+
+        # Look up a schema by Matrix event type (e.g. "m.room.message").
+        # Returns a JSONSchemer::Schema or nil if no schema exists for that type.
+        def [](event_type)
+          unless @loaded
+            load_schemas!
+          end
+          @schemas[event_type]
+        end
+
+        # Look up a variant schema (e.g. variant("m.room.message", "m.text")).
+        # Returns a JSONSchemer::Schema or nil.
+        def variant(event_type, subtype)
+          unless @loaded
+            load_schemas!
+          end
+          @variants[[event_type, subtype]]
+        end
+
+        # All known base event types (excludes variant subtypes).
+        # @return [Array<String>] sorted event type strings
+        def event_types
+          unless @loaded
+            load_schemas!
+          end
+          @schemas.keys.sort
+        end
+
+        # All known variant keys as [event_type, subtype] pairs.
+        # @return [Array<Array(String, String)>]
+        def variant_types
+          unless @loaded
+            load_schemas!
+          end
+          @variants.keys.sort
+        end
+
+        # Total number of schemas loaded (base + variants).
+        def size
+          unless @loaded
+            load_schemas!
+          end
+          @schemas.size + @variants.size
+        end
+
+        # Validate an event hash against its schema.
+        # Returns an array of error hashes (empty if valid).
+        # If no schema exists for the event type, returns empty (lenient).
+        def validate(event_hash)
+          event_type = event_hash["type"]
+          if event_type
+            base = self[event_type]
+            if base
+              errors = base.validate(event_hash).to_a
+              variant_key = detect_variant_key(event_type, event_hash)
+              if variant_key
+                variant_schema = variant(event_type, variant_key)
+                if variant_schema
+                  errors.concat(variant_schema.validate(event_hash).to_a)
+                end
+              end
+              errors
+            else
+              []
+            end
+          else
+            []
+          end
+        end
+
+        # Boolean validation.
+        def valid?(event_hash)
+          validate(event_hash).empty?
+        end
+
+        # Content properties defined by the schema for a given event type.
+        # Returns an array of property name strings, or empty array if unknown.
+        def content_properties(event_type)
+          schema = self[event_type]
+          if schema
+            extract_content_properties(schema.value)
+          else
+            []
+          end
+        end
+
+        private
+
+          # Ref resolver that loads YAML/JSON files from disk.
+          # json_schemer calls this with a URI for each $ref it encounters.
+          def ref_resolver
+            @ref_resolver ||= proc do |uri|
+              path = uri.path
+              if path && File.exist?(path)
+                content = File.read(path)
+                if path.end_with?(".yaml", ".yml")
+                  YAML.safe_load(content, permitted_classes: [Symbol])
+                else
+                  JSON.parse(content)
+                end
+              else
+                raise JSONSchemer::UnknownRef, uri.to_s
+              end
+            end
+          end
+
+          # Build a JSONSchemer::Schema from a parsed YAML hash, anchored at the
+          # given file path so relative $ref paths resolve correctly.
+          def build_schemer(parsed, file_path)
+            uri = URI("file://#{File.expand_path(file_path)}")
+            JSONSchemer.schema(
+              parsed,
+              base_uri:                 uri,
+              ref_resolver:             ref_resolver,
+              insert_property_defaults: false,
+              formats:                  MATRIX_FORMATS,
+            )
+          end
+
+          # Scan the schema directory and load all event schemas.
+          def load_schemas!
+            if @loaded
+              nil
+            else
+              Dir.glob(File.join(SCHEMA_DIR, "*.yaml")).each do |path|
+                load_schema_file(path)
+              end
+              Dir.glob(File.join(SCHEMA_DIR, "*.json")).each do |path|
+                load_schema_file(path)
+              end
+              @loaded = true
+            end
+          end
+
+          def load_schema_file(path)
+            filename = File.basename(path, File.extname(path))
+            content = File.read(path)
+            if path.end_with?(".json")
+              parsed = JSON.parse(content)
+            else
+              parsed = YAML.safe_load(content, permitted_classes: [Symbol])
+            end
+
+            schemer = build_schemer(parsed, path)
+
+            # Detect event type from schema: properties.type.enum[0]
+            declared_type = parsed.dig("properties", "type", "enum")&.first
+
+            if filename.include?("$")
+              # Variant schema: "m.room.message$m.text" -> base="m.room.message", sub="m.text"
+              parts = filename.split("$", 2)
+              base_type = declared_type || parts[0]
+              subtype = parts[1]
+              @variants[[base_type, subtype]] = schemer
+            elsif declared_type
+              @schemas[declared_type] = schemer
+            else
+              # Schemas without a type enum (like core-event-schema/) are skipped
+              # from the index -- they're only used as $ref targets.
+            end
+          rescue => e
+            # Don't let a single broken schema prevent loading the rest
+            warn "async-matrix: failed to load schema #{path}: #{e.message}"
+          end
+
+          # Detect the variant subtype key from an event hash.
+          # For m.room.message, the variant is the msgtype.
+          # For m.room.encrypted, the variant is the algorithm.
+          # For m.key.verification.start, the variant is the method.
+          def detect_variant_key(event_type, event_hash)
+            content = event_hash["content"]
+            if content.is_a?(Hash)
+              case event_type
+              when "m.room.message"
+                content["msgtype"]
+              when "m.room.encrypted"
+                content["algorithm"]
+              when "m.key.verification.start"
+                content["method"]
+              end
+            else
+              nil
+            end
+          end
+
+          # Extract content property names from a schema's parsed YAML.
+          def extract_content_properties(schema_hash)
+            props = schema_hash.dig("properties", "content", "properties")
+            if props.is_a?(Hash)
+              props.keys
+            else
+              []
+            end
+          end
+      end
+    end
+  end
+end
+
+__END__
+  describe "Protocol::Matrix::Schema::Registry" do
+    it "loads schemas from disk" do
+      Protocol::Matrix::Schema::Registry.instance.size.should.be > 0
+    end
+
+    it "has known event types" do
+      types = Protocol::Matrix::Schema::Registry.instance.event_types
+      types.should.include "m.room.message"
+      types.should.include "m.room.member"
+      types.should.include "m.room.create"
+      types.should.include "m.reaction"
+    end
+
+    it "returns a JSONSchemer::Schema for a known type" do
+      schema = Protocol::Matrix::Schema::Registry.instance["m.room.message"]
+      schema.should.not.be.nil
+      schema.should.be.kind_of JSONSchemer::Schema
+    end
+
+    it "returns nil for an unknown type" do
+      Protocol::Matrix::Schema::Registry.instance["m.fake.event"].should.be.nil
+    end
+
+    it "has variant schemas" do
+      Protocol::Matrix::Schema::Registry.instance.variant_types.should.not.be.empty
+    end
+
+    it "resolves variant schemas" do
+      schema = Protocol::Matrix::Schema::Registry.instance.variant("m.room.message", "m.text")
+      schema.should.not.be.nil
+      schema.should.be.kind_of JSONSchemer::Schema
+    end
+
+    it "validates a correct m.room.message event" do
+      event = {
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text", "body" => "hello"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      }
+      Protocol::Matrix::Schema::Registry.instance.valid?(event).should == true
+    end
+
+    it "rejects m.room.message missing body" do
+      event = {
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      }
+      Protocol::Matrix::Schema::Registry.instance.valid?(event).should == false
+    end
+
+    it "is lenient with unknown event types" do
+      event = {
+        "type" => "m.room.other",
+        "content" => {"msgtype" => "m.text", "body" => "hi"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      }
+      Protocol::Matrix::Schema::Registry.instance.valid?(event).should == true
+    end
+
+    it "validates m.room.member with correct membership" do
+      event = {
+        "type" => "m.room.member",
+        "content" => {"membership" => "join"},
+        "state_key" => "@alice:example.org",
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      }
+      Protocol::Matrix::Schema::Registry.instance.valid?(event).should == true
+    end
+
+    it "rejects m.room.member with invalid membership" do
+      event = {
+        "type" => "m.room.member",
+        "content" => {"membership" => "invalid_state"},
+        "state_key" => "@alice:example.org",
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      }
+      Protocol::Matrix::Schema::Registry.instance.valid?(event).should == false
+    end
+
+    it "returns content properties for known types" do
+      props = Protocol::Matrix::Schema::Registry.instance.content_properties("m.room.message")
+      props.should.include "msgtype"
+      props.should.include "body"
+    end
+
+    it "returns empty content properties for unknown types" do
+      Protocol::Matrix::Schema::Registry.instance.content_properties("m.fake.type").should == []
+    end
+
+    it "performs variant validation for m.room.message with msgtype" do
+      event = {
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text", "body" => "hello"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      }
+      Protocol::Matrix::Schema::Registry.instance.validate(event).should == []
+    end
+  end

data/lib/protocol/matrix/schema/validation_error.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "../error"
+
+module Protocol
+  module Matrix
+    module Schema
+      # Raised by Event#valid! when data fails schema validation.
+      #
+      # Produces detailed, human-readable error messages that identify the exact
+      # key path and offending value.
+      #
+      #   Schema validation failed for m.room.member event $abc123:
+      #     - content.membership = "invalid" -- must be one of: ["invite", "join", "knock", "leave", "ban"]
+      #     - sender is required but missing
+      #
+      # Carries an errcode, which the base supports: M_BAD_JSON is what a
+      # homeserver answers for a payload that fails its schema.
+      class ValidationError < Protocol::Matrix::Error
+        attr_reader :errors, :event_type, :event_id
+
+        # @param errors     [Array<Hash>] raw JSONSchemer error hashes
+        # @param event_type [String, nil] Matrix event type (e.g. "m.room.member")
+        # @param event_id   [String, nil] Matrix event ID (e.g. "$abc123")
+        def initialize(errors, event_type: nil, event_id: nil)
+          @errors     = errors
+          @event_type = event_type
+          @event_id   = event_id
+          super("M_BAD_JSON", build_message)
+        end
+
+        private
+
+          def build_message
+            lines = [header_line]
+            @errors.each { |e| lines.concat(Array(format_error(e))) }
+            lines.join("\n")
+          end
+
+          def header_line
+            header = "Schema validation failed"
+            if @event_type
+              header += " for #{@event_type}"
+            end
+            if @event_id
+              header += " event #{@event_id}"
+            end
+            header + ":"
+          end
+
+          def format_error(error)
+            path = pointer_to_dot(error["data_pointer"])
+            type = error["type"]
+            data = error["data"]
+
+            case type
+            when "required"
+              format_required(error, path)
+            when "string", "integer", "number", "boolean", "array", "object", "null"
+              "  - #{path} = #{truncate(data.inspect)} -- expected #{type}, got #{data.class}"
+            when "minimum"
+              "  - #{path} = #{truncate(data.inspect)} -- must be >= #{error.dig("schema", "minimum")}"
+            when "maximum"
+              "  - #{path} = #{truncate(data.inspect)} -- must be <= #{error.dig("schema", "maximum")}"
+            when "enum"
+              allowed = error.dig("schema", "enum")
+              "  - #{path} = #{truncate(data.inspect)} -- must be one of: #{truncate(allowed.inspect)}"
+            when "pattern"
+              pattern = error.dig("schema", "pattern")
+              "  - #{path} = #{truncate(data.inspect)} -- does not match pattern: #{pattern}"
+            when "format"
+              fmt = error.dig("schema", "format")
+              "  - #{path} = #{truncate(data.inspect)} -- invalid #{fmt} format"
+            when "minLength"
+              "  - #{path} = #{truncate(data.inspect)} -- length must be >= #{error.dig("schema", "minLength")}"
+            when "maxLength"
+              "  - #{path} = #{truncate(data.inspect)} -- length must be <= #{error.dig("schema", "maxLength")}"
+            when "minItems"
+              "  - #{path} -- array must have >= #{error.dig("schema", "minItems")} items"
+            when "maxItems"
+              "  - #{path} -- array must have <= #{error.dig("schema", "maxItems")} items"
+            when "uniqueItems"
+              "  - #{path} -- array items must be unique"
+            when "const"
+              expected = error.dig("schema", "const")
+              "  - #{path} = #{truncate(data.inspect)} -- must be #{truncate(expected.inspect)}"
+            when "additionalProperties"
+              "  - #{path}: #{error["error"] || "has additional properties that are not allowed"}"
+            else
+              msg = error["error"] || type
+              "  - #{path}: #{msg}"
+            end
+          end
+
+          def format_required(error, path)
+            missing = error.dig("details", "missing_keys") || []
+            if missing.empty?
+              "  - #{path}: #{error["error"] || "required"}"
+            else
+              missing.map { |key| "  - #{join_path(path, key)} is required but missing" }
+            end
+          end
+
+          def pointer_to_dot(pointer)
+            if pointer.nil? || pointer.empty?
+              "root"
+            else
+              pointer.delete_prefix("/").gsub("/", ".")
+            end
+          end
+
+          def join_path(base, key)
+            base == "root" ? key.to_s : "#{base}.#{key}"
+          end
+
+          def truncate(str, max: 60)
+            str.length > max ? "#{str[0...max]}..." : str
+          end
+      end
+    end
+  end
+end
+
+__END__
+  describe "Protocol::Matrix::Schema::ValidationError" do
+    def error_hash(overrides = {})
+      {
+        "data" => nil,
+        "data_pointer" => "",
+        "schema" => {},
+        "schema_pointer" => "",
+        "root_schema" => {},
+        "type" => "unknown",
+        "error" => "something went wrong"
+      }.merge(overrides)
+    end
+
+    it "includes event type in header" do
+      err = Protocol::Matrix::Schema::ValidationError.new(
+        [error_hash],
+        event_type: "m.room.message"
+      )
+      err.message.should.include "Schema validation failed for m.room.message"
+    end
+
+    it "includes event ID in header" do
+      err = Protocol::Matrix::Schema::ValidationError.new(
+        [error_hash],
+        event_type: "m.room.member",
+        event_id: "$abc123"
+      )
+      err.message.should.include "m.room.member event $abc123"
+    end
+
+    it "formats type mismatch errors" do
+      err = Protocol::Matrix::Schema::ValidationError.new([
+        error_hash(
+          "data_pointer" => "/content/body",
+          "type" => "string",
+          "data" => 42
+        )
+      ])
+      err.message.should.include "content.body = 42 -- expected string, got Integer"
+    end
+
+    it "formats required errors with missing keys" do
+      err = Protocol::Matrix::Schema::ValidationError.new([
+        error_hash(
+          "data_pointer" => "/content",
+          "type" => "required",
+          "details" => {"missing_keys" => ["msgtype", "body"]}
+        )
+      ])
+      err.message.should.include "content.msgtype is required but missing"
+      err.message.should.include "content.body is required but missing"
+    end
+
+    it "formats enum errors" do
+      err = Protocol::Matrix::Schema::ValidationError.new([
+        error_hash(
+          "data_pointer" => "/content/membership",
+          "type" => "enum",
+          "data" => "invalid",
+          "schema" => {"enum" => %w[invite join knock leave ban]}
+        )
+      ])
+      err.message.should.include 'content.membership = "invalid" -- must be one of:'
+      err.message.should.include "invite"
+    end
+
+    it "formats pattern errors" do
+      err = Protocol::Matrix::Schema::ValidationError.new([
+        error_hash(
+          "data_pointer" => "/state_key",
+          "type" => "pattern",
+          "data" => "bad",
+          "schema" => {"pattern" => "^@"}
+        )
+      ])
+      err.message.should.include 'state_key = "bad" -- does not match pattern: ^@'
+    end
+
+    it "formats format errors" do
+      err = Protocol::Matrix::Schema::ValidationError.new([
+        error_hash(
+          "data_pointer" => "/content/avatar_url",
+          "type" => "format",
+          "data" => "not-a-uri",
+          "schema" => {"format" => "uri"}
+        )
+      ])
+      err.message.should.include "invalid uri format"
+    end
+
+    it "truncates long values" do
+      err = Protocol::Matrix::Schema::ValidationError.new([
+        error_hash(
+          "data_pointer" => "/content/body",
+          "type" => "integer",
+          "data" => "a" * 200
+        )
+      ])
+      err.message.should.include "..."
+    end
+
+    it "exposes the raw errors array" do
+      raw = [error_hash]
+      err = Protocol::Matrix::Schema::ValidationError.new(raw)
+      err.errors.should.equal raw
+    end
+  end