samagotchi 0.170.0 → 0.171.0

data/lib/samagotchi/web/app.rb

@@ -69,15 +69,19 @@ require_relative "session_hub"
 require_relative "project_list"
 require_relative "session_access_routes"
 require_relative "principal"
+require_relative "viewer"
 require_relative "participant_access"
+require_relative "participant_images"
 require_relative "participants_admin"
 require_relative "participant_review"
+require_relative "participant_show"
 require_relative "message_display"
 require_relative "session_show"
 require_relative "session_create"
 require_relative "session_control"
 require_relative "verify_fresh_routes"
 require_relative "reload_check_route"
+require_relative "working_set_routes"
 require_relative "push_routes"
 require_relative "block_renderer_routes"
 require_relative "update_check"
@@ -105,14 +109,17 @@ module Samagotchi
       include RedactedInspect
       include SessionAccessRoutes
       include ParticipantAccess
+      include ParticipantImages
       include ParticipantsAdmin
       include ParticipantReview
+      include ParticipantShow
       include MessageDisplay
       include SessionShow
       include SessionCreate
       include SessionControl
       include VerifyFreshRoutes
       include ReloadCheckRoute
+      include WorkingSetRoutes
       include PushRoutes
       include BlockRendererRoutes
       include ProxyGate
@@ -223,6 +230,7 @@ module Samagotchi
         @update_ops = update_ops || UpdateOps.new(hub: hub, manager: @manager, state_dir: state_dir,
                                                   runner: update_runner, blocked: update_blocked)
         init_participant_access(grants, state_dir)
+        init_participant_images
         init_proxy_gate(public_url, public_token)
       end
 
@@ -283,9 +291,8 @@ module Samagotchi
         ["POST", %r{\A/api/update/restart_web\z}, :handle_restart_web, :owner],
         ["POST", %r{\A/api/render\z}, :handle_render, :owner],
         ["GET", %r{\A/api/sessions/([^/]+)/stream\z}, :handle_stream, :participant],
-        ["GET", %r{\A/api/sessions/([^/]+)/review\z}, :handle_review, :participant, :session],
         ["GET", %r{\A/api/sessions/([^/]+)/output\z}, :handle_output, :owner, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel, :participant, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/tasks/([^/]+)/stop\z}, :handle_task_stop, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/turn/([^/]+)/dequeue\z}, :handle_dequeue_turn, :participant, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/stop\z}, :handle_stop, :owner, :session],
@@ -311,14 +318,15 @@ module Samagotchi
         ["POST", %r{\A/api/sessions/([^/]+)/answer\z}, :handle_question_answer, :owner],
         ["POST", %r{\A/api/sessions/([^/]+)/question/dismiss\z}, :handle_question_dismiss, :owner],
         ["POST", %r{\A/api/sessions/([^/]+)/command\z}, :handle_command, :owner, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/images\z}, :handle_image_upload, :owner],
-        ["GET", %r{\A/api/sessions/([^/]+)/images/([^/]+)\z}, :handle_image, :owner],
+        ["POST", %r{\A/api/sessions/([^/]+)/images\z}, :handle_image_upload, :participant, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/images/([^/]+)\z}, :handle_image, :participant, :session],
         ["GET", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_list, :owner, :session],
         ["GET", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_show, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_add, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/context/([^/]+)/push\z}, :handle_context_push, :owner, :session],
         ["DELETE", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_delete, :owner, :session],
-        ["GET", %r{\A/api/sessions/([^/]+)/working_set\z}, :handle_working_set, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/working_set\z}, :handle_working_set, :participant, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/working_set/item\z}, :handle_working_set_item, :owner, :session],
         ["GET", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_list, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_invite, :owner, :session],
         ["DELETE", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_revoke, :owner, :session],
@@ -1387,69 +1395,6 @@ module Samagotchi
         end
       end
 
