feat: implement queue routing and worker subscription model

[niteshpurohit]

• Introduced a new Subscription class to manage worker queue and handler subscriptions.
• Updated worker reserve logic to match jobs based on both queue and handler criteria.
• Enhanced error handling for duplicate queue and handler names.
• Improved documentation to clarify the new routing and subscription behavior.
• Added tests to validate subscription functionality and error handling.

closes: #38

[Copilot]

Pull request overview

Implements queue routing and a worker subscription model so reservation only occurs when both the job’s queue and handler match what a worker has subscribed to, establishing a stable routing boundary for later reliability features.

Changes:

• Added Worker::Subscription and wired workers to reserve jobs using (queues, handler_names) matching rather than queue-only matching.
• Updated the in-memory queue store’s reserve API to support subscription-aware scans and queue-order preference.
• Tightened validation and documentation around duplicate/empty queue and handler configurations, with expanded test coverage.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/pages/runtime/workers.md	Documents explicit routing + subscription matching behavior.
docs/pages/runtime/job-model.md	Clarifies reserve semantics now respect subscription boundaries.
core/karya/README.md	Summarizes new routing/subscription model at the library level.
core/karya/lib/karya/worker/subscription.rb	Introduces immutable-ish subscription object for queue+handler matching.
core/karya/lib/karya/worker.rb	Switches worker reserve logic to subscription-aware reserve call.
core/karya/lib/karya/worker/configuration.rb	Builds and exposes subscription derived from queues + handler registry.
core/karya/lib/karya/worker/handler_registry.rb	Adds empty-handlers validation and exposes normalized handler names.
core/karya/lib/karya/worker_supervisor/handler_mapping.rb	Adds empty-handlers validation for supervisor handler mapping.
core/karya/lib/karya/queue_store/in_memory.rb	Implements subscription-aware reserve scanning across queues + handlers.
core/karya/lib/karya/queue_store/base.rb	Updates reserve contract to accept queue(s) + handler_names inputs.
core/karya/lib/karya/primitives/queue_list.rb	Enforces uniqueness of queues after normalization.
core/karya/lib/karya/cli/mapping_entry.rb	Rejects duplicate handler mappings at CLI parse time.
core/karya/lib/karya/cli/handler_parser.rb	Wires duplicate handler mapping errors to Thor::Error.
core/karya/sig/karya/worker/subscription.rbs	Adds RBS for new subscription class.
core/karya/sig/karya/worker.rbs	Exposes Worker#subscription in RBS.
core/karya/sig/karya/queue_store/base.rbs	Updates reserve signature for subscription-aware inputs.
core/karya/sig/karya/queue_store/in_memory.rbs	Updates reserve + adds HandlerMatcher typing.
core/karya/spec/...	Adds/updates tests for subscription matching, duplicates, and queue store reserve behavior.
core/karya/.reek.yml	Excludes new matcher method(s) from select smells.

Comments suppressed due to low confidence (2)

core/karya/lib/karya/worker_supervisor/handler_mapping.rb:23

• HandlerMapping#normalize can silently overwrite handlers when two keys normalize to the same handler name (e.g., 'billing_sync' and ' billing_sync '). This makes configuration errors hard to detect and can route jobs to the wrong handler. Consider detecting normalized key collisions and raising InvalidWorkerSupervisorConfigurationError listing the duplicate normalized handler name(s).

      def normalize
        raise InvalidWorkerSupervisorConfigurationError, 'handlers must be a Hash' unless value.is_a?(Hash)
        raise InvalidWorkerSupervisorConfigurationError, 'handlers must be present' if value.empty?

        value.each_with_object({}) do |(name, handler), normalized|
          normalized_name = Primitives::Identifier.new(:handler, name, error_class: InvalidWorkerSupervisorConfigurationError).normalize
          normalized[normalized_name] = handler
        end.freeze

core/karya/lib/karya/worker/handler_registry.rb:18

• HandlerRegistry#normalize currently overwrites entries when multiple input keys normalize to the same handler name, which can silently drop a handler mapping and produce a subscription that doesn’t reflect the intended configuration. Consider detecting normalized-name collisions and raising InvalidWorkerConfigurationError (similar to how duplicate queue names are rejected).

      def initialize(value)
        raise InvalidWorkerConfigurationError, 'handlers must be a Hash' unless value.is_a?(Hash)
        raise InvalidWorkerConfigurationError, 'handlers must be present' if value.empty?

        @value = value
        @normalized_handlers = normalize
      end

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated no new comments.