mailbox-kit 0.1.0

data/lib/mailbox_kit/tenancy.rb

@@ -0,0 +1,76 @@
+require "mailbox_kit/error"
+
+module MailboxKit
+  # An adapter boundary: the host owns tenant discovery and connection switching.
+  # Configure once, before requiring any optional Active Record models.
+  module Tenancy
+    CONTEXT_KEY = :cloudflare_email_tenant_key
+
+    class << self
+      def configure(base_class:, switch:, current:)
+        raise ConfigurationError, "configure tenancy before loading Mailbox Kit models" if @models_loaded
+        raise ConfigurationError, "tenancy is already configured" if enabled?
+        unless base_class.is_a?(Class) && base_class.respond_to?(:abstract_class?) && base_class.abstract_class?
+          raise ConfigurationError, "base_class must be an abstract Active Record class"
+        end
+        unless switch.respond_to?(:call) && current.respond_to?(:call)
+          raise ConfigurationError, "switch and current must be callable"
+        end
+
+        @base_class, @switch, @current = base_class, switch, current
+        self
+      end
+
+      def enabled?
+        !@switch.nil?
+      end
+
+      def model_base(default)
+        @models_loaded = true
+        @base_class || default
+      end
+
+      def current_key
+        Thread.current[CONTEXT_KEY]
+      end
+
+      # Only trusted host integration code should use this to capture new work.
+      # Model access and persisted job deserialization still require explicit
+      # gem context; the adapter must not invent a default tenant here.
+      def host_current_key
+        return unless enabled?
+        key = @current.call
+        normalize_key(key) unless key.nil?
+      end
+
+      def normalize_key(key)
+        unless key.is_a?(String) && !key.empty? && key == key.strip && !key.match?(/[[:cntrl:]]/)
+          raise ConfigurationError, "tenant key must be a nonempty string without surrounding whitespace or control characters"
+        end
+        key.dup.freeze
+      end
+
+      def require_context!
+        key = current_key
+        raise ConfigurationError, "an explicit Mailbox Kit tenant context is required" unless key
+        if enabled? && @current.call != key
+          raise ConfigurationError, "host database tenant does not match Mailbox Kit tenant context"
+        end
+        key
+      end
+
+      def with(key)
+        key = normalize_key(key)
+        previous = current_key
+        run = proc do
+          Thread.current[CONTEXT_KEY] = key
+          require_context!
+          yield
+        ensure
+          Thread.current[CONTEXT_KEY] = previous
+        end
+        enabled? ? @switch.call(key, &run) : run.call
+      end
+    end
+  end
+end

data/lib/mailbox_kit/tenant_job_context.rb

@@ -0,0 +1,88 @@
+require "mailbox_kit/tenancy"
+
+module MailboxKit
+    # Opt in with `prepend MailboxKit::TenantJobContext` on jobs whose
+    # arguments or work reference tenant records. Queue payloads must be trusted.
+    module TenantJobContext
+      PAYLOAD_KEY = "cloudflare_email_tenant_key".freeze
+
+      def serialize
+        key = cloudflare_email_job_tenant_key
+        return super unless key
+        Tenancy.with(key) do
+          payload = super
+          verify_cloudflare_email_host_tenant!(key, payload["tenant"])
+          payload.merge(PAYLOAD_KEY => key)
+        end
+      end
+
+      def deserialize(job_data)
+        # Bind before super: host job integrations may deserialize model arguments
+        # eagerly. Never infer a missing tenant from the worker's ambient context.
+        if !job_data.key?(PAYLOAD_KEY) && cloudflare_email_optional_job_context?
+          @cloudflare_email_job_tenant_key = nil
+          return super
+        end
+        @cloudflare_email_job_tenant_key = Tenancy.normalize_key(job_data[PAYLOAD_KEY])
+        verify_cloudflare_email_host_tenant!(@cloudflare_email_job_tenant_key, job_data["tenant"])
+        Tenancy.with(@cloudflare_email_job_tenant_key) { super }
+      end
+
+      def perform_now
+        # Active Job resolves GlobalIDs before around_perform, so that callback
+        # cannot safely implement database tenant selection.
+        key = cloudflare_email_job_tenant_key
+        return super unless key
+        if defined?(::ActiveRecord::Tenanted::Job) && respond_to?(:tenant)
+          verify_cloudflare_email_host_tenant!(key, tenant)
+        end
+        Tenancy.with(key) { super }
+      end
+
+      def self.install_framework_jobs!
+        if defined?(::ActionMailbox)
+          %i[RoutingJob IncinerationJob].each do |name|
+            next unless ::ActionMailbox.const_defined?(name)
+            klass = ::ActionMailbox.const_get(name)
+            klass.define_singleton_method(:cloudflare_email_optional_job_context?) { !Tenancy.enabled? }
+            klass.prepend(self) unless klass.ancestors.include?(self)
+          end
+        end
+        if defined?(::ActiveStorage)
+          %i[BaseJob AnalyzeJob PurgeJob MirrorJob TransformJob PreviewImageJob].each do |name|
+            next unless ::ActiveStorage.const_defined?(name)
+            klass = ::ActiveStorage.const_get(name)
+            klass.define_singleton_method(:cloudflare_email_optional_job_context?) { !Tenancy.enabled? }
+            klass.prepend(self) unless klass.ancestors.include?(self)
+          end
+        end
+      end
+
+      private
+
+      def cloudflare_email_job_tenant_key
+        # Once serialized/deserialized, retries retain their original tenant even
+        # if re-enqueued from a different tenant or outside a tenant context.
+        return @cloudflare_email_job_tenant_key if instance_variable_defined?(:@cloudflare_email_job_tenant_key)
+        return nil if cloudflare_email_optional_job_context? && !Tenancy.current_key
+        # Native uploads/mailbox work may originate in the host's own with_tenant
+        # block. Framework jobs can capture that trusted context on first use.
+        # deserialize never takes this path for missing persisted metadata.
+        if !Tenancy.current_key && self.class.respond_to?(:cloudflare_email_optional_job_context?)
+          key = Tenancy.host_current_key
+          return @cloudflare_email_job_tenant_key = key if key
+        end
+        @cloudflare_email_job_tenant_key = Tenancy.require_context!
+      end
+
+      def cloudflare_email_optional_job_context?
+        self.class.respond_to?(:cloudflare_email_optional_job_context?) && self.class.cloudflare_email_optional_job_context?
+      end
+
+      def verify_cloudflare_email_host_tenant!(key, host_key)
+        if host_key && host_key != key
+          raise ConfigurationError, "job host tenant conflicts with Mailbox Kit tenant context"
+        end
+      end
+    end
+  end

