async-matrix 1.0.0 → 1.1.0

data/lib/async/discord/api/path_tree.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "json"
+require "pathname"
+require "uri"
+require "async/discord"
+require "async/matrix"
+
+module Async
+  module Discord
+    module Api
+      # Loads the Discord HTTP API OpenAPI spec and builds a PathTree trie
+      # of all valid endpoints. Reuses the core Node/insert/match logic from
+      # Async::Matrix::Api::PathTree.
+      #
+      # The Discord spec is a single JSON file (OpenAPI 3.1.0) with the server
+      # URL https://discord.com/api/v10, yielding prefix segments ["api", "v10"].
+      #
+      #   tree = PathTree.load
+      #   tree.match(%w[api v10 channels 123 messages], "POST")
+      #   # => { valid: true, operation_id: "create_message", methods: ["post"] }
+      #
+      class PathTree < Async::Matrix::Api::PathTree
+        SCHEMA_PATH = Pathname.new(File.expand_path("../../../../data/discord-api-spec/openapi.json", __dir__)).freeze
+
+        def self.load(schema_path: SCHEMA_PATH)
+          tree = new
+          tree.load_json_schema(schema_path)
+          tree
+        end
+
+        # Parse the Discord OpenAPI JSON file and insert all paths into the trie.
+        def load_json_schema(path)
+          doc = JSON.parse(File.read(path))
+
+          base_path = extract_json_base_path(doc)
+          paths = doc["paths"]
+          return unless paths.is_a?(Hash)
+
+          paths.each do |path_template, methods_hash|
+            next unless methods_hash.is_a?(Hash)
+
+            full_path = "#{base_path}#{path_template.strip}"
+            segments = full_path.split("/").reject(&:empty?)
+
+            methods_hash.each do |method, operation|
+              # Skip path-level parameters (Discord spec puts these alongside methods)
+              next if method == "parameters"
+              next unless %w[get post put delete patch head].include?(method)
+              operation_id = operation.is_a?(Hash) ? operation["operationId"] : nil
+              insert(segments, method, operation_id)
+            end
+          end
+        end
+
+        private
+
+          def extract_json_base_path(doc)
+            servers = doc["servers"]
+            return "" unless servers.is_a?(Array) && servers.first.is_a?(Hash)
+
+            url = servers.first["url"]
+            return "" unless url
+
+            URI.parse(url).path
+          rescue URI::InvalidURIError
+            ""
+          end
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Discord::Api::PathTree" do
+    it "loads from the Discord OpenAPI spec" do
+      tree = Async::Discord::Api::PathTree.load
+
+      # channels/{id}/messages should exist
+      result = tree.match(%w[api v10 channels 123456 messages], "POST")
+      result[:valid].should == true
+      result[:operation_id].should == "create_message"
+
+      # guilds/{id} should exist
+      result = tree.match(%w[api v10 guilds 789 channels], "GET")
+      result[:valid].should == true
+
+      # users/@me should exist
+      result = tree.match(%w[api v10 users @me], "GET")
+      result[:valid].should == true
+    end
+
+    it "rejects unknown paths" do
+      tree = Async::Discord::Api::PathTree.load
+      result = tree.match(%w[api v10 totallyFake], "GET")
+      result[:valid].should == false
+    end
+
+    it "rejects wrong HTTP method" do
+      tree = Async::Discord::Api::PathTree.load
+      # GET on a POST-only endpoint
+      result = tree.match(%w[api v10 channels 123 messages], "DELETE")
+      # DELETE is not valid on /channels/{id}/messages (only GET and POST)
+      result[:valid].should == false
+    end
+
+    it "supports PATCH method (Discord uses it heavily)" do
+      tree = Async::Discord::Api::PathTree.load
+      # PATCH /channels/{id} should exist
+      result = tree.match(%w[api v10 channels 123], "PATCH")
+      result[:valid].should == true
+    end
+
+    it "inherits from Async::Matrix::Api::PathTree" do
+      Async::Discord::Api::PathTree.ancestors.should.include Async::Matrix::Api::PathTree
+    end
+
+    it "supports manual insert and match" do
+      tree = Async::Discord::Api::PathTree.new
+      tree.insert(%w[api v10 test {id} action], "post", "testAction")
+      result = tree.match(%w[api v10 test 12345 action], "POST")
+      result[:valid].should == true
+      result[:operation_id].should == "testAction"
+    end
+  end
+end

