async-matrix 0.1.0

data/lib/async/matrix/application_service/server.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "json"
+require "rack"
+require "console"
+
+module Async
+	module Matrix
+		module ApplicationService
+			# Rack 3 application implementing the Matrix Application Service API.
+			#
+			# Routes:
+			#   PUT  /_matrix/app/v1/transactions/{txnId}  — receive events from homeserver
+			#   GET  /_matrix/app/v1/users/{userId}         — user existence query
+			#   GET  /_matrix/app/v1/rooms/{roomAlias}       — room alias query
+			#   POST /_matrix/app/v1/ping                    — healthcheck
+			class Server
+				CONTENT_JSON = {"content-type" => "application/json"}.freeze
+				EMPTY_BODY   = ["{}"].freeze
+
+				RESP_NOT_FOUND  = [404, CONTENT_JSON, ['{"errcode":"M_UNRECOGNIZED"}']].freeze
+				RESP_FORBIDDEN  = [403, CONTENT_JSON, ['{"errcode":"M_FORBIDDEN"}']].freeze
+				RESP_BAD_JSON   = [400, CONTENT_JSON, ['{"errcode":"M_BAD_JSON"}']].freeze
+				RESP_BAD_METHOD = [405, CONTENT_JSON, ['{"errcode":"M_UNRECOGNIZED"}']].freeze
+
+				def initialize(hs_token:, dispatcher:)
+					@hs_token   = hs_token
+					@dispatcher = dispatcher
+					@txn_store  = TransactionStore.new
+				end
+
+				def call(env)
+					request = Rack::Request.new(env)
+					method  = request.request_method
+					path    = request.path_info
+
+					case path
+					when %r{\A/_matrix/app/v1/transactions/(.+)\z}
+						return RESP_BAD_METHOD unless method == "PUT"
+						return RESP_FORBIDDEN  unless authorized?(request)
+						handle_transaction(request, Regexp.last_match(1))
+
+					when %r{\A/_matrix/app/v1/users/(.+)\z}
+						return RESP_BAD_METHOD unless method == "GET"
+						return RESP_FORBIDDEN  unless authorized?(request)
+						[200, CONTENT_JSON, EMPTY_BODY]
+
+					when %r{\A/_matrix/app/v1/rooms/(.+)\z}
+						return RESP_BAD_METHOD unless method == "GET"
+						return RESP_FORBIDDEN  unless authorized?(request)
+						RESP_NOT_FOUND
+
+					when "/_matrix/app/v1/ping"
+						return RESP_BAD_METHOD unless method == "POST"
+						[200, CONTENT_JSON, EMPTY_BODY]
+
+					else
+						RESP_NOT_FOUND
+					end
+				end
+
+				private
+
+				def authorized?(request)
+					token = extract_token(request)
+					return false unless token
+					secure_compare(token, @hs_token)
+				end
+
+				def extract_token(request)
+					auth = request.get_header("HTTP_AUTHORIZATION")
+					if auth && auth.start_with?("Bearer ")
+						return auth.delete_prefix("Bearer ")
+					end
+					request.params["access_token"]
+				end
+
+				def secure_compare(a, b)
+					return false unless a.bytesize == b.bytesize
+					l = a.unpack("C*")
+					r = b.unpack("C*")
+					result = 0
+					l.each_with_index { |byte, i| result |= byte ^ r[i] }
+					result.zero?
+				end
+
+				def handle_transaction(request, txn_id)
+					if @txn_store.seen?(txn_id)
+						Console.debug(self) { "Duplicate transaction #{txn_id} — skipping" }
+						return [200, CONTENT_JSON, EMPTY_BODY]
+					end
+
+					body = parse_json(request)
+					return RESP_BAD_JSON unless body
+
+					Console.info(self) {
+						event_count = (body["events"] || []).size
+						"Transaction #{txn_id}: #{event_count} event(s)"
+					}
+
+					@dispatcher.dispatch_transaction(body)
+					@txn_store.mark_seen(txn_id)
+
+					[200, CONTENT_JSON, EMPTY_BODY]
+				end
+
+				def parse_json(request)
+					raw = request.body&.read
+					return nil if raw.nil? || raw.empty?
+					JSON.parse(raw)
+				rescue JSON::ParserError => e
+					Console.error(self) { "Bad JSON in transaction: #{e.message}" }
+					nil
+				end
+			end
+		end
+	end
+end
+
+test do
+	require "stringio"
+	require_relative "transaction_store"
+	require_relative "dispatcher"
+	require_relative "event"
+
+	describe "Async::Matrix::ApplicationService::Server" do
+		def build_server(hs_token: "secret")
+			dispatcher = Async::Matrix::ApplicationService::Dispatcher.new
+			Async::Matrix::ApplicationService::Server.new(hs_token: hs_token, dispatcher: dispatcher)
+		end
+
+		def env(method, path, headers: {}, body: nil, params: {})
+			rack_env = {
+				"REQUEST_METHOD" => method,
+				"PATH_INFO" => path,
+				"QUERY_STRING" => params.map { |k, v| "#{k}=#{v}" }.join("&"),
+				"rack.input" => body ? StringIO.new(body) : StringIO.new("")
+			}
+			headers.each { |k, v| rack_env["HTTP_#{k.upcase.tr("-", "_")}"] = v }
+			rack_env
+		end
+
+		# --- Ping ---
+
+		it "responds to POST /ping with 200" do
+			server = build_server
+			status, _, _ = server.call(env("POST", "/_matrix/app/v1/ping"))
+			status.should == 200
+		end
+
+		it "rejects GET /ping with 405" do
+			server = build_server
+			status, _, _ = server.call(env("GET", "/_matrix/app/v1/ping"))
+			status.should == 405
+		end
+
+		# --- Auth ---
+
+		it "rejects transactions without a token" do
+			server = build_server
+			status, _, _ = server.call(env("PUT", "/_matrix/app/v1/transactions/txn1"))
+			status.should == 403
+		end
+
+		it "rejects transactions with wrong token" do
+			server = build_server(hs_token: "correct")
+			status, _, _ = server.call(env("PUT", "/_matrix/app/v1/transactions/txn1",
+				headers: {"authorization" => "Bearer wrong"}))
+			status.should == 403
+		end
+
+		# --- Transactions ---
+
+		it "accepts valid transactions with Bearer auth" do
+			server = build_server(hs_token: "secret")
+			status, _, _ = server.call(env("PUT", "/_matrix/app/v1/transactions/txn1",
+				headers: {"authorization" => "Bearer secret"},
+				body: '{"events":[]}'))
+			status.should == 200
+		end
+
+		it "deduplicates transactions" do
+			server = build_server(hs_token: "secret")
+			rack = env("PUT", "/_matrix/app/v1/transactions/txn1",
+				headers: {"authorization" => "Bearer secret"},
+				body: '{"events":[]}')
+			server.call(rack)
+			# Second call with same txn_id
+			rack2 = env("PUT", "/_matrix/app/v1/transactions/txn1",
+				headers: {"authorization" => "Bearer secret"},
+				body: '{"events":[]}')
+			status, _, _ = server.call(rack2)
+			status.should == 200
+		end
+
+		it "rejects bad JSON" do
+			server = build_server(hs_token: "secret")
+			status, _, _ = server.call(env("PUT", "/_matrix/app/v1/transactions/txn1",
+				headers: {"authorization" => "Bearer secret"},
+				body: "not json"))
+			status.should == 400
+		end
+
+		# --- Users / Rooms ---
+
+		it "responds 200 for user queries" do
+			server = build_server(hs_token: "secret")
+			status, _, _ = server.call(env("GET", "/_matrix/app/v1/users/@bot:localhost",
+				headers: {"authorization" => "Bearer secret"}))
+			status.should == 200
+		end
+
+		it "responds 404 for room queries" do
+			server = build_server(hs_token: "secret")
+			status, _, _ = server.call(env("GET", "/_matrix/app/v1/rooms/#room:localhost",
+				headers: {"authorization" => "Bearer secret"}))
+			status.should == 404
+		end
+
+		# --- Unknown routes ---
+
+		it "responds 404 for unknown paths" do
+			server = build_server
+			status, _, _ = server.call(env("GET", "/unknown"))
+			status.should == 404
+		end
+	end
+end