-      # ── The working set (web.working_set) ───────────────────────────────
-
-      # GET /api/sessions/:id/working_set: the working set as the model has
-      # it ({items:, at:, running:}, WorkingSet), what the page overlays on its rows'
-      # set when it seeds a session's and when the expanded view opens (a
-      # file changed while the session sat idle). A live worker's snapshot
-      # messages are the truth, as #handle_show's, else the file's; the
-      # strategy is the session's llm_context summary's, the folder its working
-      # directory. running: a turn runs. The snapshot's messages lag it, so
-      # the answer is then the turn's last :working_set_updated (the
-      # snapshot's working_set, TurnAccumulator#working_set); before the
-      # turn emitted one, or from an older worker without the field, it is
-      # the session's messages, behind that turn's events, and the page
-      # keeps theirs (working_set.js newerSnapshot).
-      def handle_working_set(_req, id)
-        session = @session_class.load(id, state_dir: default_state_dir)
-        live = bridge_get_json(id, "snapshot")
-        worker_snapshot = live && live["snapshot"]
-        running = !worker_snapshot&.dig("current_turn").nil?
-        turn_set = running && running_working_set(live["snapshot"]["working_set"])
-        return json_response(200, turn_set.merge(running: true)) if turn_set
-
-        idle_set = idle_working_set(worker_snapshot && worker_snapshot["idle_working_set"]) unless running
-        return json_response(200, idle_set.merge(running: false)) if idle_set
-
-        messages = live_or_saved(worker_snapshot, "messages") { session.messages }
-        # A snapshot's entries have string keys (paired_runs reads symbols).
-        messages = Array(messages).map { |message| message.is_a?(Hash) ? message.transform_keys(&:to_sym) : message }
-        llm_context = SessionSetting::LLM_CONTEXT.snapshot_value(live && live["session_state_snapshot"]) do
-          SessionSetting::LLM_CONTEXT.saved_summary(session, registry: host_registry)
-        end
-        snapshot = WorkingSet.build(messages, cwd: session.working_directory, strategy: working_set_strategy(llm_context),
-                                    pins: session.working_set_pins)
-        json_response(200, snapshot.to_h.merge(running: running))
-      end
-
-      # The running turn's set from a worker's snapshot ({"items", "at"}), as
-      # {items:, at:}; nil when it has none (none emitted yet, an older worker).
-      def running_working_set(set)
-        return nil unless set.is_a?(Hash) && set["items"].is_a?(Array) && set["at"].is_a?(Integer)
-
-        { items: set["items"], at: set["at"] }
-      end
-
-      # The worker's between-turns working set ({"items", "at", optional
-      # "adds"}); nil for an older or malformed snapshot.
-      def idle_working_set(set)
-        return nil unless set.is_a?(Hash) && set["items"].is_a?(Array) && set["at"].is_a?(Integer)
-        return nil if set.key?("adds") && !set["adds"].is_a?(Array)
-
-        { items: set["items"], at: set["at"] }.tap do |snapshot|
-          snapshot[:adds] = set["adds"] if set.key?("adds")
-        end
-      end
-
-      # The strategy an llm_context summary names ("none", "stale,forget"), as
-      # LLMContextView takes it; none when there is no chip.
-      def working_set_strategy(llm_context)
-        named = llm_context.is_a?(Hash) ? (llm_context[:strategy] || llm_context["strategy"]).to_s : ""
-        layers = named.split(",").map(&:strip).reject { |layer| layer.empty? || layer == "none" }
-        layers.empty? ? LLMContextView::NONE : layers.map(&:to_sym)
-      end
-
       # ── Attached context (ContextSources): the session bar's chips ───────
       # A source's command isn't shown (the page may be on a phone over the
       # LAN), and the web adds a URL only, through an installed bundle's
@@ -1679,9 +1624,8 @@ module Samagotchi
       end
 
       # What a request's stream goes through on its way from the Bridge:
-      # nil, the raw bytes unchanged, for the owner; a participant's (and
-      # the owner's ?as=participant, the participant view) goes through
-      # ParticipantStreamFilter. A filter is anything with #call(chunk) ->
+      # nil, the raw bytes unchanged, for the owner; a participant's goes
+      # through ParticipantStreamFilter. A filter is anything with #call(chunk) ->
       # String (nil or "" sends nothing); see ProxyStreamBody.
       def stream_filter(req, id)
         return nil unless participant_view?(req)
@@ -1839,8 +1783,6 @@ module Samagotchi
       end
 
       def serve_index(req)
