munawaba 0.1.0

data/app/jobs/munawaba/maintenance_job.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Munawaba
+  # Run every minute, or repair the timing of one schedule after a delivery mismatch.
+  class MaintenanceJob < ApplicationJob
+    def perform(schedule_id = nil)
+      failure = nil
+      scope = Schedule.where(state: schedule_id ? %w[scheduled active pausing] : %w[scheduled pausing])
+      scope = scope.where(id: schedule_id) if schedule_id
+      scope.find_each(batch_size: 100) do |schedule|
+        Shifts::NormalizeFutureTiming.call(schedule: schedule)
+      rescue StandardError => error
+        failure ||= error
+        Munawaba.signal("maintenance_failed", task: "lifecycle", schedule_id: schedule.id)
+      end
+
+      unless schedule_id
+        [Notifications::ReclaimExpiredLeases, Notifications::Dispatcher].each do |task|
+          task.call
+        rescue StandardError => error
+          failure ||= error
+          Munawaba.signal("maintenance_failed", task: task.name)
+        end
+      end
+      raise failure if failure
+    end
+  end
+end

data/app/models/munawaba/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/munawaba/audit_event.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class AuditEvent < ApplicationRecord
+    self.table_name = "munawaba_audit_events"
+    belongs_to :schedule, class_name: "Munawaba::Schedule", optional: true
+    belongs_to :person, class_name: "Munawaba::Person", optional: true
+    belongs_to :shift, class_name: "Munawaba::Shift", optional: true
+    validates :event_type, presence: true, length: { maximum: 100 }
+    validate do
+      unless metadata.is_a?(Hash) && metadata.to_json.bytesize <= 131072
+        errors.add(:metadata, "must be an object no larger than 128 KiB")
+      end
+    end
+  end
+end

data/app/models/munawaba/notification_delivery.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class NotificationDelivery < ApplicationRecord
+    self.table_name = "munawaba_notification_deliveries"
+    KINDS = %w[advance_reminder shift_start assignment_change next_assignment_change test].freeze
+    STATUSES = %w[pending enqueued processing delivered failed canceled stale].freeze
+    TERMINAL_STATUSES = %w[delivered failed canceled stale].freeze
+    CLEAR_CLAIM = { claim_token: nil, lease_expires_at: nil, enqueued_at: nil, processing_at: nil }.freeze
+    belongs_to :schedule, class_name: "Munawaba::Schedule"
+    belongs_to :shift, class_name: "Munawaba::Shift", optional: true
+    belongs_to :retry_of_delivery, class_name: "Munawaba::NotificationDelivery", optional: true
+    has_one :retry_delivery, class_name: "Munawaba::NotificationDelivery", foreign_key: :retry_of_delivery_id
+    validates :kind, inclusion: { in: KINDS }
+    validates :status, inclusion: { in: STATUSES }
+    validates :event_key, presence: true, length: { maximum: 255 }, uniqueness: true
+    validates :due_at, :expires_at, presence: true
+    validates :notification_revision, :attempt_count, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    validate :valid_context
+    validate {
+      errors.add(:base,
+                 "Terminal deliveries cannot be reopened") if persisted? && TERMINAL_STATUSES.include?(status_in_database) && changed?
+    }
+    scope :unsent, -> { where(status: %w[pending enqueued]) }
+    scope :pending, -> { where(status: "pending") }
+    scope :recent, -> { order(created_at: :desc, id: :desc) }
+    STATUSES.each { |value| define_method("#{value}?") { status == value } }
+
+    def mark_pending!(at:, error_code: last_error_code)
+      update_columns(**CLEAR_CLAIM, status: "pending", next_attempt_at: at, last_error_code: error_code,
+                                    updated_at: Time.current)
+    end
+
+    def finish!(status:, code: nil, now: Time.current, http_status: nil)
+      unknown = last_error_code == "delivery_outcome_unknown"
+      error = status.to_s == "delivered" ? nil : (unknown ? "delivery_outcome_unknown" : code)
+      update_columns(**CLEAR_CLAIM, status: status.to_s, next_attempt_at: nil, updated_at: now,
+                                    last_error_code: error, last_http_status: http_status || last_http_status,
+                                    delivered_at: status.to_s == "delivered" ? now : nil)
+    end
+
+    def retry_later!(now:, code:, retry_after: nil, unknown: false, validity: nil)
+      sticky = unknown || last_error_code == "delivery_outcome_unknown"
+      self.last_error_code = sticky ? "delivery_outcome_unknown" : code
+      validity ||= Notifications::Validity.call(self, now: now)
+      unless validity.valid?
+        finish!(status: validity.status, code: validity.code, now: now)
+        return
+      end
+      if attempt_count >= Defaults::NOTIFICATION_MAX_ATTEMPTS
+        finish!(status: :failed, code: "retry_exhausted", now: now)
+        return
+      end
+      window = [Defaults::NOTIFICATION_BACKOFF_CAP.to_f,
+                Defaults::NOTIFICATION_BACKOFF_BASE.to_f * (2**[attempt_count - 1, 0].max)].min
+      delay = 1 + (SecureRandom.random_number * [window - 1, 0].max)
+      delay += retry_after.to_f if retry_after
+      at = now + delay
+      if at >= expires_at
+        finish!(status: :stale, code: "expired_before_retry", now: now)
+      else
+        update_columns(last_http_status: last_http_status)
+        mark_pending!(at: at, error_code: last_error_code)
+      end
+    end
+
+    private
+
+    def valid_context
+      Notifications::Context::V1.validate!(kind: kind, context: context)
+    rescue ArgumentError, Munawaba::Error => error
+      errors.add(:context, error.message)
+    end
+  end
+end

