async-matrix 0.1.3 → 1.1.0

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

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "../error"
+
+module Async
+	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
+			#
+			class ValidationError < Async::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"
+						header += " for #{@event_type}" if @event_type
+						header += " event #{@event_id}" if @event_id
+						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)
+						return "root" if pointer.nil? || pointer.empty?
+						pointer.delete_prefix("/").gsub("/", ".")
+					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
+
+test do
+	describe "Async::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 = Async::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 = Async::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 = Async::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 = Async::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 = Async::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 = Async::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 = Async::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 = Async::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 = Async::Matrix::Schema::ValidationError.new(raw)
+			err.errors.should.equal raw
+		end
+	end
+end

data/lib/async/matrix/schema.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/matrix"
+
+module Async
+	module Matrix
+		# Schema-driven validation for Matrix events using the official matrix-org/matrix-spec
+		# YAML schemas and the json_schemer gem.
+		#
+		# Schemas are loaded lazily from data/matrix-spec/event-schemas/schema/ and cached
+		# for the process lifetime. This ensures validation is always up-to-date with the
+		# spec -- just re-run `bin/fetch-matrix-schemas` to pull the latest.
+		#
+		#   # Look up a schema by event type
+		#   Async::Matrix::Schema["m.room.message"]  # => JSONSchemer::Schema
+		#
+		#   # Validate an event hash
+		#   Async::Matrix::Schema.valid?(event_hash)  # => true/false
+		#   Async::Matrix::Schema.validate(event_hash) # => [errors]
+		#
+		#   # List all known event types
+		#   Async::Matrix::Schema.event_types  # => ["m.accepted_terms", "m.call.answer", ...]
+		#
+		module Schema
+			class << self
+				# Look up a schema by Matrix event type.
+				# @param event_type [String] e.g. "m.room.message"
+				# @return [JSONSchemer::Schema, nil]
+				def [](event_type)
+					Registry.instance[event_type]
+				end
+
+				# Look up a variant schema.
+				# @param event_type [String] e.g. "m.room.message"
+				# @param subtype [String] e.g. "m.text"
+				# @return [JSONSchemer::Schema, nil]
+				def variant(event_type, subtype)
+					Registry.instance.variant(event_type, subtype)
+				end
+
+				# Validate an event hash against its schema.
+				# @param event_hash [Hash] the raw event data (string keys)
+				# @return [Array<Hash>] array of error hashes (empty if valid)
+				def validate(event_hash)
+					Registry.instance.validate(event_hash)
+				end
+
+				# Boolean validation.
+				# @param event_hash [Hash] the raw event data (string keys)
+				# @return [Boolean]
+				def valid?(event_hash)
+					Registry.instance.valid?(event_hash)
+				end
+
+				# All known base event types.
+				# @return [Array<String>] sorted
+				def event_types
+					Registry.instance.event_types
+				end
+
+				# All known variant types as [event_type, subtype] pairs.
+				# @return [Array<Array(String, String)>]
+				def variant_types
+					Registry.instance.variant_types
+				end
+
+				# Content properties defined by the schema for a given event type.
+				# @return [Array<String>]
+				def content_properties(event_type)
+					Registry.instance.content_properties(event_type)
+				end
+
+				# Parse a raw event hash into a schema-aware Event.
+				# @param event_hash [Hash] the raw event data (string keys)
+				# @return [ApplicationService::Event]
+				def parse(event_hash)
+					ApplicationService::Event.new(event_hash)
+				end
+
+				# Total schemas loaded (base + variants).
+				# @return [Integer]
+				def size
+					Registry.instance.size
+				end
+			end
+		end
+	end
+end
+
+test do
+	describe "Async::Matrix::Schema" do
+		it "looks up schemas by event type" do
+			schema = Async::Matrix::Schema["m.room.message"]
+			schema.should.not.be.nil
+			schema.should.be.kind_of JSONSchemer::Schema
+		end
+
+		it "returns nil for unknown event types" do
+			Async::Matrix::Schema["m.fake.event"].should.be.nil
+		end
+
+		it "validates event hashes" do
+			valid_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"
+			}
+			Async::Matrix::Schema.valid?(valid_event).should == true
+		end
+
+		it "returns errors for invalid events" do
+			invalid_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"
+			}
+			errors = Async::Matrix::Schema.validate(invalid_event)
+			errors.should.not.be.empty
+		end
+
+		it "lists event types" do
+			types = Async::Matrix::Schema.event_types
+			types.should.be.kind_of Array
+			types.should.include "m.room.message"
+			types.should.include "m.room.member"
+		end
+
+		it "lists variant types" do
+			variants = Async::Matrix::Schema.variant_types
+			variants.should.not.be.empty
+		end
+
+		it "looks up variant schemas" do
+			schema = Async::Matrix::Schema.variant("m.room.message", "m.text")
+			schema.should.not.be.nil
+		end
+
+		it "returns content properties" do
+			props = Async::Matrix::Schema.content_properties("m.room.message")
+			props.should.include "msgtype"
+			props.should.include "body"
+		end
+
+		it "reports total schema count" do
+			Async::Matrix::Schema.size.should.be > 50
+		end
+
+		it "parses a raw hash into a schema-aware Event" do
+			event = Async::Matrix::Schema.parse({
+				"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"
+			})
+			event.should.be.kind_of Async::Matrix::ApplicationService::Event
+			event.type.should == "m.room.message"
+			event.content.body.should == "hello"
+			event.valid?.should == true
+			event.schema.should.not.be.nil
+		end
+	end
+end