-        return participant_shell(req) if participant_view?(req)
-
         path = File.join(@public_dir, "index.html")
         if File.file?(path)
           # A block: a preset's \& or \' is text, never a backreference.
@@ -1956,17 +1898,21 @@ module Samagotchi
       # #code= and the app's start_url "/" all land there). ?dir= beats
       # ?scope=all.
       def index_data_attributes(req)
+        return participant_index_data(req) unless principal(req).owner?
+
         # version: the chi that served the page; the events snapshot names
         # the one serving now (an upgraded chi web after a reconnect).
         attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(start_dir), "version" => Samagotchi::VERSION }
-        # The owner's home: a claim link's quote reads it "~", as the
-        # participant page shows it (claim_link.js).
+        # The owner's home: a claim link's quote reads it "~", as a
+        # participant's page shows it (claim_link.js).
         attrs["home"] = Dir.home
         # Only when on: the page reads its presence.
         attrs["working-set"] = "1" if working_set?(req.params["working_set"])
         # The opt-in reload check (reload_check.js): only when on.
         attrs["reload-check"] = "1" if @reload_check
         attrs.merge!(annotate_presets_data)
+        # Who looks and what they may do (Viewer; viewer.js reads it at boot).
+        attrs.merge!(Viewer.for(principal(req)).body_attributes)
         dir, = scope_dir(req.params["dir"])
         unless dir
           dir = default_scope_dir(req)
@@ -1989,11 +1935,30 @@ module Samagotchi
         body_data(attrs)
       end
 