data/app/models/munawaba/person.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class Person < ApplicationRecord
+    self.table_name = "munawaba_people"
+    has_many :schedule_memberships, class_name: "Munawaba::ScheduleMembership", inverse_of: :person
+    has_many :schedules, through: :schedule_memberships
+    has_many :effective_shifts, class_name: "Munawaba::Shift", foreign_key: :effective_person_id
+    has_many :base_shifts, class_name: "Munawaba::Shift", foreign_key: :base_person_id
+    has_many :audit_events, class_name: "Munawaba::AuditEvent"
+
+    normalizes :name, with: ->(value) { value.strip }
+    normalizes :email, with: ->(value) { value.strip.downcase }
+    normalizes :slack_member_id, with: ->(value) { value.strip.presence }
+    validates :name, presence: true, length: { maximum: 120 }
+    validates :email, presence: true, length: { maximum: 320 }, uniqueness: { case_sensitive: false }, format: { with: URI::MailTo::EMAIL_REGEXP }
+    validates :slack_member_id, allow_nil: true, uniqueness: true, format: { with: /\A[A-Z][A-Z0-9]{1,31}\z/ }
+    validates :active, inclusion: { in: [true, false] }
+    validates :lock_version, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    validate { errors.add(:deactivated_at, "must match active status") unless active == deactivated_at.nil? }
+    scope :active, -> { where(active: true) }
+  end
+end