data/lib/async/matrix/application_service/transaction.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require_relative "event"
+
+module Async
+	module Matrix
+		module ApplicationService
+			class Transaction
+				attr_reader :events, :ephemeral
+
+				def initialize(data)
+					@events    = (data["events"] || []).map { |e| Event.new(e) }
+					@ephemeral = (data["de.sorunome.msc2409.ephemeral"] || data["ephemeral"] || []).map { |e| Event.new(e) }
+				end
+			end
+		end
+	end
+end
+
+test do
+	describe "Async::Matrix::ApplicationService::Transaction" do
+		it "wraps events array" do
+			txn = Async::Matrix::ApplicationService::Transaction.new({
+				"events" => [
+					{"type" => "m.room.message", "content" => {"body" => "one"}},
+					{"type" => "m.room.message", "content" => {"body" => "two"}}
+				]
+			})
+			txn.events.length.should == 2
+			txn.events.first.content.body.should == "one"
+			txn.events.last.content.body.should == "two"
+		end
+
+		it "defaults to empty events when missing" do
+			txn = Async::Matrix::ApplicationService::Transaction.new({})
+			txn.events.should.be.empty
+		end
+
+		it "parses MSC2409 ephemeral events" do
+			txn = Async::Matrix::ApplicationService::Transaction.new({
+				"events" => [],
+				"de.sorunome.msc2409.ephemeral" => [
+					{"type" => "m.typing", "content" => {}}
+				]
+			})
+			txn.ephemeral.length.should == 1
+			txn.ephemeral.first.type.should == "m.typing"
+		end
+
+		it "falls back to ephemeral key" do
+			txn = Async::Matrix::ApplicationService::Transaction.new({
+				"events" => [],
+				"ephemeral" => [
+					{"type" => "m.receipt", "content" => {}}
+				]
+			})
+			txn.ephemeral.length.should == 1
+			txn.ephemeral.first.type.should == "m.receipt"
+		end
+
+		it "defaults to empty ephemeral when missing" do
+			txn = Async::Matrix::ApplicationService::Transaction.new({"events" => []})
+			txn.ephemeral.should.be.empty
+		end
+	end
+end

