monkrb 0.17.0 → 0.18.0

data/lib/monk/jobs/runtime.rb

@@ -0,0 +1,239 @@
+require "socket"
+require_relative "../jobs"
+require_relative "worker"
+
+module Monk
+  module Jobs
+    # A job process (bin/jobs): the supervisor in the calling Ractor and N
+    # worker Ractors (docs/history/plan-jobs.md Phase 6). Opt-in on its own,
+    # require "monk/jobs/runtime" -- the web process only enqueues.
+    #
+    #   Monk::Jobs::Runtime.new(queues: %w[mailers default], workers: 5).run
+    #
+    # run blocks until TERM or INT (or #stop): workers finish the job in
+    # hand, up to shutdown_timeout seconds, and whatever is still running
+    # then is released for another process.
+    class Runtime
+      DEFAULTS = {
+        queues: [Job::DEFAULT_QUEUE], workers: 5, poll_interval: 1.0, tick_interval: 1.0,
+        heartbeat_interval: 15, process_timeout: 120, shutdown_timeout: 25,
+      }.freeze
+
+      # queues: claimed in this order, so earlier ones go first.
+      # poll_interval: seconds an idle worker waits before claiming again.
+      # tick_interval: seconds between the supervisor's rounds of staging
+      #   due jobs (so also how late a scheduled job can start).
+      # heartbeat_interval: seconds between this process's heartbeats, and
+      #   between its looks for dead processes to prune.
+      # process_timeout: seconds of silence after which another process's
+      #   running jobs are released.
+      # shutdown_timeout: seconds a stop waits for jobs in flight.
+      def initialize(**settings)
+        unknown = settings.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown Monk::Jobs::Runtime setting(s): #{unknown.join(", ")}" if unknown.any?
+
+        settings = DEFAULTS.merge(settings)
+        @queues = checked_queues(settings[:queues])
+        @worker_count = settings[:workers]
+        unless positive_integer?(@worker_count)
+          raise ArgumentError, "workers must be a positive Integer, got #{@worker_count.inspect}"
+        end
+
+        %i[poll_interval tick_interval heartbeat_interval process_timeout shutdown_timeout].each do |name|
+          value = settings[name]
+          unless value.is_a?(Numeric) && value.positive?
+            raise ArgumentError, "#{name} must be a positive number of seconds, got #{value.inspect}"
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+        @stopping = false
+      end
+
+      def run(trap_signals: true)
+        Monk.freeze!
+        @adapter = Monk::Jobs.adapter
+        @hostname = Socket.gethostname
+        @pid = Process.pid
+        @process_id = @adapter.register_process(hostname: @hostname, pid: @pid)
+        trap_signals! if trap_signals
+
+        @monitors = {} # monitor port => [worker index, its Ractor]
+        @controls = {} # worker index => its control port
+        @holding = {} # worker index => id of the job it's running
+        @to_release = [] # ids of jobs dead workers held, not yet released
+        @holding_port = Ractor::Port.new
+        @worker_count.times { |index| spawn_worker(index) }
+        Monk::Log.info(
+          "Monk::Jobs process #{@process_id} started: #{@worker_count} workers on #{@queues.join(", ")} (pid #{@pid})",
+        )
+
+        ticker, timer = start_ticker
+        supervise(ticker)
+        shut_down(ticker)
+      ensure
+        timer&.kill
+        ticker&.close
+        @holding_port&.close
+      end
+
+      # Asks run to stop; safe from a signal handler or another thread.
+      def stop
+        @stopping = true
+      end
+
+      private
+
+      def supervise(ticker)
+        last_heartbeat = monotonic
+        dead = []
+        until @stopping
+          port, message = Ractor.select(ticker, @holding_port, *@monitors.keys)
+          if port.equal?(ticker)
+            last_heartbeat = tick(last_heartbeat)
+            # Respawned on the next tick rather than at once, so a worker
+            # that dies straight away (the database is down) can't spin.
+            dead.each { |index| spawn_worker(index) }
+            dead.clear
+          elsif port.equal?(@holding_port)
+            index, id = message
+            id ? @holding[index] = id : @holding.delete(index)
+          else
+            dead << worker_exited(port)
+          end
+        end
+      end
+
+      # A database error here (Postgres restarting, a dropped connection)
+      # mustn't end the process: it's logged, this Ractor's connection is
+      # reset, and the next tick tries again.
+      def tick(last_heartbeat)
+        release_dead_workers_jobs
+        @adapter.stage_due
+        return last_heartbeat if monotonic - last_heartbeat < @heartbeat_interval
+
+        beat
+        monotonic
+      rescue StandardError => e
+        Monk::Log.error("Monk::Jobs supervisor: #{Monk::Jobs.describe_error(e)}; reconnecting")
+        reconnect
+        last_heartbeat
+      end
+
+      # A job stays on the list until its release has gone through (or found
+      # the job no longer held), so a database error just retries it next tick.
+      def release_dead_workers_jobs
+        until @to_release.empty?
+          @adapter.release(@to_release.first, @process_id)
+          @to_release.shift
+        end
+      end
+
+      def reconnect
+        @adapter.reset_connection
+      rescue StandardError => e
+        Monk::Log.error("Monk::Jobs supervisor: can't reconnect yet (#{e.class}: #{e.message})")
+      end
+
+      def beat
+        @adapter.heartbeat(@process_id, hostname: @hostname, pid: @pid)
+        released = @adapter.prune(@process_timeout)
+        return unless released.positive?
+
+        Monk::Log.warn("Monk::Jobs: released #{released} job(s) of processes silent for #{@process_timeout}s")
+      end
+
+      def spawn_worker(index)
+        hello = Ractor::Port.new
+        args = [@adapter, @process_id, @queues, @poll_interval, hello, @holding_port, index]
+        ractor = Ractor.new(*args, name: "monk-jobs-worker-#{index}") { |*worker_args| Monk::Jobs::Worker.run(*worker_args) }
+        @controls[index] = hello.receive
+        monitor = Ractor::Port.new
+        ractor.monitor(monitor)
+        @monitors[monitor] = [index, ractor]
+      ensure
+        hello&.close
+      end
+
+      # One port per worker: Ractor#monitor's message is a bare :exited or
+      # :aborted that doesn't say which Ractor (Phase 0.4).
+      def worker_exited(port)
+        index, ractor = @monitors.delete(port)
+        @controls.delete(index)
+        held = @holding.delete(index)
+        @to_release << held if held
+        begin
+          ractor.value
+          Monk::Log.warn("Monk::Jobs: worker #{index} exited; starting a new one")
+        rescue Ractor::RemoteError => e
+          Monk::Log.error("Monk::Jobs: worker #{index} died; starting a new one. #{Monk::Jobs.describe_error(e.cause)}")
+        end
+        index
+      end
+
+      def shut_down(ticker)
+        Monk::Log.info(
+          "Monk::Jobs process #{@process_id} stopping: waiting up to #{@shutdown_timeout}s for jobs in flight",
+        )
+        @controls.each_value do |control|
+          control << :stop
+        rescue Ractor::ClosedError
+          nil
+        end
+
+        deadline = monotonic + @shutdown_timeout
+        until @monitors.empty? || monotonic >= deadline
+          port, = Ractor.select(ticker, *@monitors.keys)
+          @monitors.delete(port) unless port.equal?(ticker)
+        end
+        unless @monitors.empty?
+          Monk::Log.warn(
+            "Monk::Jobs: #{@monitors.size} worker(s) still busy after #{@shutdown_timeout}s; releasing their jobs",
+          )
+        end
+
+        begin
+          @adapter.deregister(@process_id)
+        rescue StandardError => e
+          # Its jobs are released by another process's pruning instead.
+          Monk::Log.error("Monk::Jobs process #{@process_id} couldn't deregister: #{e.class}: #{e.message}")
+        end
+        Monk::Log.info("Monk::Jobs process #{@process_id} stopped")
+      end
+
+      def start_ticker
+        ticker = Ractor::Port.new
+        interval = @tick_interval
+        timer = Thread.new do
+          loop do
+            sleep interval
+            ticker << :tick
+          end
+        rescue Ractor::ClosedError
+          nil
+        end
+        [ticker, timer]
+      end
+
+      def trap_signals!
+        %w[TERM INT].each { |signal| Signal.trap(signal) { stop } }
+      end
+
+      def checked_queues(queues)
+        unless queues.is_a?(Array) && queues.any? && queues.all? { |q| q.is_a?(String) && !q.empty? }
+          raise ArgumentError, "queues must be a non-empty Array of queue names, got #{queues.inspect}"
+        end
+
+        Ractor.make_shareable(queues.map(&:dup))
+      end
+
+      def positive_integer?(value)
+        value.is_a?(Integer) && value.positive?
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/monk/jobs/worker.rb