data/lib/async/matrix/server.rb

@@ -5,16 +5,17 @@
 
 require "bundler/setup"
 require "async/http"
+require "async/matrix"
 
 module Async
-	module Matrix
-		class Server < Async::HTTP::Protocol::HTTP2::Server
-		end
-	end
+  module Matrix
+    class Server < Async::HTTP::Protocol::HTTP2::Server
+    end
+  end
 end
 
 test do
-	it "inherits from Async::HTTP::Protocol::HTTP2::Server" do
-		Async::Matrix::Server.ancestors.should.include Async::HTTP::Protocol::HTTP2::Server
-	end
+  it "inherits from Async::HTTP::Protocol::HTTP2::Server" do
+    Async::Matrix::Server.ancestors.should.include Async::HTTP::Protocol::HTTP2::Server
+  end
 end

data/lib/async/matrix/stream.rb

@@ -8,14 +8,14 @@ require "async/http"
 require "async/matrix"
 
 module Async
-	module Matrix
-		class Stream < Async::HTTP::Protocol::HTTP2::Stream
-		end
-	end
+  module Matrix
+    class Stream < Async::HTTP::Protocol::HTTP2::Stream
+    end
+  end
 end
 
 test do
-	it "inherits from Async::HTTP::Protocol::HTTP2::Stream" do
-		Async::Matrix::Stream.ancestors.should.include Async::HTTP::Protocol::HTTP2::Stream
-	end
+  it "inherits from Async::HTTP::Protocol::HTTP2::Stream" do
+    Async::Matrix::Stream.ancestors.should.include Async::HTTP::Protocol::HTTP2::Stream
+  end
 end

data/lib/async/matrix/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Matrix
-    VERSION = "0.1.3"
+    VERSION = "1.1.0"
 	end
 end

data/lib/async/matrix.rb

@@ -3,15 +3,17 @@
 # Released under the Apache License, Version 2.0.
 # Copyright, 2026, by General Intelligence Systems.
 
+require "bundler/setup"
 require "async/http"
 require "scampi"
 
 module Async
-	module Matrix
-	end
+  module Matrix
+  end
 end
 
 Dir.glob("#{__dir__}/matrix/**/*.rb").sort.each do |path|
+  next if path.include?("/migrations/")
   require path
 end