feat: add priority field to server for queue ordering

Adds a priority field to servers that controls the order in which
queued messages are processed. Messages from servers with higher
priority values are sent first.

Includes:
- Database migration to add priority column
- Validation for priority (0-32767)
- UI field in server form
- Queue ordering by server priority

Cherry-picked from postalserver/postal PR postalserver#3446

Co-authored-by: Xyaren <Xyaren@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

app/controllers/servers_controller.rb

@@ -96,7 +96,7 @@ def unsuspend
   private
 
   def safe_params(*extras)
-    params.require(:server).permit(:name, :mode, :ip_pool_id, *extras)
+    params.require(:server).permit(:name, :mode, :priority, :ip_pool_id, *extras)
   end
 
 end

app/lib/worker/jobs/process_queued_messages_job.rb

@@ -40,12 +40,16 @@ def local_ip?(ip)
       end
 
       # Obtain a queued message from the database for processing
+      # Messages are prioritized based on the server's priority (higher priority first)
+      # and then by the message ID (ascending order).
       #
       # @return [void]
       def lock_message_for_processing
-        QueuedMessage.where(ip_address_id: [nil, @ip_addresses])
+        QueuedMessage.joins(:server)
+                     .where(ip_address_id: [nil, @ip_addresses])
                      .where(locked_by: nil, locked_at: nil)
                      .ready_with_delayed_retry
+                     .order("servers.priority DESC, queued_messages.id ASC")
                      .limit(1)
                      .update_all(locked_by: @locker, locked_at: @lock_time)
       end

app/models/server.rb

@@ -77,6 +77,12 @@ class Server < ApplicationRecord
   validates :name, presence: true, uniqueness: { scope: :organization_id, case_sensitive: false }
   validates :mode, inclusion: { in: MODES }
   validates :permalink, presence: true, uniqueness: { scope: :organization_id, case_sensitive: false }, format: { with: /\A[a-z0-9-]*\z/ }, exclusion: { in: RESERVED_PERMALINKS }
+  validates :priority, presence: true, numericality: {
+    only_integer: true,
+    greater_than_or_equal_to: 0,
+    less_than_or_equal_to: 32767,
+    message: "must be a whole number between 0 and 32,767"
+  }
   validate :validate_ip_pool_belongs_to_organization
 
   before_validation(on: :create) do

app/views/servers/_form.html.haml

@@ -20,6 +20,15 @@
           e-mail will be routed normally to the intended recipients. When in <b>Development</b> mode,
           outgoing & incoming mail will be held and only visible in the web interface and will not be
           sent to any recipients or HTTP endpoints.
+    .fieldSet__field
+      = f.label :priority, "Sending Priority", :class => 'fieldSet__label'
+      .fieldSet__input
+        = f.text_field :priority,
+                       :class => 'input input--text',
+                       :placeholder => "e.g. 10"
+        %p.fieldSet__text
+          Set a priority for this server's outgoing mail. Messages from servers with a higher number will be sent first.
+          The default is <b>0</b>.
 
     - if Postal.ip_pools?
       .fieldSet__field

db/migrate/20260121000001_add_priority_to_server.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddPriorityToServer < ActiveRecord::Migration[7.0]
+
+  def change
+    add_column :servers, :priority, :integer, limit: 2, unsigned: true, default: 0
+  end
+
+end