@@ -0,0 +1,94 @@
+require "timeout"
+
+module Monk
+  module Jobs
+    # One worker Ractor's loop (docs/history/plan-jobs.md Phase 6): claim
+    # from the queues in order, run the job, finish or fail it, and wait
+    # poll_interval when there's nothing to claim. Plain module methods,
+    # not blocks, so they're callable from any Ractor.
+    module Worker
+      # Failures that retrying can't fix.
+      NEVER_RETRY = [UnknownJobError, NotImplementedError].freeze
+
+      # The body of a worker Ractor, until the supervisor sends :stop on the
+      # control port handed back through `hello`. A stop is only noticed
+      # between jobs, never in the middle of one. `holding` tells the
+      # supervisor which job this worker has, [index, id] after a claim and
+      # [index, nil] once it's finished or failed, so a job whose worker
+      # dies in between can be released.
+      def self.run(adapter, process_id, queues, poll_interval, hello, holding, index)
+        # The supervisor logs why a worker ended, backtrace included; don't
+        # also dump it to stderr.
+        Thread.current.report_on_exception = false
+        control = Ractor::Port.new
+        hello << control
+        wake = Thread::Queue.new
+        stopping = false
+        Thread.new do
+          control.receive
+          stopping = true
+          wake << :stop
+        end
+
+        until stopping
+          claim = next_claim(adapter, queues, process_id)
+          next wake.pop(timeout: poll_interval) unless claim
+
+          holding << [index, claim.id]
+          perform(adapter, process_id, claim)
+          holding << [index, nil]
+        end
+      end
+
+      def self.next_claim(adapter, queues, process_id)
+        queues.each do |queue|
+          claim = adapter.claim(queue, process_id)
+          return claim if claim
+        end
+        nil
+      end
+
+      # Every exception fails the job, not only StandardErrors: one that
+      # escaped would leave the job running inside a live process, which
+      # pruning never touches. A non-StandardError is re-raised afterwards,
+      # ending this Ractor so the supervisor starts a fresh one.
+      def self.perform(adapter, process_id, claim)
+        job = nil
+        error = begin
+          job = Monk::Jobs.lookup(claim.job_class)
+          run_job(job, claim.args)
+          nil
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          e
+        end
+        return adapter.finish(claim.id, process_id) unless error
+
+        record_failure(adapter, process_id, claim, error, job)
+        raise error unless error.is_a?(StandardError) || error.is_a?(NotImplementedError)
+      end
+
+      def self.run_job(job, args)
+        return job.perform(*args) unless job.timeout
+
+        Timeout.timeout(job.timeout) { job.perform(*args) }
+      end
+
+      # job is nil when its class couldn't be found (UnknownJobError).
+      def self.record_failure(adapter, process_id, claim, error, job)
+        # Phase 0.3: the interrupted query is still running on the server,
+        # and this connection's next query would wait for it.
+        adapter.reset_connection if error.is_a?(Timeout::Error)
+
+        never_retry = NEVER_RETRY + (job ? job.never_retry : [])
+        retry_in = never_retry.any? { |klass| error.is_a?(klass) } ? nil : Monk::Jobs.backoff(claim.attempts)
+        outcome = adapter.fail(claim.id, process_id, error: Monk::Jobs.describe_error(error), retry_in: retry_in)
+        outcomes = { scheduled: "retrying in #{retry_in}s", failed: "failed for good" }
+        what_next = outcomes.fetch(outcome, "no longer held")
+        Monk::Log.error(
+          "Monk::Jobs: #{claim.job_class} (job #{claim.id}, attempt #{claim.attempts}) failed with " \
+          "#{error.class}: #{error.message} -- #{what_next}",
+        )
+      end
+    end
+  end
+end