+      # A participant's <body> data for index.html: who they are (Viewer), their
+      # grant's session and its participant title (the tab's), the version
+      # and the Annotate presets, and whether the working set is on
+      # (web.working_set: their stage's file column, as the owner's).
+      # Nothing of the owner's machine: no home, folders, project or way
+      # back (sessions-dir, server-dir, home, scope-dir, project-*, back-*).
+      def participant_index_data(req)
+        grant = principal(req).grant
+        attrs = { "version" => Samagotchi::VERSION, "session" => grant.session_id }
+        attrs["working-set"] = "1" if working_set?(req.params["working_set"])
+        title = Degrade.call(:web, "participant_title_unreadable", fallback: nil) do
+          participant_title(@session_class.load(grant.session_id, state_dir: default_state_dir))
+        end
+        attrs["session-title"] = title if title
+        attrs.merge!(annotate_presets_data)
+        attrs.merge!(Viewer.for(principal(req)).body_attributes)
+        body_data(attrs)
+      end
+
       # +attrs+ as <body> data attributes, each value escaped.
       def body_data(attrs) = attrs.map { |key, value| %(data-#{key}="#{Rack::Utils.escape_html(value)}") }.join(" ")
 
-      # The Annotate presets (web.annotate_presets) for a page's <body>, the
-      # owner's and the participant page's. Always there: an empty one means
+      # The Annotate presets (web.annotate_presets) for the page's <body>,
+      # the owner's and a participant's. Always there: an empty one means
       # no presets, not the default.
       def annotate_presets_data = { "annotate-presets" => @annotate_presets }
 

data/lib/samagotchi/web/participant_access.rb

@@ -11,9 +11,12 @@ require_relative "../session_inbox"
 require_relative "../session_metrics"
 require_relative "../parent_report"
 require_relative "../participant_messages"
+require_relative "../participant_mode"
+require_relative "../participant_revise"
 require_relative "../participants"
 require_relative "../session"
 require_relative "../turn_checkpoint"
+require_relative "../turn_origin"
 require_relative "../verify_fresh"
 require_relative "../log"
 
@@ -254,32 +257,94 @@ module Samagotchi
                     .map { |entry| { id: entry.id, name: entry.name, kind: entry.kind, role: entry.role } }
       end
 
+      # POST …/cancel from a participant: only their own running turn, named
+      # by its turn_id. The live snapshot's turn must be that turn and
+      # theirs (its author is the grant's), and the worker is asked to
+      # cancel that turn id (TurnState#cancel! compares it under its lock,
+      # 409 turn_mismatch): a turn that ended and gave way to another
+      # person's between the read and the cancel is never stopped. No
+      # turn_id (the Bridge would cancel whatever runs), or a turn that
+      # isn't theirs: 403 not_permitted, audited. The reason is the
+      # server's, never the body's.
+      def participant_cancel(req, id)
+        parsed = parse_json(request_body(req))
+        turn_id = (parsed["turn_id"] if parsed.is_a?(Hash)).to_s.strip
+        return not_permitted_for(req, principal(req)) if turn_id.empty?
+
+        live = bridge_get_json(id, "snapshot")
+        return not_live(id) unless live.is_a?(Hash)
+
+        turn = live.dig("snapshot", "current_turn")
+        return json_response(409, { error: "not_running", detail: "no active turn to cancel", session_id: id }) unless turn.is_a?(Hash)
+        return not_permitted_for(req, principal(req)) unless own_running_turn?(principal(req).grant, turn, turn_id)
+        return cancel_unavailable(req) unless cancels_by_turn_id?(id)
+
+        relay_cancel(id, ->(client) { client.cancel(reason: PARTICIPANT_CANCEL_REASON, turn_id: turn_id) })
+      end
+
+      # Whether the session's live worker cancels only the turn_id it is
+      # named (Delivery::CANCEL_TURN_ID_FEATURE): an older one ignores it and
+      # would stop whatever runs, the owner's next turn too.
+      def cancels_by_turn_id?(id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        Array(ParticipantMode.live_features(session, default_state_dir)).include?(Delivery::CANCEL_TURN_ID_FEATURE)
+      end
+
+      # 409 cancel_unavailable, audited; nothing is relayed.
+      def cancel_unavailable(req)
+        audit_refused(req, principal(req).grant, reason: "cancel_unavailable")
+        error_response(409, "cancel_unavailable", ParticipantMessages::CANCEL_UNAVAILABLE)
+      end
+
+      # Bridge::CANCEL_REASONS' "user": the person who sent it stopped it.
+      PARTICIPANT_CANCEL_REASON = "user"
+
+      # Whether the snapshot's running +turn+ is +turn_id+ and +grant+'s.
+      def own_running_turn?(grant, turn, turn_id)
+        author = turn["author"] || TurnOrigin.from(turn["origin"])&.author
+        turn["turn_id"].to_s == turn_id && author.to_s == grant.author
+      end
+
       # ── A participant's turn ──────────────────────────────────────────
 
-      # POST /api/sessions/:id/turn from a participant: a review turn (D6,
-      # D10). Of the body only the prompt counts: the author and client id
-      # are the grant's (review:<id>), the delivery is always queue, no
-      # images, no no_interrupt; the owner's prompt history never sees it.
-      # Refused: a line starting ! or / (403 not_permitted: shell lines
-      # and commands are the owner's), images (403), their turn limit (429
-      # too_many_turns, the Bridge counts) and their cap (429 cap_reached).
+      # POST /api/sessions/:id/turn from a participant: their turn (D6,
+      # D10). Of the body only the prompt, the delivery and images they
+      # uploaded count: the author and client id are the grant's
+      # (review:<id>), no no_interrupt; the owner's prompt history never
+      # sees it. The delivery
+      # is queue or next step (none: next step): the worker puts a next-step
+      # message into a running turn only when that turn is theirs, else it
+      # runs as their own turn after it (Bridge#same_author_steer?; an older
+      # worker queues it). Refused: a line starting ! or / (403
+      # not_permitted: shell lines and commands are the owner's), a cut
+      # (403: theirs never cuts), their cap (429 cap_reached), images not
+      # theirs or a model without vision (ParticipantImages#
+      # participant_images_refusal) and their turn limit (429
+      # too_many_turns, the Bridge counts).
       # Every answer is audited (turn: accepted or refused, why).
       def handle_participant_turn(req, id, body)
         grant = principal(req).grant
         prompt = body["prompt"].to_s
         return error_response(400, "missing_fields", "prompt is required") if prompt.strip.empty?
 
-        reason = participant_turn_refusal(grant, prompt, body)
-        return participant_turn_refused(grant, prompt, *reason) if reason
+        anchors = TurnAnchors.from(body)
+        revises = anchors.revises&.turn_id
+        reason = participant_turn_refusal(grant, prompt, body) || participant_revise_refusal(grant, id, anchors)
+        return participant_turn_refused(grant, prompt, *reason, revises: revises) if reason
+
+        reason, images = participant_images_refusal(grant, id, body["images"])
+        return participant_turn_refused(grant, prompt, *reason, revises: revises) if reason
 
-        # A Verify turn's claim; never a Revise (the owner's stacks).
+        # A Verify turn's claim, a Revise turn's draft of their own answer.
+        delivery = Delivery.queue?(body["delivery"]) ? Delivery::QUEUE : Delivery::NEXT_STEP
         result = SessionManager.deliver_turn(id, prompt: prompt, client_id: ClientId.review(grant.id),
-                                                 delivery: Delivery::QUEUE, author: grant.author,
-                                                 anchors: TurnAnchors.from(body).without_revises,
+                                                 delivery: delivery, author: grant.author,
+                                                 **(images.empty? ? {} : { images: images }),
+                                                 anchors: anchors,
                                                  pending_limit: grant.queue_limit + 1,
                                                  state_dir: @state_dir, manager: @manager,
                                                  bridge: -> { live_bridge_client(id) })
-        participant_turn_result(grant, prompt, result)
+        participant_turn_result(grant, prompt, result, images: images.empty? ? nil : images.size, revises: revises)
       rescue SessionManager::OwnedByTUI => e
         owned_by_tui(e)
       end
@@ -287,11 +352,35 @@ module Samagotchi
       # [status, code, detail] for a turn refused before delivery, nil to send it.
       def participant_turn_refusal(grant, prompt, body)
         return [403, "not_permitted", NOT_PERMITTED] if prompt.lstrip.start_with?("!", "/")
-        return [403, "not_permitted", NOT_PERMITTED] unless body["images"].nil? || body["images"] == []
+        return [403, "not_permitted", NOT_PERMITTED] if Delivery.cut?(body["delivery"])
 
         participant_cap_refusal(grant)
       end
 
+      # [status, code, detail] for a Revise draft (+anchors+' revises) they
+      # may not send, nil without one or when they may: a live worker
+      # without ReviseAnchor::PARTICIPANT_FEATURE (409 revise_unavailable:
+      # it wouldn't check it at the stamp), then ParticipantRevise over the
+      # messages a live worker's snapshot has (the session file lags it
+      # mid-turn and just after a turn's end), the file's only with no
+      # live worker: 403 revise_not_own (a missing turn answers the same),
+      # 409 revise_overtaken. The worker checks again at the stamp.
+      def participant_revise_refusal(grant, id, anchors)
+        return nil unless anchors.revises
+
+        session = @session_class.load(id, state_dir: default_state_dir)
+        features = ParticipantMode.live_features(session, default_state_dir)
+        if features && !features.include?(ReviseAnchor::PARTICIPANT_FEATURE)
+          return [409, "revise_unavailable", ParticipantMessages::REVISE_UNAVAILABLE]
+        end
+
+        messages = show_reads(id, session).raw_messages
+        case ParticipantRevise.refusal(messages, turn_id: anchors.revises.turn_id, author: grant.author)
+        when :not_own then [403, "revise_not_own", ParticipantMessages::REVISE_NOT_OWN]
+        when :overtaken then [409, "revise_overtaken", ParticipantMessages::REVISE_OVERTAKEN]
+        end
+      end
+
       # [429, cap_reached, …] once the grant spent its cap (D7: their turns
       # and the side requests they caused, from the session's saved
       # analytics, and their Verify fresh children's; a running turn's
@@ -311,23 +400,36 @@ module Samagotchi
           VerifyFresh.children_spend(grant.session_id, grant.author, state_dir: default_state_dir)
       end
 
-      def participant_turn_refused(grant, prompt, status, code, detail)
-        audit_turn(grant, prompt, status: "refused", reason: code)
+      # +audit_detail+: what only the audit line says (no_vision's full
+      # words); +revises+: the turn id a Revise draft named (nil: none).
+      def participant_turn_refused(grant, prompt, status, code, detail, audit_detail = nil, revises: nil)
+        audit_turn(grant, prompt, status: "refused", reason: code, detail: audit_detail, revises: revises)
         error_response(status, code, detail)
       end
 
-      def participant_turn_result(grant, prompt, result)
+      # +images+: how many the turn carried (nil: none), +revises+ the turn
+      # id its Revise draft named, for the audit line.
+      def participant_turn_result(grant, prompt, result, images: nil, revises: nil)
         case result.status
         when :accepted
           enqueued_id = result.ack["enqueued_id"]
           remember_participant_turn(enqueued_id, grant.id)
-          audit_turn(grant, prompt, status: "accepted", enqueued_id: enqueued_id)
-          json_response(202, result.ack.merge("via" => result.via.to_s, "delivery" => Delivery::QUEUE))
+          audit_turn(grant, prompt, status: "accepted", enqueued_id: enqueued_id, images: images, revises: revises)
+          # What the worker says will happen (a turn of its own, or into
+          # their running turn at its next step); a file (no worker yet)
+          # runs as the next turn, which reads as a queue.
+          json_response(202, result.ack.merge("via" => result.via.to_s, "delivery" => result.ack["delivery"] || Delivery::QUEUE))
         when :refused
-          audit_turn(grant, prompt, status: "refused", reason: result.ack["error"])
+          audit_turn(grant, prompt, status: "refused", reason: result.ack["error"], images: images, revises: revises)
+          # A worker without Revise at all: the participant's words, never
+          # the owner's "restart this session".
+          if result.ack["error"] == ReviseAnchor::UNAVAILABLE["error"]
+            return error_response(409, "revise_unavailable", ParticipantMessages::REVISE_UNAVAILABLE)
+          end
+
           json_response(result.code, result.ack)
         when :timeout
-          audit_turn(grant, prompt, status: "refused", reason: "worker_timeout")
+          audit_turn(grant, prompt, status: "refused", reason: "worker_timeout", images: images, revises: revises)
           error_response(504, "worker_timeout", result.detail)
         else error_response(500, "enqueue_failed", "could not write turn input")
         end
@@ -416,17 +518,18 @@ module Samagotchi
       # answer trimmed to what their turn's reply is (status, text, turn
       # id, a cancel's reason): no file path, no question (an approval or a
       # question their turn raised is the owner's to answer: the status
-      # says waiting_for_owner), no origin, no parent strategy. It waits as
-      # for a queued turn (theirs always is: never merged), so it never
-      # falls back to the next reply past a cursor, which would be anyone's;
-      # the body's cursor doesn't count. A revoke or the expiry ends a wait
+      # says waiting_for_owner), no origin, no parent strategy. It waits on
+      # their turn's id, so it never falls back to the next reply past a
+      # cursor, which would be anyone's (the body's cursor doesn't count);
+      # a message merged into their own running turn is followed into it by
+      # its merge record (ReplyWait::Poll#follow_merge), a turn of theirs. A revoke or the expiry ends a wait
       # already running (the gate checked the grant when it began): 401
       # token_revoked / token_expired, as their next request would get.
       def participant_wait(req, id, options)
         grant = principal(req).grant
         return not_permitted_for(req, principal(req)) unless own_turn?(grant, id, options[:turn])
 
-        options = options.merge(queued: true, cursor: nil)
+        options = options.merge(queued: false, cursor: nil)
         session = session_access.show(id)
         result = session_access.wait_reply(id, **options, poll_interval: @wait_poll_interval,
                                                cancelled: -> { !@server_running.call || !@grants.active?(grant.id) })

data/lib/samagotchi/web/participant_images.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "../grants"
+require_relative "../image_store"
+require_relative "../participant_messages"
+require_relative "../participant_uploads"
+require_relative "../participants"
+require_relative "../send_command"
+require_relative "../session"
+
+module Samagotchi
+  module Web
+    # A participant's images, mixed into App: their uploads (POST
+    # /api/sessions/:id/images) and reading their own back (GET
+    # …/images/<hash>.<ext>). Ownership is ParticipantUploads' record alone,
+    # written here, under @participant_images_mutex. Their turn's refs are
+    # checked by ParticipantAccess#participant_images_refusal. See
+    # docs/internals/participants.md (Participant images).
+    module ParticipantImages
+      # One upload's answer: +ref+ when accepted, else +status+, +code+ and
+      # +detail+; +bytes+ the stored size (for the audit line).
+      Upload = Data.define(:status, :code, :detail, :ref, :bytes) do
+        def self.refused(status, code, detail) = new(status: status, code: code, detail: detail, ref: nil, bytes: nil)
+        def self.accepted(ref) = new(status: 201, code: nil, detail: nil, ref: ref, bytes: ref[:bytes])
+      end
+
+      private
+
+      # The largest image a participant may upload, by its header: pixels
+      # and either side (a phone's 4032×3024 passes). Checked before any
+      # tool reads their bytes.
+      MAX_PARTICIPANT_PIXELS = 40_000_000
+      MAX_PARTICIPANT_SIDE = 12_000
+
+      def init_participant_images
+        @participant_images_mutex = Mutex.new
+        # One participant conversion (ImageStore.ingest, which may run sips
+        # or magick on their bytes) at a time, whoever's.
+        @participant_conversion_mutex = Mutex.new
+      end
+
+      # POST /api/sessions/:id/images from a participant. Every upload
+      # counts as an attempt first (before the cap check). Refused, in
+      # order: their cap (429 cap_reached), their attempts (429
+      # too_many_image_attempts, refused ones counted), the size (413, as
+      # the owner's), not an image (422 bad_image), a bmp/tiff/heic (422
+      # unsupported_image: chi converts those with an external tool), no
+      # size in its header or over MAX_PARTICIPANT_PIXELS / _SIDE (422
+      # image_too_big), their quota (429 too_many_images; a file they own
+      # already is accepted again, no new entry). Every answer is audited,
+      # an exception too (internal_error, then raised). The reply is the ref
+      # without source, mime or bytes.
+      def participant_image_upload(req, id, session_dir)
+        grant = principal(req).grant
+        upload = begin
+          participant_upload(req, session_dir, grant)
+        rescue StandardError
+          audit_image(id, grant, Upload.refused(500, "internal_error", nil))
+          raise
+        end
+        audit_image(id, grant, upload)
+        return error_response(upload.status, upload.code, upload.detail) unless upload.ref
+
+        json_response(201, upload.ref.slice(:file, :name, :width, :height))
+      end
+
+      def audit_image(id, grant, upload)
+        Participants.log(id, :image, state_dir: default_state_dir, participant: grant.id,
+                                     status: upload.ref ? "accepted" : "refused",
+                                     **{ reason: upload.code, file: upload.ref&.dig(:file), bytes: upload.bytes }.compact)
+      end
+
+      def participant_upload(req, dir, grant)
+        over = @participant_images_mutex.synchronize do
+          record = ParticipantUploads.read(dir)
+          tried = record.attempts_of(grant.id)
+          ParticipantUploads.attempt!(dir, grant.id, state: record) if tried < Grants::MAX_IMAGE_ATTEMPTS
+          tried >= Grants::MAX_IMAGE_ATTEMPTS
+        end
+        if (cap = participant_cap_refusal(grant))
+          return Upload.refused(*cap)
+        end
+        if over
+          return Upload.refused(429, "too_many_image_attempts", ParticipantMessages::TOO_MANY_IMAGE_ATTEMPTS)
+        end
+
+        bytes = image_upload_bytes(req)
+        return Upload.refused(413, "too_large", image_too_large_detail) unless bytes
+
+        participant_store(dir, grant, bytes, upload_name(req))
+      end
+
+      def participant_store(dir, grant, bytes, name)
+        info = ImageHeader.read(bytes)
+        return Upload.refused(422, "bad_image", ParticipantMessages::BAD_IMAGE) unless info
+        if ImageHeader::CONVERTIBLE.include?(info.format)
+          return Upload.refused(422, "unsupported_image", ParticipantMessages::IMAGE_TYPE)
+        end
+        return Upload.refused(422, "image_too_big", ParticipantMessages::IMAGE_TOO_BIG) unless participant_size_ok?(info)
+
+        # At quota: only a file they own already, named as its bytes would
+        # be stored unchanged (a downscaled or re-encoded one is refused).
+        raw = ImageStore.file_name_for(bytes, info.format)
+        again = @participant_images_mutex.synchronize do
+          record = ParticipantUploads.read(dir)
+          next nil if record.count(grant.id) < Grants::MAX_IMAGES
+
+          record.owned?(raw, grant.id)
+        end
+        return Upload.accepted(ImageStore.ref_for(dir, file: raw, name: name)) if again
+        return too_many_images if again == false
+
+        participant_ingest(dir, grant, bytes, name)
+      rescue ImageStore::Error
+        Upload.refused(422, "bad_image", ParticipantMessages::BAD_IMAGE)
+      end
+
+      # Whether +info+'s header gives a size within the participant limits.
+      def participant_size_ok?(info)
+        return false unless info.width.is_a?(Integer) && info.height.is_a?(Integer) && info.width.positive? && info.height.positive?
+
+        [info.width, info.height].max <= MAX_PARTICIPANT_SIDE && info.width * info.height <= MAX_PARTICIPANT_PIXELS
+      end
+
+      # Stores their image, then records it: the quota checked again under
+      # the mutex (a race past it is refused here; the stored file may stay
+      # in images/, unreachable to them without a record).
+      def participant_ingest(dir, grant, bytes, name)
+        ref = @participant_conversion_mutex.synchronize { ImageStore.ingest(dir, bytes: bytes, name: name, source: "user") }
+        added = @participant_images_mutex.synchronize do
+          record = ParticipantUploads.read(dir)
+          next true if record.owned?(ref[:file], grant.id)
+          next false if record.count(grant.id) >= Grants::MAX_IMAGES
+
+          ParticipantUploads.add(dir, file: ref[:file], grant_id: grant.id, state: record)
+        end
+        added ? Upload.accepted(ref) : too_many_images
+      end
+
+      # A participant's turn's images: [nil, refs] to deliver (refs [] for
+      # none), or [[status, code, detail(, audit detail)], nil]. In this
+      # order, so nothing tells them which files exist: the shape (400
+      # bad_images), then ownership (403 not_permitted for any ref they
+      # didn't upload, there or not), only then the files (ImageStore.
+      # check_refs), then the model (422 no_vision in their words; the
+      # model's name and the /model hint only in the audit line).
+      def participant_images_refusal(grant, id, raw)
+        return [nil, []] if raw.nil? || raw == []
+        return [[400, "bad_images", ParticipantMessages::IMAGES_SHAPE], nil] unless participant_refs_shape?(raw)
+
+        dir = Session.session_dir(id, state_dir: default_state_dir)
+        record = @participant_images_mutex.synchronize { ParticipantUploads.read(dir) }
+        owned = raw.all? { |ref| record.owned?(ref["file"].to_s, grant.id) }
+        return [[403, "not_permitted", ParticipantMessages::NOT_PERMITTED], nil] unless owned
+
+        images = ImageStore.check_refs(dir, raw)
+        return [[400, "bad_images", ParticipantMessages::IMAGE_GONE, images], nil] if images.is_a?(String)
+
+        refusal = participant_vision_refusal(id)
+        refusal ? [[422, "no_vision", ParticipantMessages::NO_VISION, refusal], nil] : [nil, images]
+      end
+
+      def participant_refs_shape?(raw)
+        raw.is_a?(Array) && raw.size <= ImageStore::MAX_TURN_REFS &&
+          raw.all? { |ref| ref.is_a?(Hash) && ref["file"].is_a?(String) && !ref.key?("path") }
+      end
+
+      # chi send's refusal for this session's model, nil when it takes
+      # images or nobody knows (the Engine stays the backstop). The model's
+      # name can lag a live /model.
+      def participant_vision_refusal(id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        SendCommand.vision_refusal_for(session.model_name, typed: session.model_typed)
+      end
+
+      # Whether the request's participant uploaded <session_dir>/images/+name+
+      # (a bare "<hash>.<ext>"): the record alone (they had the bytes).
+      def participant_owns_image?(req, session_dir, name)
+        ParticipantUploads.owned?(session_dir, "#{ImageStore::DIR}/#{name}", principal(req).grant.id)
+      end
+
+      def too_many_images = Upload.refused(429, "too_many_images", ParticipantMessages::TOO_MANY_IMAGES)
+    end
+  end
+end