data/app/models/munawaba/schedule.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class Schedule < ApplicationRecord
+    self.table_name = "munawaba_schedules"
+    STATES = %w[draft scheduled active pausing paused].freeze
+    CADENCES = %w[one_week two_weeks calendar_month].freeze
+    TIMING_FIELDS = %w[cadence time_zone anchor_local_date anchor_local_seconds].freeze
+    has_many :schedule_memberships, -> {
+      order(:position)
+    }, class_name: "Munawaba::ScheduleMembership", inverse_of: :schedule
+    has_many :people, through: :schedule_memberships
+    has_many :shifts, class_name: "Munawaba::Shift"
+    has_many :notification_deliveries, class_name: "Munawaba::NotificationDelivery"
+    has_many :audit_events, class_name: "Munawaba::AuditEvent"
+    encrypts :slack_webhook_url
+    self.filter_attributes += [:slack_webhook_url]
+    normalizes :name, with: ->(value) { value.strip }
+    validates :name, presence: true, length: { maximum: 120 }, uniqueness: { case_sensitive: false }
+    validates :state, inclusion: { in: STATES }
+    validates :cadence, inclusion: { in: CADENCES }
+    validates :time_zone, presence: true, length: { maximum: 100 }
+    validates :anchor_local_date, presence: true
+    validates :anchor_local_seconds,
+              numericality: { only_integer: true, greater_than_or_equal_to: 0, less_than_or_equal_to: 86340 }
+    validates :advance_notice_seconds,
+              numericality: { only_integer: true, greater_than_or_equal_to: 60, less_than_or_equal_to: 2592000 }
+    validates :coverage_revision, :rotation_revision, :lifecycle_revision, :notification_revision, :lock_version,
+              numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    validate :valid_time_zone
+    validate {
+      errors.add(:anchor_local_date,
+                 "must have a four-digit year (0001–9999)") if anchor_local_date && !(1..9999).cover?(anchor_local_date.year)
+    }
+    validate :minute_precision
+    validate :immutable_timing_after_commitment
+    validate :slack_configuration
+
+    def current_shift(at = Time.current)
+      shifts.live.current(at).first
+    end
+
+    def next_shift(at = Time.current)
+      shifts.live.where("starts_at > ?", at.utc).order(:starts_at, :id).first
+    end
+
+    def ordered_person_ids
+      schedule_memberships.reorder(:position).pluck(:person_id)
+    end
+
+    private
+
+    def valid_time_zone
+      TZInfo::Timezone.get(time_zone) if time_zone.present?
+    rescue TZInfo::InvalidTimezoneIdentifier
+      errors.add(:time_zone, "must be an IANA timezone")
+    end
+
+    def minute_precision
+      errors.add(:anchor_local_seconds,
+                 "must have minute precision") if anchor_local_seconds && anchor_local_seconds % 60 != 0
+    end
+
+    def immutable_timing_after_commitment
+      return unless persisted? && (first_activated_at_in_database.present? || state_in_database == "scheduled")
+
+      errors.add(:base, "Timing can only change on a draft that has never started.") if (changed & TIMING_FIELDS).any?
+    end
+
+    def slack_configuration
+      if slack_webhook_url.present? != slack_webhook_configured_at.present?
+        errors.add(:slack_webhook_url, "configuration timestamp must match the webhook")
+      end
+      errors.add(:slack_enabled, "requires a webhook") if slack_enabled && slack_webhook_url.blank?
+      return if slack_webhook_url.blank? || !will_save_change_to_slack_webhook_url?
+
+      unless Slack::WebhookValidator.valid?(slack_webhook_url)
+        errors.add(:slack_webhook_url, "must be an allowed Slack incoming webhook")
+      end
+      unless ActiveRecord::Encryption.config.has_primary_key? && ActiveRecord::Encryption.config.has_key_derivation_salt?
+        errors.add(:slack_webhook_url, "requires host Active Record Encryption keys")
+      end
+    end
+  end
+end

data/app/models/munawaba/schedule_membership.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class ScheduleMembership < ApplicationRecord
+    self.table_name = "munawaba_schedule_memberships"
+    belongs_to :schedule, class_name: "Munawaba::Schedule", inverse_of: :schedule_memberships
+    belongs_to :person, class_name: "Munawaba::Person", inverse_of: :schedule_memberships
+    validates :person_id, uniqueness: { scope: :schedule_id }
+    validates :position, numericality: { only_integer: true, greater_than_or_equal_to: 0 },
+                         uniqueness: { scope: :schedule_id }
+    validate { errors.add(:person, "must be active") if new_record? && person && !person.active? }
+  end
+end

data/app/models/munawaba/shift.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class Shift < ApplicationRecord
+    self.table_name = "munawaba_shifts"
+    belongs_to :schedule, class_name: "Munawaba::Schedule"
+    belongs_to :base_person, class_name: "Munawaba::Person"
+    belongs_to :effective_person, class_name: "Munawaba::Person"
+    has_many :shift_overrides, class_name: "Munawaba::ShiftOverride"
+    has_one :active_override, -> { where(ended_at: nil) }, class_name: "Munawaba::ShiftOverride"
+    has_many :notification_deliveries, class_name: "Munawaba::NotificationDelivery"
+    validates :starts_at, :ends_at, :generated_at, presence: true
+    validates :coverage_revision, :assignment_version, :timing_version,
+              numericality: { only_integer: true, greater_than: 0 }
+    validates :boundary_index, :rotation_revision, :lock_version,
+              numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    validates :cancellation_reason, inclusion: { in: %w[pause scheduled_run_canceled] }, allow_nil: true
+    validate :interval_and_cancellation
+    validate { errors.add(:base, "Canceled shifts are terminal") if persisted? && canceled_at_in_database && changed? }
+    scope :live, -> { where(canceled_at: nil) }
+    scope :current, ->(at = Time.current) { where("starts_at <= ? AND ends_at > ?", at.utc, at.utc) }
+    scope :overlapping, ->(from, to) {
+      where("tstzrange(starts_at, ends_at, '[)') && tstzrange(?, ?, '[)')", from.utc, to.utc)
+    }
+    def canceled? = canceled_at.present?
+
+    def self.persist_projection!(schedule:, slots:, now:)
+      connection.execute("SET CONSTRAINTS ALL DEFERRED")
+      rows = where(id: slots.filter_map { |slot| slot[:id] }).index_by(&:id)
+      slots.map do |slot|
+        values = slot.slice(:coverage_revision, :boundary_index, :starts_at, :ends_at, :base_person_id, :effective_person_id,
+                            :rotation_revision, :assignment_version, :timing_version)
+        if slot[:id]
+          row = rows.fetch(slot[:id])
+          row.update!(values) if values.any? { |key, value| row.public_send(key) != value }
+          row
+        else
+          create!(values.merge(schedule_id: schedule.id, generated_at: now))
+        end
+      end
+    end
+
+    private
+
+    def interval_and_cancellation
+      errors.add(:ends_at, "must be after the start") if starts_at && ends_at && ends_at <= starts_at
+      errors.add(:cancellation_reason,
+                 "must match the cancellation time") unless canceled_at.nil? == cancellation_reason.nil?
+    end
+  end
+end

