openlanes 3.0.0

data/lib/openlanes/live/claims.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    # The one rule that keeps machines sharing a Redis apart (W26): no two
+    # nodes work the same plan.
+    #
+    # A claim is `SET NX EX`, renewed by the heartbeat while the run keeps
+    # the plan, and released by compare-and-delete so a node can only ever
+    # remove its own. A node that dies lets its claims lapse within
+    # {Keys::CLAIM_TTL} seconds. This is advisory between well-behaved
+    # openlanes processes, like agent-lock, not a defence (W29).
+    class Claims
+      # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+      # @param keys [OpenLanes::Live::Keys]
+      # @param ttl [Integer] seconds
+      def initialize(store:, keys:, ttl: Keys::CLAIM_TTL)
+        @store = store
+        @keys = keys
+        @ttl = ttl
+        @held = []
+        @mutex = Mutex.new
+      end
+
+      # @return [Array<String>] ordinals this node holds, as far as it knows
+      def held = @mutex.synchronize { @held.dup }
+
+      # Take the plan, or keep it if it is already ours.
+      #
+      # @param ordinal [#to_s]
+      # @return [Boolean] whether this node holds it now
+      def claim(ordinal)
+        key = @keys.claim(ordinal)
+        ok = @store.set(key, @keys.node, ex: @ttl, nx: true) || @store.compare_and_expire(key, @keys.node, @ttl)
+        @mutex.synchronize { @held |= [ordinal.to_s] } if ok
+        ok
+      end
+
+      # Extend every claim this node holds. One that lapsed and was taken by
+      # another node in the meantime is dropped from {#held}, not fought for.
+      #
+      # @return [Array<String>] the ordinals lost
+      def renew
+        lost = held.reject { |ordinal| @store.compare_and_expire(@keys.claim(ordinal), @keys.node, @ttl) }
+        @mutex.synchronize { @held -= lost }
+        lost
+      end
+
+      # @param ordinal [#to_s]
+      # @return [Boolean] whether a claim of ours was removed
+      def release(ordinal)
+        @mutex.synchronize { @held.delete(ordinal.to_s) }
+        @store.compare_and_delete(@keys.claim(ordinal), @keys.node)
+      end
+
+      # @return [void]
+      def release_all = held.each { |ordinal| release(ordinal) }
+
+      # @param ordinal [#to_s]
+      # @return [String, nil] the node name holding the plan
+      def held_by(ordinal) = @store.get(@keys.claim(ordinal))
+
+      # @param ordinal [#to_s]
+      # @return [Boolean] whether another node holds the plan
+      def foreign?(ordinal)
+        holder = held_by(ordinal)
+        !holder.nil? && holder != @keys.node
+      end
+    end
+  end
+end

