async-matrix 0.1.3 → 1.0.0

data/lib/async/matrix/application_service/config/schema/encryption.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "encryption.json",
+  "description": "End-to-end encryption settings. Maps to mautrix bridgev2/bridgeconfig.EncryptionConfig.",
+  "type": "object",
+  "properties": {
+    "allow": {
+      "type": "boolean",
+      "default": false,
+      "description": "Allow encryption in portal rooms."
+    },
+    "default": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable encryption in new portal rooms by default."
+    },
+    "require": {
+      "type": "boolean",
+      "default": false,
+      "description": "Require encryption — drop messages in unencrypted rooms."
+    },
+    "appservice": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable appservice-level encryption (MSC3202)."
+    },
+    "msc4190": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable device management via MSC4190."
+    },
+    "msc4392": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable MSC4392 support."
+    },
+    "self_sign": {
+      "type": "boolean",
+      "default": false,
+      "description": "Self-sign the bridge device's keys."
+    },
+    "plaintext_mentions": {
+      "type": "boolean",
+      "default": false,
+      "description": "Include plaintext mentions alongside encrypted content."
+    },
+    "pickle_key": {
+      "type": "string",
+      "description": "Key for pickling Olm sessions. Set to 'generate' for auto-generation."
+    },
+    "allow_key_sharing": {
+      "type": "boolean",
+      "default": false,
+      "description": "Allow sharing Megolm keys with verified devices on request."
+    },
+    "delete_keys": {
+      "$ref": "#/$defs/DeleteKeys"
+    },
+    "verification_levels": {
+      "$ref": "#/$defs/VerificationLevels"
+    },
+    "rotation": {
+      "$ref": "#/$defs/Rotation"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "DeleteKeys": {
+      "description": "Key deletion policy settings.",
+      "type": "object",
+      "properties": {
+        "delete_outbound_on_ack": {
+          "type": "boolean",
+          "default": false,
+          "description": "Delete outbound sessions after all devices have acknowledged."
+        },
+        "dont_store_outbound": {
+          "type": "boolean",
+          "default": false,
+          "description": "Don't store outbound sessions at all."
+        },
+        "ratchet_on_decrypt": {
+          "type": "boolean",
+          "default": false,
+          "description": "Ratchet inbound sessions forward after decrypting a message."
+        },
+        "delete_fully_used_on_decrypt": {
+          "type": "boolean",
+          "default": false,
+          "description": "Delete inbound sessions that have been fully used after decryption."
+        },
+        "delete_prev_on_new_session": {
+          "type": "boolean",
+          "default": false,
+          "description": "Delete previous inbound session when a new one is received."
+        },
+        "delete_on_device_delete": {
+          "type": "boolean",
+          "default": false,
+          "description": "Delete keys associated with a device when that device is deleted."
+        },
+        "periodically_delete_expired": {
+          "type": "boolean",
+          "default": false,
+          "description": "Periodically delete expired inbound sessions."
+        },
+        "delete_outdated_inbound": {
+          "type": "boolean",
+          "default": false,
+          "description": "Delete outdated inbound sessions."
+        }
+      },
+      "additionalProperties": false
+    },
+    "VerificationLevels": {
+      "description": "Minimum verification trust levels for various operations.",
+      "type": "object",
+      "properties": {
+        "receive": {
+          "type": "string",
+          "description": "Minimum trust level for receiving messages."
+        },
+        "send": {
+          "type": "string",
+          "description": "Minimum trust level for sending messages."
+        },
+        "share": {
+          "type": "string",
+          "description": "Minimum trust level for sharing keys."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Rotation": {
+      "description": "Megolm session rotation settings.",
+      "type": "object",
+      "properties": {
+        "enable_custom": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable custom rotation settings (otherwise use server defaults)."
+        },
+        "milliseconds": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 604800000,
+          "description": "Rotate sessions after this many milliseconds."
+        },
+        "messages": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 100,
+          "description": "Rotate sessions after this many messages."
+        },
+        "disable_device_change_key_rotation": {
+          "type": "boolean",
+          "default": false,
+          "description": "Don't rotate keys when a device list changes."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

data/lib/async/matrix/application_service/config/schema/homeserver.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "homeserver.json",
+  "description": "Homeserver connection settings. Maps to mautrix bridgev2/bridgeconfig.HomeserverConfig.",
+  "type": "object",
+  "properties": {
+    "address": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The URL of the homeserver's client-server API (e.g. http://synapse:8008)."
+    },
+    "domain": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The server_name of the homeserver (e.g. example.com)."
+    },
+    "async_media": {
+      "type": "boolean",
+      "default": false,
+      "description": "Does the homeserver support asynchronous media uploads (MSC2246)?"
+    },
+    "public_address": {
+      "type": "string",
+      "description": "Public-facing base URL if the homeserver's API is behind a reverse proxy."
+    },
+    "software": {
+      "type": "string",
+      "enum": ["standard", "asmux", "hungry"],
+      "default": "standard",
+      "description": "The type of homeserver software (standard, asmux, or hungry)."
+    },
+    "status_endpoint": {
+      "type": "string",
+      "description": "URL to push bridge status updates to."
+    },
+    "message_send_checkpoint_endpoint": {
+      "type": "string",
+      "description": "URL to push message send checkpoints to."
+    },
+    "websocket": {
+      "type": "boolean",
+      "default": false,
+      "description": "Use websocket appservice transactions instead of HTTP."
+    },
+    "websocket_proxy": {
+      "type": "string",
+      "description": "HTTP proxy URL for the websocket connection."
+    },
+    "ping_interval_seconds": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Interval in seconds between websocket pings. 0 disables."
+    }
+  },
+  "required": ["address", "domain"],
+  "additionalProperties": false
+}