data/lib/monk/jobs.rb

@@ -0,0 +1,229 @@
+# The whole framework, as monk/live does: jobs use Monk.freeze!, Monk::Log
+# and Monk.env, and a job process (bin/jobs) may load nothing else first.
+require_relative "../monk"
+require_relative "jobs/errors"
+require_relative "jobs/args"
+require "json"
+
+module Monk
+  # Background jobs on Postgres. Opt-in: require "monk/jobs" explicitly --
+  # `require "monk"` alone does not load this. Design:
+  # docs/adr/0013-jobs-narrow-state-table-plus-payloads.md; plan:
+  # docs/history/plan-jobs.md.
+  module Jobs
+    # last_error keeps the first lines of a failure, not all of it.
+    MAX_ERROR_LENGTH = 4_000
+    BACKTRACE_LINES = 10
+
+    # The process id drain! claims jobs as: never a monk_processes id, which
+    # starts at 1.
+    DRAIN_PROCESS_ID = 0
+
+    class << self
+      # Typically, in config/jobs.rb:
+      #
+      #   Monk::Jobs.configure(db_name: :primary)
+      #
+      # db_name: is a database registered with Monk::Persistence::Pg. The
+      # app's own database by default, so a job can be enqueued inside the
+      # app's own transaction; a separate one isolates the queue from the
+      # app's long transactions (docs/adr/0013-jobs-narrow-state-table-plus-payloads.md).
+      # Tests use the app's test database, the same way: enqueue, drain!,
+      # and clear! between tests.
+      def configure(db_name:)
+        require_relative "jobs/adapters/pg"
+        @adapter = Adapters::Pg.new(db_name: db_name)
+      end
+
+      # The configured adapter. Shareable (it freezes itself), so a worker
+      # Ractor reads it straight off this module.
+      def adapter
+        @adapter || raise(NotConfiguredError, "call Monk::Jobs.configure(db_name:) before enqueueing or running jobs")
+      end
+
+      # Stores a job to run later; returns its id. args are passed to the
+      # job's self.perform as they are, and must be plain JSON values
+      # (Args.check!). Options:
+      #
+      #   wait: 60                  run no sooner than 60 seconds from now
+      #   at: Time                  run no sooner than then
+      #   conn: a PG::Connection    enqueue on it, inside its transaction, so
+      #                             the job commits or rolls back with the
+      #                             app's own writes
+      #
+      # SendReceipt.enqueue(order_id) is the same call.
+      def enqueue(job_class, *args, wait: nil, at: nil, conn: nil)
+        check_enqueueable!(job_class)
+        Args.check!(args)
+        check_schedule!(wait, at)
+
+        adapter.enqueue(
+          job_class: job_class.name, queue: job_class.queue, priority: job_class.priority,
+          max_attempts: job_class.max_attempts, args: JSON.generate(args), wait: wait, at: at, conn: conn,
+        )
+      end
+
+      # Called by Monk::Job.inherited, in the main Ractor as the app's job
+      # files load. Only recorded here: names are resolved when the
+      # registry is frozen, so a class that gets its constant name after
+      # being created (Foo = Class.new(Monk::Job)) is still found.
+      def record(job_class)
+        classes << job_class
+      end
+
+      # The Monk::Job subclass a monk_job_payloads.job_class names. Only
+      # ever answers with a recorded job class -- never Object.const_get
+      # on a String read from the database. Reads nothing but the frozen
+      # registry, so it works the same from any Ractor.
+      def lookup(name)
+        registry = @registry
+        if registry.nil?
+          raise NotFrozenError,
+            "Monk::Jobs.lookup(#{name.inspect}) before the job registry is frozen -- call Monk.boot(app) " \
+            "(or Monk.freeze!) in the main Ractor first, after the app's job classes are loaded"
+        end
+
+        registry.fetch(name) do
+          raise UnknownJobError, "no Monk::Job subclass named #{name.inspect} is loaded in this process"
+        end
+      end
+
+      # Called from Monk.freeze! via Monk.freeze_hooks. Rebuilds the map
+      # from every named job class recorded so far, so freezing twice (two
+      # apps, or a test suite) is harmless. Anonymous classes are skipped:
+      # without a name a job can never be found again once enqueued.
+      def freeze_registry!
+        @registry = Ractor.make_shareable(classes.filter_map { |job| [job.name, job] if job.name }.to_h)
+      end
+
+      # A failed job back to available, with its attempts reset; true if it
+      # was failed. Failed jobs stay in monk_jobs until retried or discarded.
+      def retry_failed(id)
+        adapter.retry_failed(id)
+      end
+
+      # Deletes a failed job; true if it was failed.
+      def discard_failed(id)
+        adapter.discard_failed(id)
+      end
+
+      # Seconds to wait before retrying a job that has failed `attempts`
+      # times: 16, 31, 96, 271, 640, ... (Sidekiq's curve, without its
+      # random jitter).
+      def backoff(attempts)
+        (attempts**4) + 15
+      end
+
+      # What goes in last_error: the class and message, then the first
+      # BACKTRACE_LINES of the backtrace, capped at MAX_ERROR_LENGTH.
+      def describe_error(error)
+        lines = ["#{error.class}: #{error.message}", *Array(error.backtrace).first(BACKTRACE_LINES)]
+        lines.join("\n")[0, MAX_ERROR_LENGTH]
+      end
+
+      # Runs every job that's due, one after another, until none is left --
+      # including jobs those jobs enqueue -- and returns how many ran. For
+      # an app's tests: enqueue, drain!, then assert on what the jobs did.
+      # Nothing is retried: the first job that raises is marked failed and
+      # its error re-raised here.
+      #
+      # Each job runs in a throwaway Ractor, as it would in bin/jobs, so a
+      # job that only works in the main Ractor (a gem with module-level
+      # state, a non-shareable constant) fails in the test too.
+      # in_ractor: false runs jobs in the calling Ractor instead, for a test
+      # that needs to see a job's side effects there.
+      #
+      # Calls Monk.freeze! first, as bin/jobs does, so jobs can read the
+      # app's frozen configuration from their Ractor.
+      def drain!(in_ractor: true)
+        Monk.freeze!
+        queues = classes.map(&:queue) | [Job::DEFAULT_QUEUE]
+        ran = 0
+        loop do
+          nil while adapter.stage_due.positive?
+          claim = queues.lazy.filter_map { |queue| adapter.claim(queue, DRAIN_PROCESS_ID) }.first
+          break unless claim
+
+          run_drained(claim, in_ractor)
+          ran += 1
+        end
+        ran
+      end
+
+      # Empties the queue: every job, failed ones included, and every job
+      # process row. For an app's tests, between one test and the next --
+      # and so it refuses to run unless MONK_ENV is test.
+      def clear!
+        unless Monk.env.test?
+          raise ClearOutsideTestsError,
+            "Monk::Jobs.clear! empties the whole queue, so it only runs with MONK_ENV=test (this is #{Monk.env})"
+        end
+
+        adapter.clear!
+      end
+
+      # Test-only: unfreezes the registry and forgets the configuration.
+      # Recorded classes stay recorded, the same way a Ruby class can't be
+      # undefined.
+      def reset!
+        @registry = nil
+        @adapter = nil
+      end
+
+      private
+
+      def run_drained(claim, in_ractor)
+        begin
+          job = lookup(claim.job_class)
+          in_ractor ? perform_in_ractor(job, claim.args) : job.perform(*claim.args)
+        # NotImplementedError too, a job class with no self.perform: it's a
+        # ScriptError, not a StandardError, and would otherwise leave the job
+        # running.
+        rescue StandardError, NotImplementedError => e
+          adapter.fail(claim.id, DRAIN_PROCESS_ID, error: describe_error(e), retry_in: nil)
+          raise
+        end
+        adapter.finish(claim.id, DRAIN_PROCESS_ID)
+      end
+
+      def perform_in_ractor(job, args)
+        Ractor.new(job, args) do |job, args|
+          # The error is re-raised in the caller; don't also print it here.
+          Thread.current.report_on_exception = false
+          job.perform(*args)
+          nil
+        end.value
+      rescue Ractor::RemoteError => e
+        # The job's own error, as if it had run here. cause: nil, or Ruby
+        # would chain the RemoteError onto it -- whose cause it already is.
+        raise e.cause, cause: nil
+      end
+
+      def check_enqueueable!(job_class)
+        unless job_class.is_a?(Class) && job_class < Monk::Job
+          raise ArgumentError, "Monk::Jobs.enqueue needs a Monk::Job subclass, got #{job_class.inspect}"
+        end
+        return if job_class.name
+
+        raise ArgumentError,
+          "#{job_class.inspect} has no name, so a worker could never find it again -- assign it to a constant"
+      end
+
+      def check_schedule!(wait, at)
+        raise ArgumentError, "pass wait: or at:, not both" if wait && at
+        if wait && !(wait.is_a?(Numeric) && wait >= 0)
+          raise ArgumentError, "wait: must be a number of seconds, zero or more, got #{wait.inspect}"
+        end
+        raise ArgumentError, "at: must be a Time, got #{at.inspect}" if at && !at.is_a?(Time)
+      end
+
+      def classes
+        @classes ||= []
+      end
+    end
+
+    Monk.freeze_hooks << self
+  end
+end
+
+require_relative "jobs/job"