data/app/models/munawaba/shift_override.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class ShiftOverride < ApplicationRecord
+    self.table_name = "munawaba_shift_overrides"
+    END_REASONS = %w[revoked superseded restored_to_base shift_canceled].freeze
+    belongs_to :shift, class_name: "Munawaba::Shift"
+    belongs_to :previous_person, class_name: "Munawaba::Person"
+    belongs_to :replacement_person, class_name: "Munawaba::Person"
+    normalizes :reason, with: ->(value) { value.strip.presence }
+    validates :reason, length: { maximum: 1000 }
+    validates :end_reason, inclusion: { in: END_REASONS }, allow_nil: true
+    validate :valid_transition
+
+    private
+
+    def valid_transition
+      errors.add(:replacement_person,
+                 "must differ from the previous person") if previous_person_id == replacement_person_id
+      errors.add(:replacement_person,
+                 "must be active") if new_record? && replacement_person && !replacement_person.active?
+      errors.add(:end_reason, "must match the end time") unless ended_at.nil? == end_reason.nil?
+      errors.add(:ended_at, "cannot precede creation") if ended_at && created_at && ended_at < created_at
+      return unless persisted?
+
+      errors.add(:base, "Ended overrides are terminal") if ended_at_in_database && changed?
+      errors.add(:base, "Only an override terminal transition may be updated") if (changed - %w[ended_at end_reason
+                                                                                                updated_at]).any?
+    end
+  end
+end

data/app/services/munawaba/audit/recorder.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Audit
+    # Metadata is stored without filtering; omit secrets and request/model snapshots.
+    class Recorder
+      def self.record!(event_type:, metadata: {}, actor: nil, operation_id: SecureRandom.uuid,
+                       occurred_at: Time.current, schedule: nil, person: nil, shift: nil, shift_id: nil)
+        snapshot = actor.to_h.symbolize_keys.slice(:type, :id, :name).transform_values { |value| value&.to_s.presence }
+        AuditEvent.create!(event_type: event_type, operation_id: operation_id, occurred_at: occurred_at,
+                           schedule: schedule, person: person, shift_id: shift&.id || shift_id,
+                           actor_type: snapshot[:type], actor_id: snapshot[:id], actor_name: snapshot[:name],
+                           metadata: metadata.as_json)
+      end
+    end
+  end
+end

data/app/services/munawaba/canonical.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Munawaba
+  module Canonical
+    module_function
+
+    def time(value)
+      Time.at(value.to_time.utc.to_r.floor(6)).utc
+    end
+
+    def micros(value)
+      (value.to_time.utc.to_r * 1_000_000).floor
+    end
+
+    def instant(value)
+      value&.utc&.iso8601(6)
+    end
+
+    def from_micros(value)
+      Time.at(Rational(Integer(value), 1_000_000)).utc
+    end
+
+    def digest(value)
+      Digest::SHA256.hexdigest(JSON.generate(value))
+    end
+
+    def equal?(left, right)
+      left.is_a?(String) && right.is_a?(String) && left.bytesize == right.bytesize &&
+        ActiveSupport::SecurityUtils.secure_compare(left, right)
+    end
+
+    def deep_freeze(value)
+      case value
+      when Array then value.each { |item| deep_freeze(item) }
+      when Hash then value.each { |key, item| deep_freeze(key); deep_freeze(item) }
+      end
+      value.freeze
+    end
+  end
+end