data/lib/async/matrix/application_service/config/schema/logging.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "logging.json",
+  "description": "Logging configuration. Maps to go.mau.fi/zeroconfig.Config (zerolog-based). Kept permissive since the full zeroconfig schema is external.",
+  "type": "object",
+  "properties": {
+    "min_level": {
+      "type": "string",
+      "enum": ["trace", "debug", "info", "warn", "error", "fatal"],
+      "default": "debug",
+      "description": "Minimum log level."
+    },
+    "writers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Writer type (e.g. 'stdout', 'file')."
+          },
+          "format": {
+            "type": "string",
+            "enum": ["pretty-colored", "pretty", "json"],
+            "description": "Log output format."
+          },
+          "filename": {
+            "type": "string",
+            "description": "Log file path (for file writer type)."
+          },
+          "max_size": {
+            "type": "integer",
+            "description": "Maximum log file size in bytes before rotation."
+          },
+          "max_backups": {
+            "type": "integer",
+            "description": "Maximum number of old log files to keep."
+          },
+          "compress": {
+            "type": "boolean",
+            "description": "Compress rotated log files."
+          }
+        },
+        "additionalProperties": true
+      },
+      "description": "Log output writers."
+    }
+  },
+  "additionalProperties": true
+}

data/lib/async/matrix/application_service/config/schema/management_room_texts.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "management_room_texts.json",
+  "description": "Management room message templates. Maps to mautrix bridgev2/bridgeconfig.ManagementRoomTexts.",
+  "type": "object",
+  "properties": {
+    "welcome": {
+      "type": "string",
+      "description": "Welcome message sent when a user opens the management room."
+    },
+    "welcome_connected": {
+      "type": "string",
+      "description": "Welcome message variant for users who are already connected."
+    },
+    "welcome_unconnected": {
+      "type": "string",
+      "description": "Welcome message variant for users who are not yet connected."
+    },
+    "additional_help": {
+      "type": "string",
+      "description": "Additional help text appended to the help command output."
+    }
+  },
+  "additionalProperties": false
+}