data/lib/monk/mail/errors.rb

@@ -24,5 +24,12 @@ module Monk
     # refusing it. The transport's own exception is the #cause.
     class DeliveryError < StandardError
     end
+
+    # A DeliveryError the server made final: an SMTP 5xx (no such mailbox,
+    # relaying refused) or refused credentials. Raised by
+    # Monk::Mail::DeliveryJob (require "monk/mail/later") so the job isn't
+    # retried; still a DeliveryError, so a rescue of that catches it too.
+    class PermanentDeliveryError < DeliveryError
+    end
   end
 end

data/lib/monk/mail/later.rb

@@ -0,0 +1,53 @@
+require_relative "../mail"
+require_relative "../jobs"
+
+module Monk
+  module Mail
+    # Sends one message from a job process (docs/adr/0014-mail-from-jobs-and-login-links-created-in-the-job.md).
+    # Enqueued by Monk::Mail.deliver_later, never directly: its argument
+    # is the message's fields, already checked and with from: resolved.
+    class DeliveryJob < Monk::Job
+      queue "mailers"
+      never_retry PermanentDeliveryError
+
+      # The SMTP failures that are final, by class name so this file never
+      # loads net/smtp itself (the app's Gemfile decides that, ADR 0012):
+      # a 5xx reply, a malformed command, refused credentials. Everything
+      # else -- a 4xx "try later", a refused connection, TLS, a timeout --
+      # is worth retrying.
+      PERMANENT_SMTP_ERRORS = %w[Net::SMTPFatalError Net::SMTPSyntaxError Net::SMTPAuthenticationError].freeze
+
+      def self.perform(fields)
+        Monk::Mail.deliver(**fields.transform_keys(&:to_sym))
+      rescue DeliveryError => e
+        raise unless PERMANENT_SMTP_ERRORS.include?(e.cause&.class&.name)
+
+        raise PermanentDeliveryError, e.message
+      end
+    end
+
+    class << self
+      # deliver, later: the same arguments, plus enqueue's wait:, at: and
+      # conn: (the last one enqueues inside the caller's transaction, so the
+      # email commits or rolls back with the app's own writes). Returns the
+      # job's id. The message is built -- and so checked -- here, before
+      # anything is enqueued: bad input raises InvalidMessageError in the
+      # caller, exactly as deliver would, rather than failing later in the
+      # job process. Render HTML before calling (html: Monk::Mail.render(...)):
+      # the job stores the finished message and only sends it.
+      #
+      #   Monk::Mail.deliver_later(to: order[:email], subject: "Your receipt", text: receipt_text)
+      def deliver_later(to:, subject:, text: nil, html: nil, reply_to: nil, from: nil, wait: nil, at: nil, conn: nil)
+        raise NotConfiguredError, "call Monk::Mail.configure(url:, from:) before Monk::Mail.deliver_later" unless config
+
+        from ||= config[:from]
+        if from.nil?
+          raise InvalidMessageError, "no from: given, and Monk::Mail.configure has no default from: (MAIL_FROM)"
+        end
+
+        message = Message.new(from: from, to: to, subject: subject, text: text, html: html, reply_to: reply_to)
+        DeliveryJob.enqueue(message.to_h.transform_keys(&:to_s), wait: wait, at: at, conn: conn)
+      end
+    end
+  end
+end