data/lib/async/matrix/application_service/transaction_store.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+
+module Async
+	module Matrix
+		module ApplicationService
+			# In-memory idempotency store for appservice transaction IDs.
+			class TransactionStore
+				DEFAULT_CAPACITY = 1024
+
+				def initialize(capacity: DEFAULT_CAPACITY)
+					@seen     = {}
+					@capacity = capacity
+				end
+
+				def seen?(txn_id)
+					@seen.key?(txn_id)
+				end
+
+				def mark_seen(txn_id)
+					prune! if @seen.size >= @capacity
+					@seen[txn_id] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+				end
+
+				def size
+					@seen.size
+				end
+
+				private
+
+				def prune!
+					sorted = @seen.sort_by { |_, ts| ts }
+					drop   = sorted.size / 2
+					sorted.first(drop).each { |id, _| @seen.delete(id) }
+				end
+			end
+		end
+	end
+end
+
+test do
+	describe "Async::Matrix::ApplicationService::TransactionStore" do
+		it "tracks seen transaction IDs" do
+			store = Async::Matrix::ApplicationService::TransactionStore.new
+			store.seen?("txn1").should == false
+			store.mark_seen("txn1")
+			store.seen?("txn1").should == true
+		end
+
+		it "reports size" do
+			store = Async::Matrix::ApplicationService::TransactionStore.new
+			store.size.should == 0
+			store.mark_seen("a")
+			store.mark_seen("b")
+			store.size.should == 2
+		end
+
+		it "prunes oldest entries when capacity is reached" do
+			store = Async::Matrix::ApplicationService::TransactionStore.new(capacity: 4)
+			store.mark_seen("a")
+			store.mark_seen("b")
+			store.mark_seen("c")
+			store.mark_seen("d")
+			# This triggers prune — drops oldest half (a, b)
+			store.mark_seen("e")
+			store.seen?("a").should == false
+			store.seen?("b").should == false
+			store.seen?("d").should == true
+			store.seen?("e").should == true
+		end
+
+		it "does not prune below capacity" do
+			store = Async::Matrix::ApplicationService::TransactionStore.new(capacity: 10)
+			5.times { |i| store.mark_seen("txn#{i}") }
+			store.size.should == 5
+			store.seen?("txn0").should == true
+		end
+	end
+end