data/lib/openlanes/live/command.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Live
+    # One instruction from the page to the engine, as `web/src/api/types.ts`
+    # defines `Command`. The id is minted by the page and is also the
+    # idempotency key (W13): the engine applies a command once however many
+    # times it is delivered.
+    #
+    # {.parse} checks only the shape, so the API server can refuse a
+    # malformed command with 422 before it is queued. Whether the plan,
+    # agent or question it names exists is the engine's to say, when it
+    # applies it.
+    #
+    # @!attribute [r] id
+    #   @return [String]
+    # @!attribute [r] kind
+    #   @return [String] one of {KINDS}
+    # @!attribute [r] plan
+    #   @return [String, nil] an ordinal
+    # @!attribute [r] agent
+    #   @return [String, nil]
+    # @!attribute [r] payload
+    #   @return [Hash{String => Object}]
+    Command = Data.define(:id, :kind, :plan, :agent, :payload) do
+      # @return [String] `"<ordinal>/<agent>"`, the car it addresses
+      def car = "#{plan}/#{agent}"
+
+      # @param name [String]
+      # @return [String] the payload field, stripped; empty when absent
+      def [](name) = payload[name.to_s].to_s.strip
+
+      # @return [Hash] as the wire carries it
+      def wire = { id:, kind:, plan:, agent:, payload: }
+    end
+
+    class Command
+      # A command that cannot be applied as written.
+      class Invalid < Error; end
+
+      # Every kind the page may send.
+      KINDS = %w[answer hold_blocked release_hold resume discard message hold wrap_up compact stop stop_all
+                 set_model switch_model add_plan create_plans].freeze
+
+      # Kinds that act on one plan, and so must name it.
+      PLAN_KINDS = %w[answer hold_blocked release_hold resume discard message hold wrap_up compact stop
+                      set_model switch_model].freeze
+
+      # Kinds that act on one agent of that plan, and so must name it too.
+      AGENT_KINDS = %w[hold wrap_up compact stop set_model switch_model].freeze
+
+      # Payload fields each kind cannot do without.
+      PAYLOAD = {
+        "answer"       => %w[question text],
+        "hold_blocked" => %w[question],
+        "release_hold" => %w[question],
+        "message"      => %w[text],
+        "set_model"    => %w[model],
+        "switch_model" => %w[model],
+        "add_plan"     => %w[ordinal],
+        "create_plans" => %w[idea]
+      }.freeze
+
+      # Ids are ULIDs; this only keeps an absurd one out of a hash field.
+      ID = /\A[0-9A-Za-z_-]{1,64}\z/
+
+      # @param input [String, Hash] JSON, or the parsed hash
+      # @return [OpenLanes::Live::Command]
+      # @raise [OpenLanes::Live::Command::Invalid] naming what is wrong
+      def self.parse(input)
+        data = input.is_a?(String) ? JSON.parse(input) : input
+        raise Invalid, "a command is a JSON object" unless data.is_a?(Hash)
+
+        data = data.transform_keys(&:to_s)
+        plan = data["plan"]&.to_s
+        command = new(id: data["id"].to_s,
+          kind: data["kind"].to_s,
+          plan: (Plans::Ordinal.parse(plan)&.to_s if plan) || plan,
+          agent: data["agent"]&.to_s,
+          payload: (data["payload"] || {}).to_h.transform_keys(&:to_s))
+        command.tap { check(it) }
+      rescue JSON::ParserError, TypeError, NoMethodError => e
+        raise Invalid, "not a command: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # @param command [OpenLanes::Live::Command]
+      # @return [void]
+      # @raise [OpenLanes::Live::Command::Invalid]
+      def self.check(command)
+        raise Invalid, "id must be 1 to 64 letters, digits, - or _" unless command.id.match?(ID)
+        raise Invalid, "unknown kind #{command.kind.inspect}; known: #{KINDS.join(", ")}" unless KINDS.include?(command.kind)
+        raise Invalid, "#{command.kind} needs a plan" if PLAN_KINDS.include?(command.kind) && command.plan.to_s.empty?
+        raise Invalid, "#{command.kind} needs an agent" if AGENT_KINDS.include?(command.kind) && command.agent.to_s.empty?
+
+        missing = PAYLOAD.fetch(command.kind, []).select { |field| command[field].empty? }
+        raise Invalid, "#{command.kind} needs payload #{missing.join(" and ")}" unless missing.empty?
+      end
+    end
+
+    # The engine's answer to one {Command}: `Reply` in `types.ts`.
+    #
+    # @!attribute [r] id
+    #   @return [String] the command's id
+    # @!attribute [r] status
+    #   @return [String] "accepted", "refused" or "done"
+    # @!attribute [r] reason
+    #   @return [String, nil]
+    # @!attribute [r] at
+    #   @return [Time]
+    Reply = Data.define(:id, :status, :reason, :at) do
+      def initialize(reason: nil, at: Time.now, **rest) = super
+
+      # @return [Hash]
+      def wire = { id:, status:, reason:, at: at.utc.iso8601 }
+
+      # @return [String]
+      def to_json(*) = JSON.generate(wire)
+    end
+  end
+end