data/lib/mailbox_kit/version.rb

@@ -0,0 +1,3 @@
+module MailboxKit
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: mailbox-kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cole
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Provider-neutral mailbox identities, aliases, memberships, retention,
+  optional tenancy, and a server-rendered management engine built on Rails Action
+  Mailbox.
+email:
+- cole@dscribeai.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- app/controllers/mailbox_kit/management/mailboxes_controller.rb
+- app/controllers/mailbox_kit/management/styles_controller.rb
+- app/views/layouts/mailbox_kit/management.html.erb
+- app/views/mailbox_kit/management/mailboxes/index.html.erb
+- app/views/mailbox_kit/management/mailboxes/message.html.erb
+- app/views/mailbox_kit/management/mailboxes/show.html.erb
+- docs/integration.md
+- docs/upgrading.md
+- lib/generators/mailbox_kit/install/install_generator.rb
+- lib/generators/mailbox_kit/install/templates/create_mailbox_kit_mailboxes.rb
+- lib/generators/mailbox_kit/install/templates/create_mailbox_kit_receiving_domains.rb
+- lib/generators/mailbox_kit/upgrade/templates/allow_provider_neutral_receiving_domains.rb
+- lib/generators/mailbox_kit/upgrade/templates/index_mailbox_kit_inbound_messages.rb
+- lib/generators/mailbox_kit/upgrade/upgrade_generator.rb
+- lib/mailbox-kit.rb
+- lib/mailbox_kit/active_record/base.rb
+- lib/mailbox_kit/address_syntax.rb
+- lib/mailbox_kit/error.rb
+- lib/mailbox_kit/inbound_email.rb
+- lib/mailbox_kit/mailboxes.rb
+- lib/mailbox_kit/mailboxes/configuration.rb
+- lib/mailbox_kit/mailboxes/inbound_retention.rb
+- lib/mailbox_kit/mailboxes/models.rb
+- lib/mailbox_kit/mailboxes/service.rb
+- lib/mailbox_kit/management.rb
+- lib/mailbox_kit/management/adapter.rb
+- lib/mailbox_kit/management/configuration.rb
+- lib/mailbox_kit/management/engine.rb
+- lib/mailbox_kit/management/management.css
+- lib/mailbox_kit/management/routes.rb
+- lib/mailbox_kit/railtie.rb
+- lib/mailbox_kit/tenancy.rb
+- lib/mailbox_kit/tenant_job_context.rb
+- lib/mailbox_kit/version.rb
+homepage: https://github.com/cole-robertson/cloudflare-email
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/cole-robertson/cloudflare-email/tree/main/mailbox-kit
+  changelog_uri: https://github.com/cole-robertson/cloudflare-email/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/cole-robertson/cloudflare-email/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Persistent inboxes and management UI built on Rails Action Mailbox.
+test_files: []