data/lib/async/matrix/application_service/config/schema/matrix.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "matrix.json",
+  "description": "Matrix protocol behavior settings. Maps to mautrix bridgev2/bridgeconfig.MatrixConfig.",
+  "type": "object",
+  "properties": {
+    "message_status_events": {
+      "type": "boolean",
+      "default": false,
+      "description": "Send message status events (MSC3381) for bridge message processing."
+    },
+    "delivery_receipts": {
+      "type": "boolean",
+      "default": false,
+      "description": "Send delivery receipts after successfully bridging a message."
+    },
+    "message_error_notices": {
+      "type": "boolean",
+      "default": true,
+      "description": "Send error notices to the room when a message fails to bridge."
+    },
+    "sync_direct_chat_list": {
+      "type": "boolean",
+      "default": false,
+      "description": "Sync the m.direct account data event with bridged DM rooms."
+    },
+    "federate_rooms": {
+      "type": "boolean",
+      "default": true,
+      "description": "Allow portal rooms to federate."
+    },
+    "upload_file_threshold": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 5242880,
+      "description": "Maximum file size in bytes to upload directly (default 5 MiB)."
+    },
+    "ghost_extra_profile_info": {
+      "type": "boolean",
+      "default": false,
+      "description": "Set extra profile info (e.g. identifiers) on ghost users."
+    }
+  },
+  "additionalProperties": false
+}

data/lib/async/matrix/application_service/config/schema/permissions.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "permissions.json",
+  "description": "Permission level definition. Maps to mautrix bridgev2/bridgeconfig.Permissions. Used as values in the bridge.permissions map.",
+  "oneOf": [
+    {
+      "type": "string",
+      "enum": ["block", "relay", "commands", "user", "admin"],
+      "description": "Named permission preset."
+    },
+    {
+      "type": "object",
+      "properties": {
+        "send_events": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow bridging events from the remote network to Matrix."
+        },
+        "commands": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow using bridge commands."
+        },
+        "login": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow logging into the bridge."
+        },
+        "double_puppet": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow enabling double-puppeting."
+        },
+        "admin": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow bridge administration commands."
+        },
+        "manage_relay": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow managing relay mode."
+        },
+        "max_logins": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Maximum number of simultaneous logins. 0 means unlimited."
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

data/lib/async/matrix/application_service/config/schema/provisioning.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "provisioning.json",
+  "description": "Provisioning API settings. Maps to mautrix bridgev2/bridgeconfig.ProvisioningConfig.",
+  "type": "object",
+  "properties": {
+    "shared_secret": {
+      "type": "string",
+      "description": "Shared secret for provisioning API authentication. Set to 'generate' for auto-generation."
+    },
+    "debug_endpoints": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable debug/profiling endpoints on the provisioning API."
+    },
+    "enable_session_transfers": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable transferring login sessions between devices."
+    }
+  },
+  "additionalProperties": false
+}

data/lib/async/matrix/application_service/config/schema/public_media.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "public_media.json",
+  "description": "Public media proxy settings. Maps to mautrix bridgev2/bridgeconfig.PublicMediaConfig.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable the public media proxy."
+    },
+    "signing_key": {
+      "type": "string",
+      "description": "Signing key for public media URLs. Set to 'generate' for auto-generation."
+    },
+    "expiry": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Expiry time for public media URLs in seconds. 0 means no expiry."
+    },
+    "hash_length": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 32,
+      "description": "Length of the hash in public media URLs."
+    },
+    "path_prefix": {
+      "type": "string",
+      "description": "URL path prefix for the public media endpoint."
+    },
+    "use_database": {
+      "type": "boolean",
+      "default": false,
+      "description": "Store public media URL mappings in the database."
+    }
+  },
+  "additionalProperties": false
+}