data/lib/async/matrix/client.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/http/internet"
+require "json"
+require "erb"
+require "console"
+require "securerandom"
+require_relative "error"
+require_relative "application_service/error_response"
+
+module Async
+	module Matrix
+		# Async HTTP client for the Matrix Client-Server API.
+		#
+		# Every outbound request is authenticated with the appservice `as_token`.
+		# All methods are fiber-safe and run naturally inside Falcon's async reactor.
+		#
+		#   client = Async::Matrix::Client.new(config)
+		#   client.send_text("!room:example.com", "Hello world")
+		#   client.join_room("!room:example.com")
+		#
+		class Client
+			CLIENT_PREFIX = "/_matrix/client/v3"
+
+			attr_reader :config
+
+			def initialize(config)
+				@config  = config
+				@base    = config.homeserver_url
+				@headers = [
+					["authorization", "Bearer #{config.as_token}"],
+					["content-type",  "application/json"],
+					["user-agent",    "AsyncMatrix/#{Async::Matrix::VERSION}"]
+				]
+			end
+
+			# ── Messaging ──────────────────────────────────────────────
+
+			def send_text(room_id, text)
+				content = {msgtype: "m.text", body: text}
+				send_message_event(room_id, "m.room.message", content)
+			end
+
+			def send_html(room_id, html, plaintext = nil)
+				content = {
+					msgtype:        "m.text",
+					body:           plaintext || html.gsub(/<[^>]+>/, ""),
+					format:         "org.matrix.custom.html",
+					formatted_body: html
+				}
+				send_message_event(room_id, "m.room.message", content)
+			end
+
+			def send_notice(room_id, text)
+				content = {msgtype: "m.notice", body: text}
+				send_message_event(room_id, "m.room.message", content)
+			end
+
+			# ── Room actions ───────────────────────────────────────────
+
+			def join_room(room_id)
+				post("#{CLIENT_PREFIX}/join/#{encode(room_id)}")
+			end
+
+			def leave_room(room_id)
+				post("#{CLIENT_PREFIX}/rooms/#{encode(room_id)}/leave")
+			end
+
+			# ── Profile ────────────────────────────────────────────────
+
+			def set_display_name(name, user_id = nil)
+				uid = user_id || @config.bot_mxid
+				put(
+					"#{CLIENT_PREFIX}/profile/#{encode(uid)}/displayname",
+					{displayname: name}
+				)
+			end
+
+			# ── Verification ───────────────────────────────────────────
+
+			def whoami
+				get("#{CLIENT_PREFIX}/account/whoami")
+			end
+
+			# ── Low-level HTTP ─────────────────────────────────────────
+
+			def send_message_event(room_id, event_type, content)
+				txn_id = SecureRandom.uuid
+				path = "#{CLIENT_PREFIX}/rooms/#{encode(room_id)}/send/#{encode(event_type)}/#{txn_id}"
+				put(path, content)
+			end
+
+			def get(path)
+				request("GET", path)
+			end
+
+			def put(path, body = {})
+				request("PUT", path, body)
+			end
+
+			def post(path, body = {})
+				request("POST", path, body)
+			end
+
+			def close
+				@internet&.close
+				@internet = nil
+			end
+
+			private
+
+			def internet
+				@internet ||= Async::HTTP::Internet.new
+			end
+
+			def request(method, path, body = nil)
+				url = "#{@base}#{path}"
+				json_body = body ? JSON.generate(body) : nil
+
+				Console.debug(self) { "#{method} #{path}" }
+
+				response = internet.call(method, url, @headers, json_body)
+				status   = response.status
+				payload  = response.read
+
+				unless (200..299).cover?(status)
+					parsed = ApplicationService::ErrorResponse.new(
+						begin; JSON.parse(payload); rescue; {} end
+					)
+					Console.error(self) { "Matrix API #{status}: #{parsed.errcode} — #{parsed.error}" }
+					raise HomeserverError.new(
+						parsed.errcode || "UNKNOWN",
+						parsed.error || payload.to_s[0..200],
+						status: status
+					)
+				end
+
+				payload && !payload.empty? ? JSON.parse(payload) : {}
+			end
+
+			def encode(value)
+				ERB::Util.url_encode(value)
+			end
+		end
+	end
+end
+
+test do
+	require_relative "version"
+
+	describe "Async::Matrix::Client" do
+		it "sets authorization header from config" do
+			config = Struct.new(:homeserver_url, :as_token, :bot_mxid).new(
+				"http://localhost:8008", "test_token", "@bot:localhost"
+			)
+			client = Async::Matrix::Client.new(config)
+			client.config.as_token.should == "test_token"
+		end
+
+		it "responds to messaging methods" do
+			config = Struct.new(:homeserver_url, :as_token, :bot_mxid).new(
+				"http://localhost:8008", "token", "@bot:localhost"
+			)
+			client = Async::Matrix::Client.new(config)
+			client.should.respond_to :send_text
+			client.should.respond_to :send_html
+			client.should.respond_to :send_notice
+		end
+
+		it "responds to room action methods" do
+			config = Struct.new(:homeserver_url, :as_token, :bot_mxid).new(
+				"http://localhost:8008", "token", "@bot:localhost"
+			)
+			client = Async::Matrix::Client.new(config)
+			client.should.respond_to :join_room
+			client.should.respond_to :leave_room
+		end
+
+		it "responds to profile and verification methods" do
+			config = Struct.new(:homeserver_url, :as_token, :bot_mxid).new(
+				"http://localhost:8008", "token", "@bot:localhost"
+			)
+			client = Async::Matrix::Client.new(config)
+			client.should.respond_to :set_display_name
+			client.should.respond_to :whoami
+		end
+
+		it "can be closed without error" do
+			config = Struct.new(:homeserver_url, :as_token, :bot_mxid).new(
+				"http://localhost:8008", "token", "@bot:localhost"
+			)
+			client = Async::Matrix::Client.new(config)
+			lambda { client.close }.should.not.raise
+		end
+	end
+end