data/lib/monk/persistence/pg.rb

@@ -1,3 +1,4 @@
+require "json"
 require "pg"
 
 require_relative "../persistence"
@@ -16,12 +17,31 @@ module Monk
     module Pg
       extend Monk::Persistence::Registry
 
+      # json/jsonb columns, decoded with plain JSON.parse. pg's own
+      # PG::TextDecoder::JSON (1.6.3) calls JSON.parse(string, quirks_mode:
+      # true), and json 3 removed that keyword, so with pg's default every
+      # json/jsonb read raised ArgumentError. json 3 parses a bare scalar
+      # ("7", "\"text\"") without it.
+      class JsonDecoder < PG::SimpleDecoder
+        def decode(string, _tuple = nil, _field = nil)
+          JSON.parse(string)
+        end
+      end
+
+      # pg's default result types, with JsonDecoder for json and jsonb.
+      # Built once and made shareable, so every Ractor's #connect can use
+      # it rather than building its own.
+      RESULT_TYPES = Ractor.make_shareable(
+        PG::BasicTypeRegistry.new.register_default_types
+          .tap { |types| %w[json jsonb].each { |name| types.register_type(0, name, nil, JsonDecoder) } },
+      )
+
       class << self
         private
 
         def connect(**opts)
           conn = PG.connect(**opts)
-          conn.type_map_for_results = PG::BasicTypeMapForResults.new(conn)
+          conn.type_map_for_results = PG::BasicTypeMapForResults.new(conn, registry: RESULT_TYPES)
           conn
         end