data/lib/async/matrix/application_service/config/schema/relay.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "relay.json",
+  "description": "Relay mode settings. Maps to mautrix bridgev2/bridgeconfig.RelayConfig.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable relay mode for bridging messages from non-logged-in users."
+    },
+    "admin_only": {
+      "type": "boolean",
+      "default": false,
+      "description": "Only allow admins to enable relay mode in a room."
+    },
+    "prefer_default": {
+      "type": "boolean",
+      "default": false,
+      "description": "Prefer default relays over room-specific relays."
+    },
+    "allow_bridge": {
+      "type": "boolean",
+      "default": false,
+      "description": "Allow relayed bridging of messages."
+    },
+    "default_relays": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Default user login IDs to use for relaying."
+    },
+    "message_formats": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Go text/template strings for formatting relayed messages, keyed by message type (e.g. 'm.text')."
+    },
+    "displayname_format": {
+      "type": "string",
+      "description": "Go text/template string for formatting relayed displaynames."
+    }
+  },
+  "additionalProperties": false
+}

data/lib/async/matrix/application_service/config/vivify.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    module ApplicationService
+      class Config
+        # Mixin that gives a Hash dot-notation accessors with autovivification.
+        #
+        # Not applied globally — only extended onto the validated config hash
+        # and its nested children so the rest of the world is unaffected.
+        #
+        #   h = {}.extend(Vivify)
+        #   h.foo.bar.baz = 42
+        #   h  # => { foo: { bar: { baz: 42 } } }
+        #
+        module Vivify
+          def method_missing(name, *args)
+            key = name.to_s
+
+            if key.end_with?("=")
+              self[key.chomp("=").to_sym] = args.first
+            elsif key?(name.to_sym)
+              self[name.to_sym]
+            elsif key.start_with?("to_")
+              super
+            else
+              self[name.to_sym] = {}.extend(Vivify)
+            end
+          end
+
+          def respond_to_missing?(name, _priv = false)
+            name.to_s.end_with?("=") || key?(name.to_sym) || super
+          end
+
+          # Recursively symbolize keys and extend every nested Hash with Vivify.
+          #
+          # Call this on the raw (string-keyed) hash that comes out of
+          # YAML.safe_load / JSON Schema validation before wrapping it in Config.
+          def self.deep_vivify(obj)
+            case obj
+            when Hash
+              result = {}
+              obj.each { |k, v| result[k.to_s.to_sym] = deep_vivify(v) }
+              result.extend(Vivify)
+            when Array
+              obj.map { |v| deep_vivify(v) }
+            else
+              obj
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+test do
+  V = Async::Matrix::ApplicationService::Config::Vivify
+
+  describe "Vivify" do
+    it "provides dot-notation read access to symbol keys" do
+      h = { foo: "bar" }.extend(V)
+      h.foo.should == "bar"
+    end
+
+    it "provides dot-notation write access" do
+      h = {}.extend(V)
+      h.foo = 42
+      h[:foo].should == 42
+    end
+
+    it "autovivifies missing keys as vivified hashes" do
+      h = {}.extend(V)
+      h.a.b.c = "deep"
+      h[:a][:b][:c].should == "deep"
+    end
+
+    it "delegates to_* methods to super (no autovivify)" do
+      h = { x: 1 }.extend(V)
+      h.to_a.should == [[:x, 1]]
+    end
+  end
+
+  describe "Vivify.deep_vivify" do
+    it "symbolizes string keys" do
+      result = V.deep_vivify({"a" => 1})
+      result[:a].should == 1
+    end
+
+    it "recursively vivifies nested hashes" do
+      result = V.deep_vivify({"outer" => {"inner" => "val"}})
+      result.outer.inner.should == "val"
+    end
+
+    it "vivifies hashes inside arrays" do
+      result = V.deep_vivify({"list" => [{"name" => "x"}]})
+      result.list.first.name.should == "x"
+    end
+
+    it "passes scalars through unchanged" do
+      result = V.deep_vivify({"n" => 42, "s" => "hi", "b" => true})
+      result.n.should == 42
+      result.s.should == "hi"
+      result.b.should == true
+    end
+  end
+end