data/lib/async/discord/api.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/discord"
+require "async/matrix"
+
+module Async
+  module Discord
+    # Runtime-generated Discord HTTP API built from the official OpenAPI spec.
+    #
+    # Loads the OpenAPI 3.1.0 JSON file from data/discord-api-spec/openapi.json
+    # at require-time and builds a PathTree trie of all valid endpoints. API calls
+    # are constructed via method chains (reusing Async::Matrix::Api::Chain),
+    # validated against the tree, and terminated by .get(), .post(), .put(),
+    # .patch(), or .delete().
+    #
+    # Usage:
+    #   client.api.channels("123456").messages.post(content: "hello")
+    #   client.api.guilds("789").members.get(limit: 100)
+    #   client.api.users("@me").get
+    #
+    module Api
+      # The shared PathTree instance, loaded once from the bundled spec.
+      def self.path_tree
+        @path_tree ||= PathTree.load
+      end
+
+      # Reset the cached path tree (useful for testing or reloading).
+      def self.reset!
+        @path_tree = nil
+      end
+
+      # Gateway produces Chain instances bound to a specific Discord Client.
+      # Each call to a method on the Gateway starts a new chain.
+      class Gateway
+        def initialize(client, prefix: %w[api v10])
+          @client = client
+          @prefix = prefix
+        end
+
+        # Start a fresh chain. Every method call on the gateway creates
+        # a new chain so chains are never reused.
+        def chain
+          Async::Matrix::Api::Chain.new(
+            client: @client,
+            path_tree: Api.path_tree,
+            prefix: @prefix
+          )
+        end
+
+        # Forward all unknown methods to a fresh chain, starting the path.
+        def method_missing(name, *args, **kwargs, &block)
+          if name.start_with?("to_")
+            super
+          else
+            chain.__send__(name, *args, **kwargs, &block)
+          end
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          !name.start_with?("to_") || super
+        end
+
+        def inspect
+          "#<#{self.class} prefix=/#{@prefix.join("/")}>"
+        end
+      end
+    end
+  end
+end
+
+test do
+  describe "Async::Discord::Api::Gateway" do
+    # Stub client that records calls instead of making HTTP requests.
+    StubDiscordClient = Struct.new(:calls) do
+      def initialize
+        super([])
+      end
+
+      def get(path, max_retries: nil)
+        calls << [:get, path, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def post(path, body = {}, max_retries: nil)
+        calls << [:post, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def put(path, body = {}, max_retries: nil)
+        calls << [:put, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      def request(method, path, body = nil, max_retries: nil)
+        calls << [method.downcase.to_sym, path, body, {max_retries: max_retries}]
+        {"stub" => true}
+      end
+
+      # Chain checks for media_client on binary routes; Discord doesn't need it
+      # but we provide a stub to avoid NoMethodError.
+      def media_client
+        nil
+      end
+    end
+
+    def make_gateway
+      client = StubDiscordClient.new
+      gateway = Async::Discord::Api::Gateway.new(client)
+      [gateway, client]
+    end
+
+    it "GET /users/@me" do
+      gw, client = make_gateway
+      gw.users("@me").get
+      client.calls.last[0].should == :get
+      client.calls.last[1].should == "/api/v10/users/%40me"
+    end
+
+    it "POST /channels/{id}/messages" do
+      gw, client = make_gateway
+      gw.channels("123456").messages.post(content: "hello world")
+      client.calls.last[0].should == :post
+      client.calls.last[1].should == "/api/v10/channels/123456/messages"
+      client.calls.last[2].should == {content: "hello world"}
+    end
+
+    it "GET /guilds/{id}/channels" do
+      gw, client = make_gateway
+      gw.guilds("789").channels.get
+      client.calls.last[0].should == :get
+      client.calls.last[1].should == "/api/v10/guilds/789/channels"
+    end
+
+    it "PATCH /channels/{id} via request" do
+      gw, client = make_gateway
+      gw.channels("123456").patch(name: "new-name")
+      client.calls.last[0].should == :patch
+    end
+
+    it "each gateway method call starts a fresh chain" do
+      gw, client = make_gateway
+      gw.users("@me").get
+      gw.channels("123").messages.post(content: "hi")
+      client.calls.length.should == 2
+    end
+
+    it "raises InvalidEndpointError for unknown path" do
+      gw, _ = make_gateway
+      lambda { gw.totally.bogus.endpoint.get }.should.raise Async::Matrix::InvalidEndpointError
+    end
+  end
+end

data/lib/async/discord/client.rb

@@ -0,0 +1,286 @@
+# 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 "async/discord"
+require "json"
+require "erb"
+require "console"
+require "time"
+
+module Async
+  module Discord
+    # Async HTTP client for the Discord REST API.
+    #
+    # Authenticated with a Bot token. All methods are fiber-safe and run
+    # naturally inside Falcon's async reactor.
+    #
+    #   client = Async::Discord::Client.new(token: "MTk...")
+    #   client.api.channels("123").messages.post(content: "hello")
+    #   client.api.users("@me").get
+    #
+    class Client
+      DEFAULT_BASE_URL = "https://discord.com"
+
+      # Retry defaults
+      DEFAULT_MAX_RETRIES     = 3
+      DEFAULT_RETRY_BASE      = 0.5
+      DEFAULT_MAX_RETRY_DELAY = 30
+
+      # Status codes eligible for retry
+      RATE_LIMIT_STATUS      = 429
+      GATEWAY_ERROR_STATUSES = [502, 503, 504].freeze
+
+      # Response size limits (bytes)
+      DEFAULT_RESPONSE_SIZE_LIMIT       = 50 * 1024 * 1024   # 50 MiB
+      DEFAULT_ERROR_RESPONSE_SIZE_LIMIT = 512 * 1024          # 512 KiB
+
+      attr_reader :token
+
+      def initialize(token:, base_url: DEFAULT_BASE_URL,
+                     max_retries: DEFAULT_MAX_RETRIES,
+                     retry_base_delay: DEFAULT_RETRY_BASE,
+                     max_retry_delay: DEFAULT_MAX_RETRY_DELAY,
+                     response_size_limit: DEFAULT_RESPONSE_SIZE_LIMIT,
+                     error_response_size_limit: DEFAULT_ERROR_RESPONSE_SIZE_LIMIT)
+        @token                     = token
+        @base                      = base_url
+        @max_retries               = max_retries
+        @retry_base_delay          = retry_base_delay
+        @max_retry_delay           = max_retry_delay
+        @response_size_limit       = response_size_limit
+        @error_response_size_limit = error_response_size_limit
+        @headers = [
+          ["authorization", "Bot #{token}"],
+          ["content-type",  "application/json"],
+          ["user-agent",    "AsyncDiscord (https://github.com/general-intelligence-systems/async-matrix, 1.0)"]
+        ]
+      end
+
+      # ── Full API (runtime-generated from OpenAPI spec) ────────
+
+      # Returns a Gateway that provides method-chained access to every
+      # Discord HTTP API endpoint. Chains are validated against the official
+      # OpenAPI path tree and terminated by .get(), .post(), .put(),
+      # .patch(), or .delete().
+      #
+      #   client.api.channels("123").messages.post(content: "hello")
+      #   client.api.guilds("789").get
+      #   client.api.users("@me").get
+      #
+      def api
+        Api::Gateway.new(self)
+      end
+
+      # ── Low-level HTTP ────────────────────────────────────────
+
+      def get(path, max_retries: nil)
+        request("GET", path, nil, max_retries: max_retries)
+      end
+
+      def post(path, body = {}, max_retries: nil)
+        request("POST", path, body, max_retries: max_retries)
+      end
+
+      def put(path, body = {}, max_retries: nil)
+        request("PUT", path, body, max_retries: max_retries)
+      end
+
+      def close
+        @internet&.close
+        @internet = nil
+      end
+
+      # General-purpose request method supporting any HTTP method.
+      def request(method, path, body = nil, max_retries: nil)
+        url = "#{@base}#{path}"
+        json_body = body ? JSON.generate(body) : nil
+        effective_max_retries = max_retries || @max_retries
+
+        Console.debug(self) { "#{method} #{path}" }
+
+        attempt = 0
+        loop do
+          response = internet.call(method, url, @headers, json_body)
+          status   = response.status
+
+          if (200..299).cover?(status)
+            payload = read_limited(response, @response_size_limit)
+            return payload && !payload.empty? ? JSON.parse(payload) : {}
+          end
+
+          attempt += 1
+
+          if attempt <= effective_max_retries && retryable_status?(status)
+            delay = compute_retry_delay(status, response, attempt)
+            Console.warn(self) {
+              "#{method} #{path} returned #{status}, retry #{attempt}/#{effective_max_retries} in #{delay.round(2)}s"
+            }
+            response.close if response.respond_to?(:close)
+            sleep(delay)
+            next
+          end
+
+          payload = read_limited(response, @error_response_size_limit)
+          parsed = begin; JSON.parse(payload || "{}"); rescue; {} end
+          discord_code = parsed["code"]
+          discord_msg  = parsed["message"] || payload.to_s[0..200]
+
+          Console.error(self) { "Discord API #{status}: #{discord_code} — #{discord_msg}" }
+
+          error_class = case status
+                        when 401 then AuthError
+                        when 429 then RateLimitError
+                        when 400..499 then ApiError
+                        else ServerError
+                        end
+
+          raise error_class.new(
+            discord_code.to_s,
+            discord_msg,
+            status: status
+          )
+        end
+      end
+
+      private
+
+        def internet
+          @internet ||= Async::HTTP::Internet.new
+        end
+
+        # ── Response size limiting ──────────────────────────────
+
+        def read_limited(response, limit)
+          body = response.body
+          return nil unless body
+
+          if body.respond_to?(:length) && body.length && body.length > limit
+            body.close
+            raise ResponseTooLargeError.new(
+              "TOO_LARGE",
+              "Response Content-Length #{body.length} bytes exceeds limit of #{limit} bytes"
+            )
+          end
+
+          buffer = String.new(encoding: Encoding::BINARY)
+          body.each do |chunk|
+            buffer << chunk
+            if buffer.bytesize > limit
+              body.close
+              raise ResponseTooLargeError.new(
+                "TOO_LARGE",
+                "Response body exceeds limit of #{limit} bytes"
+              )
+            end
+          end
+          buffer.empty? ? nil : buffer
+        end
+
+        # ── Retry logic ─────────────────────────────────────────
+
+        def retryable_status?(status)
+          status == RATE_LIMIT_STATUS || GATEWAY_ERROR_STATUSES.include?(status)
+        end
+
+        # Discord sends Retry-After as seconds (float) in the JSON body on 429,
+        # and also as X-RateLimit-Reset-After header. We check both.
+        def compute_retry_delay(status, response, attempt)
+          if status == RATE_LIMIT_STATUS
+            server_delay = parse_rate_limit_delay(response)
+            delay = server_delay || exponential_delay(attempt)
+            [delay, @max_retry_delay].min
+          else
+            calculated = exponential_delay(attempt)
+            rand(0.0..[calculated, @max_retry_delay].min)
+          end
+        end
+
+        def exponential_delay(attempt)
+          @retry_base_delay * (2 ** (attempt - 1))
+        end
+
+        # Parse Discord rate limit delay. Checks:
+        #   1. X-RateLimit-Reset-After header (seconds as float)
+        #   2. Retry-After header (seconds as integer)
+        def parse_rate_limit_delay(response)
+          reset_after = response.headers["x-ratelimit-reset-after"]
+          return reset_after.to_f if reset_after
+
+          retry_after = response.headers["retry-after"]
+          return retry_after.to_f if retry_after && retry_after.strip.match?(/\A[\d.]+\z/)
+
+          nil
+        end
+
+        def encode(value)
+          ERB::Util.url_encode(value)
+        end
+    end
+  end
+end
+
+test do
+  describe "Async::Discord::Client" do
+    it "sets authorization header with Bot prefix" do
+      client = Async::Discord::Client.new(token: "test_token_123")
+      headers = client.instance_variable_get(:@headers)
+      auth = headers.find { |k, _| k == "authorization" }
+      auth[1].should == "Bot test_token_123"
+    end
+
+    it "stores the token" do
+      client = Async::Discord::Client.new(token: "my_token")
+      client.token.should == "my_token"
+    end
+
+    it "defaults base URL to discord.com" do
+      client = Async::Discord::Client.new(token: "tok")
+      client.instance_variable_get(:@base).should == "https://discord.com"
+    end
+
+    it "accepts custom base URL" do
+      client = Async::Discord::Client.new(token: "tok", base_url: "http://localhost:9999")
+      client.instance_variable_get(:@base).should == "http://localhost:9999"
+    end
+
+    it "responds to HTTP methods" do
+      client = Async::Discord::Client.new(token: "tok")
+      client.should.respond_to :get
+      client.should.respond_to :post
+      client.should.respond_to :put
+      client.should.respond_to :request
+      client.should.respond_to :close
+    end
+
+    it "responds to api" do
+      client = Async::Discord::Client.new(token: "tok")
+      client.should.respond_to :api
+    end
+
+    it "returns a Discord Api::Gateway from api" do
+      client = Async::Discord::Client.new(token: "tok")
+      client.api.should.be.kind_of Async::Discord::Api::Gateway
+    end
+
+    it "accepts custom retry configuration" do
+      client = Async::Discord::Client.new(
+        token: "tok",
+        max_retries: 5,
+        retry_base_delay: 1.0,
+        max_retry_delay: 60
+      )
+      client.instance_variable_get(:@max_retries).should == 5
+      client.instance_variable_get(:@retry_base_delay).should == 1.0
+      client.instance_variable_get(:@max_retry_delay).should == 60
+    end
+
+    it "can be closed without error" do
+      client = Async::Discord::Client.new(token: "tok")
+      lambda { client.close }.should.not.raise
+    end
+  end
+end

data/lib/async/discord/error.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "bundler/setup"
+require "async/discord"
+
+module Async
+  module Discord
+    # Base error for all Discord API errors.
+    class Error < StandardError
+      attr_reader :code, :status
+
+      def initialize(code, message, status: nil)
+        @code   = code
+        @status = status
+        super(message)
+      end
+    end
+
+    # Raised when authentication fails (401).
+    class AuthError < Error; end
+
+    # Raised on non-retryable Discord API errors (4xx).
+    class ApiError < Error; end
+
+    # Raised when rate-limited and retries are exhausted.
+    class RateLimitError < Error; end
+
+    # Raised on server errors after retries exhausted (5xx).
+    class ServerError < Error; end
+
+    # Raised when a response body exceeds the configured size limit.
+    class ResponseTooLargeError < Error; end
+
+    # Raised when the WebSocket gateway connection fails.
+    class GatewayError < Error; end
+  end
+end
+
+test do
+  describe "Async::Discord::Error" do
+    it "stores code and message" do
+      err = Async::Discord::Error.new("DISCORD_ERROR", "something broke")
+      err.code.should == "DISCORD_ERROR"
+      err.message.should == "something broke"
+    end
+
+    it "stores optional status" do
+      err = Async::Discord::Error.new("ERR", "fail", status: 400)
+      err.status.should == 400
+    end
+
+    it "defaults status to nil" do
+      err = Async::Discord::Error.new("ERR", "fail")
+      err.status.should.be.nil
+    end
+
+    it "is a StandardError" do
+      Async::Discord::Error.new("ERR", "fail").should.be.kind_of StandardError
+    end
+  end
+
+  it "AuthError inherits from Error" do
+    Async::Discord::AuthError.new("AUTH", "bad token").should.be.kind_of Async::Discord::Error
+  end
+
+  it "ApiError inherits from Error" do
+    Async::Discord::ApiError.new("API", "bad request").should.be.kind_of Async::Discord::Error
+  end
+
+  it "RateLimitError inherits from Error" do
+    Async::Discord::RateLimitError.new("RATE", "slow down").should.be.kind_of Async::Discord::Error
+  end
+
+  it "ServerError inherits from Error" do
+    Async::Discord::ServerError.new("SERVER", "500").should.be.kind_of Async::Discord::Error
+  end
+
+  it "ResponseTooLargeError inherits from Error" do
+    Async::Discord::ResponseTooLargeError.new("LARGE", "too big").should.be.kind_of Async::Discord::Error
+  end
+
+  it "GatewayError inherits from Error" do
+    Async::Discord::GatewayError.new("GW", "disconnected").should.be.kind_of Async::Discord::Error
+  end
+end