mirror of
https://github.com/chatwoot/chatwoot.git
synced 2026-07-13 21:08:19 +08:00
## Linear Link
## Description
This PR introduces a new robust auto-assignment system for conversations
in Chatwoot. The system replaces the existing round-robin assignment
with a more sophisticated service-based architecture that supports
multiple assignment strategies, rate limiting, and Enterprise features
like capacity-based assignment and balanced distribution.
## Type of change
- [ ] New feature (non-breaking change which adds functionality)
## How Has This Been Tested?
- Unit test cases
- Test conversations getting assigned on status change to open
- Test the job directly via rails console
## Checklist:
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Adds a new service-based auto-assignment system with scheduled jobs,
rate limiting, enterprise capacity/balanced selection, and wiring via
inbox/handler; includes Redis helpers and comprehensive tests.
>
> - **Auto-assignment v2 (core services)**:
> - Add `AutoAssignment::AssignmentService` with bulk assignment,
configurable conversation priority, RR selection, and per-agent rate
limiting via `AutoAssignment::RateLimiter`.
> - Add `AutoAssignment::RoundRobinSelector` for agent selection.
> - **Jobs & scheduling**:
> - Add `AutoAssignment::AssignmentJob` (per-inbox bulk assign;
env-based limit) and `AutoAssignment::PeriodicAssignmentJob` (batch over
accounts/inboxes).
> - Schedule periodic run in `config/schedule.yml`
(`periodic_assignment_job`).
> - **Model/concerns wiring**:
> - Include `InboxAgentAvailability` in `Inbox`; add
`Inbox#auto_assignment_v2_enabled?`.
> - Update `AutoAssignmentHandler` to trigger v2 job when
`auto_assignment_v2_enabled?`, else fallback to legacy.
> - **Enterprise extensions**:
> - Add `Enterprise::InboxAgentAvailability` (capacity-aware filtering)
and `Enterprise::Concerns::Inbox` association `inbox_capacity_limits`.
> - Extend service via `Enterprise::AutoAssignment::AssignmentService`
(policy-driven config, capacity filtering, exclusion rules) and add
selectors/services: `BalancedSelector`, `CapacityService`.
> - **Infrastructure**:
> - Enhance `Redis::Alfred` with `expire`, key scan/count, and extended
ZSET helpers (`zadd`, `zcount`, `zcard`, `zrangebyscore`).
> - **Tests**:
> - Add specs for jobs, core service, rate limiter, RR selector, and
enterprise features (capacity, balanced selection, exclusions).
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
0ebe187c8a. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>
Co-authored-by: Shivam Mishra <scm.mymail@gmail.com>
168 lines
5.3 KiB
Ruby
168 lines
5.3 KiB
Ruby
require 'rails_helper'
|
|
|
|
RSpec.describe AutoAssignment::RateLimiter do
|
|
# Stub Math methods for testing when assignment_policy is nil
|
|
# rubocop:disable RSpec/BeforeAfterAll, RSpec/InstanceVariable
|
|
before(:all) do
|
|
@math_had_positive = Math.respond_to?(:positive?)
|
|
Math.define_singleton_method(:positive?) { false } unless @math_had_positive
|
|
end
|
|
|
|
after(:all) do
|
|
Math.singleton_class.send(:remove_method, :positive?) unless @math_had_positive
|
|
end
|
|
# rubocop:enable RSpec/BeforeAfterAll, RSpec/InstanceVariable
|
|
|
|
let(:account) { create(:account) }
|
|
let(:inbox) { create(:inbox, account: account) }
|
|
let(:agent) { create(:user, account: account, role: :agent) }
|
|
let(:conversation) { create(:conversation, inbox: inbox) }
|
|
let(:rate_limiter) { described_class.new(inbox: inbox, agent: agent) }
|
|
|
|
describe '#within_limit?' do
|
|
context 'when rate limiting is not enabled' do
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(nil)
|
|
end
|
|
|
|
it 'returns true' do
|
|
expect(rate_limiter.within_limit?).to be true
|
|
end
|
|
end
|
|
|
|
context 'when rate limiting is enabled' do
|
|
let(:assignment_policy) do
|
|
instance_double(AssignmentPolicy,
|
|
fair_distribution_limit: 5,
|
|
fair_distribution_window: 3600)
|
|
end
|
|
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
|
|
end
|
|
|
|
it 'returns true when under the limit' do
|
|
allow(rate_limiter).to receive(:current_count).and_return(3)
|
|
expect(rate_limiter.within_limit?).to be true
|
|
end
|
|
|
|
it 'returns false when at or over the limit' do
|
|
allow(rate_limiter).to receive(:current_count).and_return(5)
|
|
expect(rate_limiter.within_limit?).to be false
|
|
end
|
|
end
|
|
end
|
|
|
|
describe '#track_assignment' do
|
|
context 'when rate limiting is not enabled' do
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(nil)
|
|
end
|
|
|
|
it 'does not track the assignment' do
|
|
expect(Redis::Alfred).not_to receive(:set)
|
|
rate_limiter.track_assignment(conversation)
|
|
end
|
|
end
|
|
|
|
context 'when rate limiting is enabled' do
|
|
let(:assignment_policy) do
|
|
instance_double(AssignmentPolicy,
|
|
fair_distribution_limit: 5,
|
|
fair_distribution_window: 3600)
|
|
end
|
|
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
|
|
end
|
|
|
|
it 'creates a Redis key with correct expiry' do
|
|
expected_key = format(Redis::RedisKeys::ASSIGNMENT_KEY, inbox_id: inbox.id, agent_id: agent.id, conversation_id: conversation.id)
|
|
expect(Redis::Alfred).to receive(:set).with(
|
|
expected_key,
|
|
conversation.id.to_s,
|
|
ex: 3600
|
|
)
|
|
rate_limiter.track_assignment(conversation)
|
|
end
|
|
end
|
|
end
|
|
|
|
describe '#current_count' do
|
|
context 'when rate limiting is not enabled' do
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(nil)
|
|
end
|
|
|
|
it 'returns 0' do
|
|
expect(rate_limiter.current_count).to eq(0)
|
|
end
|
|
end
|
|
|
|
context 'when rate limiting is enabled' do
|
|
let(:assignment_policy) do
|
|
instance_double(AssignmentPolicy,
|
|
fair_distribution_limit: 5,
|
|
fair_distribution_window: 3600)
|
|
end
|
|
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
|
|
end
|
|
|
|
it 'counts matching Redis keys' do
|
|
pattern = format(Redis::RedisKeys::ASSIGNMENT_KEY_PATTERN, inbox_id: inbox.id, agent_id: agent.id)
|
|
allow(Redis::Alfred).to receive(:keys_count).with(pattern).and_return(3)
|
|
|
|
expect(rate_limiter.current_count).to eq(3)
|
|
end
|
|
end
|
|
end
|
|
|
|
describe 'configuration' do
|
|
context 'with custom window' do
|
|
let(:assignment_policy) do
|
|
instance_double(AssignmentPolicy,
|
|
fair_distribution_limit: 10,
|
|
fair_distribution_window: 7200)
|
|
end
|
|
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
|
|
end
|
|
|
|
it 'uses the custom window value' do
|
|
expected_key = format(Redis::RedisKeys::ASSIGNMENT_KEY, inbox_id: inbox.id, agent_id: agent.id, conversation_id: conversation.id)
|
|
expect(Redis::Alfred).to receive(:set).with(
|
|
expected_key,
|
|
conversation.id.to_s,
|
|
ex: 7200
|
|
)
|
|
rate_limiter.track_assignment(conversation)
|
|
end
|
|
end
|
|
|
|
context 'without custom window' do
|
|
let(:assignment_policy) do
|
|
instance_double(AssignmentPolicy,
|
|
fair_distribution_limit: 10,
|
|
fair_distribution_window: nil)
|
|
end
|
|
|
|
before do
|
|
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
|
|
end
|
|
|
|
it 'uses the default window value of 24 hours' do
|
|
expected_key = format(Redis::RedisKeys::ASSIGNMENT_KEY, inbox_id: inbox.id, agent_id: agent.id, conversation_id: conversation.id)
|
|
expect(Redis::Alfred).to receive(:set).with(
|
|
expected_key,
|
|
conversation.id.to_s,
|
|
ex: 86_400
|
|
)
|
|
rate_limiter.track_assignment(conversation)
|
|
end
|
|
end
|
|
end
|
|
end
|