data/lib/async/matrix/connection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/http"
+
+module Async
+	module Matrix
+		module Connection
+			include Async::HTTP::Protocol::HTTP2::Connection
+		end
+	end
+end
+
+test do
+	it "includes Async::HTTP::Protocol::HTTP2::Connection" do
+		Async::Matrix::Connection.ancestors.should.include Async::HTTP::Protocol::HTTP2::Connection
+	end
+end

data/lib/async/matrix/endpoint.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "json"
+require "async/http"
+
+module Async
+	module Matrix
+		# Extends Async::HTTP::Endpoint with Matrix well-known discovery.
+		# spec.matrix.org/v1.9/client-server-api/#well-known-uri
+		#
+		# A server at example.com may serve clients from a completely
+		# different origin — e.g. https://matrix.example.com:8448.
+		# #discover resolves that indirection as a proper async I/O
+		# operation before constructing the Endpoint, so every downstream
+		# caller gets a correctly-pointed connection pool for free.
+		class Endpoint < Async::HTTP::Endpoint
+			WELL_KNOWN = "/.well-known/matrix/client"
+
+			# Resolves homeserver base URL, falls back to https://domain.
+			# Must be called inside an Async block — uses the running scheduler.
+			def self.discover(domain, **options)
+				internet = Async::HTTP::Internet.new
+				data     = JSON.parse(internet.get("https://#{domain}#{WELL_KNOWN}").read)
+				base_url = data.dig("m.homeserver", "base_url") || "https://#{domain}"
+				parse(base_url, **options)
+			rescue StandardError
+				# Well-known is optional per spec — fall back gracefully
+				parse("https://#{domain}", **options)
+			ensure
+				internet&.close
+			end
+		end
+	end
+end
+
+test do
+	it "defines the WELL_KNOWN constant" do
+		Async::Matrix::Endpoint::WELL_KNOWN.should == "/.well-known/matrix/client"
+	end
+
+	it "responds to .discover" do
+		Async::Matrix::Endpoint.should.respond_to :discover
+	end
+
+	it "inherits from Async::HTTP::Endpoint" do
+		Async::Matrix::Endpoint.ancestors.should.include Async::HTTP::Endpoint
+	end
+
+	it "falls back to https://domain when well-known fails" do
+		Async do
+			endpoint = Async::Matrix::Endpoint.discover("nonexistent.invalid")
+			endpoint.to_s.should =~ /nonexistent\.invalid/
+		end.wait
+	end
+end