basecradle 0.10.2 → 0.11.0

data/lib/basecradle/contact_messages.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "api_object"
+require_relative "headers"
+require_relative "pagination"
+require_relative "serialization"
+require_relative "user"
+
+module BaseCradle
+  # Contact messages and notes are the platform's first **admin-only** surface. Every call
+  # in this file answers a non-admin with +NotAnAdminError+ (403, +not_an_admin+) — the
+  # SDK sends the request regardless, because the platform, not this library, decides who
+  # is an admin. +bc.me.admin+ is present only for an admin, if you want to ask first.
+
+  # --- models ---------------------------------------------------------------------------
+
+  # What a note is about: its subject's record type and uuid. Typed, because a note can be
+  # about any kind of record — today it is always a +"contact_message"+.
+  class Notable < ApiObject
+    attribute :type
+    attribute :uuid
+  end
+
+  # An admin's dated, signed remark about a record. A note **never changes**: there is no
+  # update and no delete, for anyone. One shape everywhere a note appears — fetched alone,
+  # listed, or embedded on its subject (+contact_message.notes+).
+  class Note < ApiObject
+    attribute :uuid
+    attribute :body
+    attribute :user, wrap: User # the author, nested-actor form
+    attribute :notable, wrap: Notable
+    attribute :created_at
+    attribute :updated_at
+  end
+
+  # A contact-page submission's request headers, exactly as the visitor's browser sent
+  # them — read through RequestHeaders' rules: case-insensitive lookup, and a render of
+  # names and never values, because a visitor's request can carry its own credentials.
+  class ContactMessageHeaders < RequestHeaders; end
+
+  # What someone sent through the public contact page, stored with everything the request
+  # told the platform and, after the fact, what the risk-assessment vendors said about it.
+  # A top-level record, so flat (no +type+ / +content+): +contact_message.uuid+ is its
+  # identity, and it embeds its notes in full.
+  #
+  # Nothing is ever rejected on a score — the record is the data, and an admin decides,
+  # with +update_status+ and +add_note+.
+  class ContactMessage < ApiObject
+    attribute :uuid
+    attribute :name
+    attribute :email_address
+    attribute :body
+    # "received" (the default) | "closed" | "spam" — the triage verdict, set with
+    # +update_status+. Treat an unrecognized value as forward-compatible, never an error.
+    attribute :status
+    # The signed-in user who submitted it (nested-actor form), or +nil+ for a visitor
+    # without an account.
+    attribute :user, wrap: User
+    attribute :ip_address
+    attribute :user_agent
+    attribute :headers, wrap: ContactMessageHeaders
+    attribute :honeypot_filled
+    attribute :fill_seconds # how long the form took to fill, or nil
+    # One self-describing slot per vendor (+vendor+, +api+, +docs+, +fetched_at+,
+    # +attempts+, then exactly one of +answer+ / +skipped+ / +error+). A plain Hash, read
+    # as the platform sent it — the vendors are the platform's to add and change, so the
+    # SDK models none of them. Note the scores do not all run the same way: see
+    # https://basecradle.com/docs/api.md#contact-messages.
+    attribute :data
+    attribute :notes, wrap: Note
+    attribute :created_at
+    attribute :updated_at
+
+    # Set the triage verdict: +"received"+, +"closed"+ or +"spam"+. It moves in any
+    # direction — reopening a closed message is +update_status("received")+.
+    #
+    # Live object: the API returns the whole contact message, and this object reads it from
+    # here on (+status+ and +updated_at+ included), then returns +self+. Raises
+    # +ValidationError+ (422) for a status outside the three.
+    def update_status(status)
+      response = require_client.request("PATCH", "/contact_messages/#{uuid}/status",
+                                        json: { "contact_message" => { "status" => status } })
+      @data = response.fetch("contact_message")
+      self
+    end
+
+    # Write a note about this contact message, and return it as a +Note+ (you are its
+    # author). Raises +ValidationError+ (422) for a blank body.
+    #
+    # This object's own +notes+ is not touched: it is the record as fetched, and the API
+    # answers with the note alone. Fetch the contact message again
+    # (+bc.contact_messages.get(uuid)+) to read it with the new note embedded.
+    #
+    # Never auto-retried — the notes endpoint takes no +Idempotency-Key+, so a resend after
+    # a lost response could write the note twice.
+    def add_note(body:)
+      response = require_client.request("POST", "/contact_messages/#{uuid}/notes",
+                                        json: { "note" => { "body" => body } })
+      Note.new(response.fetch("note"), client: @client)
+    end
+  end
+
+  # --- collections ----------------------------------------------------------------------
+
+  # Every contact message, newest first, auto-paginating — narrow with +.filter(status:)+,
+  # or fetch one by uuid. Admin-only.
+  #
+  #   bc.contact_messages.filter(status: "received").each do |message|
+  #     message.update_status("spam") if message.honeypot_filled
+  #   end
+  class ContactMessagesResource
+    include Enumerable
+    include NotSerializableCollection
+
+    def initialize(client, filters: {})
+      @client = client
+      @filters = filters
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      Paginator.new(@client, "/contact_messages", envelope_key: "contact_messages",
+                                                  model: ContactMessage, params: @filters).each(&block)
+    end
+
+    # A new lazy resource narrowed by status: +"received"+, +"closed"+ or +"spam"+. Any
+    # other value is the API's to refuse (+InvalidFilterError+, 400).
+    def filter(status: nil)
+      filters = @filters.dup
+      filters["status"] = status unless status.nil?
+      self.class.new(@client, filters: filters)
+    end
+
+    # Fetch one contact message by its uuid.
+    def get(uuid)
+      ContactMessage.new(@client.request("GET", "/contact_messages/#{uuid}").fetch("contact_message"),
+                         client: @client)
+    end
+  end
+
+  # Every note, across every subject, newest first, auto-paginating — or fetch one by uuid.
+  # Admin-only. Notes are written from their subject (+contact_message.add_note+), never
+  # from here.
+  class NotesResource
+    include Enumerable
+    include NotSerializableCollection
+
+    def initialize(client)
+      @client = client
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      Paginator.new(@client, "/notes", envelope_key: "notes", model: Note).each(&block)
+    end
+
+    # Fetch one note by its uuid.
+    def get(uuid)
+      Note.new(@client.request("GET", "/notes/#{uuid}").fetch("note"), client: @client)
+    end
+  end
+end

data/lib/basecradle/dashboard.rb

@@ -34,6 +34,13 @@ module BaseCradle
     attribute :change_password_url
   end
 
+  # The operator's surfaces — present on the Dashboard only for an admin.
+  class DashboardAdmin < ApiObject
+    attribute :contact_messages_url
+    attribute :notes_url
+    attribute :guide_url
+  end
+
   # One official SDK: where its code lives and where to install it from.
   class DashboardSdk < ApiObject
     attribute :repository
@@ -58,12 +65,17 @@ module BaseCradle
   end
 
   # Who am I, what is this place, where is everything — the answer every freshly-woken
-  # peer asks first. Identity · environment · interaction · account · documentation.
+  # peer asks first. Identity · environment · interaction · account · documentation, and
+  # for an admin a sixth section, admin.
   class Dashboard < ApiObject
     attribute :identity, wrap: User
     attribute :environment, wrap: DashboardEnvironment
     attribute :interaction, wrap: DashboardInteraction
     attribute :account, wrap: DashboardAccount
+    # Present only for an admin — so the Dashboard's shape is how a peer learns its own
+    # role. Reading it as anyone else raises MissingFieldError rather than guessing;
+    # branch on +me.identity.admin?+ instead.
+    attribute :admin, wrap: DashboardAdmin
     attribute :documentation, wrap: DashboardDocumentation
   end
 end

data/lib/basecradle/errors.rb

@@ -30,10 +30,15 @@ module BaseCradle
   # this response form). The SDK raises rather than return an ambiguous nil.
   class MissingFieldError < Error; end
 
-  # A Client or a collection resource was serialized (+to_json+ / +as_json+). Neither is
-  # a record: a Client holds your bearer token, and a collection is a lazy query whose
-  # serialization would page the whole API from inside your renderer. The SDK refuses
-  # loudly rather than emit a credential or a heap address — see BaseCradle::NotSerializable.
+  # A Client or a collection resource was serialized — +to_json+ / +as_json+,
+  # +Marshal.dump+, or +to_yaml+ / +YAML.dump+. Neither is a record: a Client holds your
+  # bearer token, and a collection is a lazy query that holds the client and would page
+  # the whole API from inside your renderer. The SDK refuses loudly rather than emit a
+  # credential or a heap address — see BaseCradle::NotSerializable.
+  #
+  # It is also how a caller who serialized *neither* gets here: +Marshal+ and Psych
+  # recurse, so dumping a model reaches the client it holds and raises this, naming
+  # BaseCradle::Client. Dump the record's own data, +model.to_h+, which holds no client.
   class NotSerializableError < Error; end
 
   # The request never got an API response (DNS failure, refused connection, timeout).
@@ -75,6 +80,9 @@ module BaseCradle
   # author (an admin may act on any task).
   class NotTaskAuthorError < ForbiddenError; end
 
+  # +not_an_admin+ — the surface is admin-only (contact messages and notes).
+  class NotAnAdminError < ForbiddenError; end
+
   # --- 404 --------------------------------------------------------------------------------
 
   # +not_found+ — no record exists for the given UUID (or it is hidden from you).
@@ -140,6 +148,9 @@ module BaseCradle
   # +payload_too_large+ — webhook ingest: the request body exceeds the maximum size.
   class PayloadTooLargeError < Error; end
 
+  # +binary_payload+ — webhook ingest: the request body is not UTF-8 text (HTTP 415).
+  class BinaryPayloadError < Error; end
+
   # --- the code => class registry ----------------------------------------------------------
 
   # Every API error is an RFC 9457 application/problem+json document with a stable,
@@ -153,6 +164,7 @@ module BaseCradle
     "not_timeline_owner" => NotTimelineOwnerError,
     "timeline_locked" => TimelineLockedError,
     "not_task_author" => NotTaskAuthorError,
+    "not_an_admin" => NotAnAdminError,
     "not_found" => NotFoundError,
     "task_not_pending" => TaskNotPendingError,
     "validation_failed" => ValidationError,
@@ -162,7 +174,8 @@ module BaseCradle
     "invalid_cursor" => InvalidCursorError,
     "invalid_filter" => InvalidFilterError,
     "endpoint_disabled" => EndpointDisabledError,
-    "payload_too_large" => PayloadTooLargeError
+    "payload_too_large" => PayloadTooLargeError,
+    "binary_payload" => BinaryPayloadError
   }.freeze
 
   class Error

data/lib/basecradle/headers.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "rendering"
+
+module BaseCradle
+  # A recorded HTTP request's headers: the wire's own spelling, looked up
+  # case-insensitively. The platform records two kinds of inbound request verbatim — a
+  # webhook delivery (+WebhookEventHeaders+) and a contact-page submission
+  # (+ContactMessageHeaders+) — and both read through this one class's rules.
+  #
+  # A +Hash+ of exactly what the wire carried — one pair per header, +Content-Type+ and
+  # +Content-Length+ included — so iterating, +keys+, +to_h+, +to_json+ and +==+ all read
+  # the platform's own spelling and nothing is renamed. Only *lookup* folds case, because
+  # header names are case-insensitive by RFC and the platform does not preserve the
+  # sender's casing: it stores names canonicalized to Title-Case per segment
+  # (+X-Github-Delivery+, not +X-GitHub-Delivery+). So a vendor's published spelling finds
+  # the header it names, and so does any other casing of it:
+  #
+  #   event.content.headers["X-GitHub-Delivery"] # GitHub's own published spelling
+  #   event.content.headers["x-github-delivery"] # the lowercase form
+  #   event.content.headers["X-Github-Delivery"] # what the wire actually carried
+  #
+  # Every read that takes a header name folds: +fetch+, +dig+, +values_at+, +fetch_values+,
+  # +to_proc+ and +key?+ (with +has_key?+, +include?+ and +member?+). A header that was
+  # genuinely not sent is *absent*, never +nil+ — +[]+ and a fallback-less +fetch+ or
+  # +fetch_values+ raise +KeyError+ naming the headers that did arrive, while +fetch+ with
+  # a fallback, +dig+ and +values_at+ answer for it the way +Hash+ does.
+  #
+  # The methods that *reshape* the hash rather than read one name — +slice+, +except+,
+  # +select+, +transform_values+ — and the mutators are left exactly as +Hash+ defines
+  # them: case-sensitive, on the platform's own spelling. This is a read of one request
+  # that already happened. Converting away from this type gives up the folding too
+  # (+to_h+, <tt>{**headers}</tt>, and anything else that hands back a plain +Hash+);
+  # +merge+ and +dup+ keep it.
+  #
+  # What it does *not* print is the values: +inspect+, +to_s+ and +pp+ render the header
+  # names alone, because these are the sender's headers and one of them may be the
+  # sender's credential. Every read is unaffected — and so is +to_json+, which still
+  # emits the request verbatim. Converting away from this type gives the redaction up
+  # exactly as it gives up the folding, and for the same reason: +slice+, +except+,
+  # +select+, +transform_values+ and +to_h+ hand back a plain +Hash+, whose +inspect+
+  # prints pairs.
+  class RequestHeaders < Hash
+    # Hash brings its own render, and a header value is another party's credential. The
+    # module puts this class back under the SDK-wide rule; it sits between this class and
+    # Hash in the ancestor chain, so all three doors resolve to it.
+    include RendersNamesOnly
+
+    # Hash's own exact-match membership, kept under a private name before the case-folding
+    # +key?+ below takes the name: a caller who wrote the wire's own spelling is answered
+    # without a scan, and it is the tiebreak if a derived copy holds two casings of one
+    # name.
+    alias_method :exact_key?, :key?
+    private :exact_key?
+
+    NO_FALLBACK = Object.new.freeze
+    private_constant :NO_FALLBACK
+
+    # +client:+ is unused — headers carry no verbs — but every wrapped model is built with
+    # it (see ApiObject.attribute's +wrap:+), so it is accepted.
+    def initialize(data, client: nil)
+      super()
+      update(data)
+    end
+
+    # The header's value, matched case-insensitively. Raises +KeyError+ when no casing of
+    # the name was delivered.
+    def [](name)
+      wire = wire_name(name)
+      wire.nil? ? raise_missing(name) : super(wire)
+    end
+
+    # Hash-like: the value, or the fallback — a default argument, or a block, which is
+    # handed the name as written — when the header was not delivered. With no fallback it
+    # behaves like +[]+.
+    def fetch(name, fallback = NO_FALLBACK, &block)
+      wire = wire_name(name)
+      return super(wire) if wire
+      return yield(name) if block
+      return fallback unless fallback.equal?(NO_FALLBACK)
+
+      raise_missing(name)
+    end
+
+    # Did this request carry the header, under any casing?
+    def key?(name)
+      !wire_name(name).nil?
+    end
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    # Ruby's nil-returning read, case folded: the value, or +nil+ for a header that was
+    # not delivered.
+    def dig(name, *rest)
+      wire = wire_name(name)
+      wire.nil? ? nil : super(wire, *rest)
+    end
+
+    # Several headers at once, folded the same way — +nil+ for one that was not delivered,
+    # as +Hash+ answers for a key it has no value for.
+    def values_at(*names)
+      names.map { |name| dig(name) }
+    end
+
+    # As +values_at+, but a header that was not delivered raises, exactly as +fetch+ does.
+    def fetch_values(*names, &block)
+      names.map { |name| block ? fetch(name, &block) : fetch(name) }
+    end
+
+    # +&headers+ — a header name to its value, folded, +nil+ for one not delivered.
+    def to_proc
+      ->(name) { dig(name) }
+    end
+
+    private
+
+    # The header *names* this request carried, and none of their values.
+    #
+    # +Hash+'s own +inspect+ prints every pair, and these headers are the *sender's*,
+    # stored verbatim by the platform: a sender that authenticates its POST to an ingest
+    # URL puts its credential in one of them, and a contact-page visitor's browser may
+    # carry its own cookies or tokens. So +logger.debug(event.content.headers)+ or
+    # +logger.debug(message.headers)+ would write another party's secret into our logs.
+    #
+    # Only the human-facing render changes. Every *read* is untouched and still
+    # wire-exact: lookups, +fetch+, +each+, +keys+, +to_h+, +to_json+, +==+.
+    #
+    # Names are sorted by their string form — a derived copy can hold a key that never
+    # came off the wire, and a mixed-type +keys+ has no natural order otherwise.
+    #
+    # +nil+ for a request the platform recorded with no headers at all, so it renders as
+    # the bare class. That is asked of the hash, not of the joined string: a request
+    # carrying a single header whose *name* is the empty string joins to "" and must stay
+    # distinguishable from one carrying nothing.
+    def render_body
+      return nil if empty?
+
+      keys.sort_by(&:to_s).join(", ")
+    end
+
+    # The wire's own spelling of +name+, or nil if no casing of it was delivered. Anything
+    # but a String is not a header name, so it is never matched rather than being coerced
+    # into one: +headers[:host]+ finds nothing, and so misses like any other absent name.
+    # Keys are type-checked too — +merge+ hands back one of these, so a caller's derived
+    # copy can hold a key that never came off the wire.
+    def wire_name(name)
+      return nil unless name.is_a?(String)
+      return name if exact_key?(name)
+
+      each_key { |wire| return wire if wire.is_a?(String) && wire.casecmp?(name) }
+      nil
+    end
+
+    def raise_missing(name)
+      raise KeyError.new(
+        "No #{name.inspect} header on this request. Header names are matched " \
+        "case-insensitively, so no casing of it was sent either. " \
+        "Headers present: #{keys.sort_by(&:to_s).inspect}",
+        receiver: self, key: name
+      )
+    end
+  end
+end

data/lib/basecradle/rendering.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BaseCradle
+  # Print what an object *is*, never what it holds.
+  #
+  # Every renderable object in this SDK follows one rule — a render shows field names and
+  # never field values — and the rule is what keeps secrets out of logs, REPL transcripts,
+  # exception messages and +p+ calls. It is load-bearing in three separate places:
+  # +Client+ holds a live +bc_uat_+ token; a +WebhookEventHeaders+ holds whatever an
+  # inbound sender put in its headers, which is another party's credential; and an
+  # +ApiObject+ holds a record's values, including an endpoint's +ingest_url+.
+  #
+  # The rule used to exist as three hand-rolled copies of the same three methods, with no
+  # fourth class ever being asked the question. That is exactly how the leak in 0.10.2
+  # arrived: +WebhookEventHeaders+ was added as a +Hash+ descendant, +Hash+ brought its
+  # own render, and every value printed with the suite green. Here it is one module, so a
+  # class added later either includes it or fails the reflective guard in
+  # +test/basecradle/rendering_test.rb+.
+  #
+  # Three doors, because a render arrives through three:
+  #
+  # - +inspect+ — +p+, a REPL echo, an exception's backtrace context, a nested +inspect+.
+  # - +to_s+ — string interpolation and +puts+, which is the door people reach for without
+  #   thinking about it. +Hash+ aliases +to_s+ to its *own* +inspect+ as one shared method
+  #   entry, so overriding +inspect+ alone leaves <tt>"#{headers}"</tt> printing values.
+  # - +pretty_print+ — +pp+. +pp+ uses an object's own +inspect+ when it defines one, which
+  #   is why an +ApiObject+ was already safe here and only a +Hash+ descendant was not;
+  #   delegating makes that a property of the module rather than a coincidence of which
+  #   superclass a class happens to have.
+  #
+  # +to_s+ is late-bound to +inspect+ rather than written <tt>alias to_s inspect</tt>: an
+  # alias copies the method body at alias time, so a subclass that redacts more in
+  # +inspect+ would be bypassed by interpolation.
+  module RendersNamesOnly
+    def inspect
+      body = render_body
+      body.nil? ? "#<#{self.class}>" : "#<#{self.class} #{body}>"
+    end
+
+    def to_s
+      inspect
+    end
+
+    def pretty_print(printer)
+      printer.text(inspect)
+    end
+
+    private
+
+    # What goes inside the angle brackets after the class name — names, never values.
+    # Includers supply it.
+    #
+    # +nil+ means "there is nothing to show" and renders the bare <tt>#<Class></tt>;
+    # anything else is rendered after a space, the empty string included. That
+    # distinction is not pedantry: a webhook delivery carrying one header whose *name* is
+    # the empty string is not the same delivery as one carrying no headers, and folding
+    # the two would report a header that arrived as a header that did not. So emptiness
+    # is the includer's question about its own contents, never this module's question
+    # about the string it was handed.
+    #
+    # The default raises rather than returning something bland, because a silent fallback
+    # would render an object as its class name alone and look deliberate; this SDK would
+    # rather fail in the test that includes the module.
+    def render_body
+      raise NotImplementedError,
+            "#{self.class} includes BaseCradle::RendersNamesOnly but defines no " \
+            "#render_body, so there is nothing for #inspect to print. Supply one " \
+            "returning field names — never field values."
+    end
+  end
+end

data/lib/basecradle/serialization.rb

@@ -18,6 +18,17 @@ module BaseCradle
   # Without ActiveSupport the same calls were merely useless: +"#<BaseCradle::Client:0x…>"+,
   # a heap address that differs every run.
   #
+  # +Marshal+ and Psych are that same act through two doors ActiveSupport never touched.
+  # Both walk instance variables directly and neither consults +as_json+, so closing the
+  # JSON door left them open, needing no ActiveSupport to be reachable. They are also the
+  # worse pair, because they are what puts a credential *at rest*: ActiveSupport's cache
+  # stores marshal what you write, so <tt>Rails.cache.write("bc", bc)</tt> landed the
+  # token in Redis, memcached or a file; a Marshal-backed session landed it in the
+  # session; Delayed::Job YAMLs its handler into the database. And nothing shadows the
+  # ivar walk the way +Enumerable#as_json+ shadows +Object#as_json+ — so
+  # <tt>Marshal.dump(bc.messages)</tt> reached the token where <tt>bc.messages.to_json</tt>
+  # never did. Both doors now raise, on the same mixin, so every includer is covered.
+  #
   # Includers supply +serialization_refusal+; the default below is the honest fallback
   # for one that does not, so the failure is still a rescuable BaseCradle::Error rather
   # than a NoMethodError out of a renderer.
@@ -34,6 +45,24 @@ module BaseCradle
       raise NotSerializableError, serialization_refusal
     end
 
+    # +Marshal.dump+, and so every store built on it: ActiveSupport's cache backends, a
+    # Marshal-backed session, and the <tt>Marshal.load(Marshal.dump(x))</tt> deep-copy
+    # idiom. Marshal reaches for this hook before it walks ivars, so defining it is what
+    # stops the walk.
+    #
+    # Deliberately unpaired with a +marshal_load+: the pair only matters to something
+    # being loaded, and nothing can be loaded because nothing is ever dumped.
+    def marshal_dump
+      raise NotSerializableError, serialization_refusal
+    end
+
+    # Psych's hook — +to_yaml+, +YAML.dump+, and anything either one nests. Psych prefers
+    # +encode_with+ over its own ivar walk for any object that defines it. The coder is
+    # unused: it is the thing we decline to fill.
+    def encode_with(_coder)
+      raise NotSerializableError, serialization_refusal
+    end
+
     private
 
     def serialization_refusal
@@ -59,16 +88,31 @@ module BaseCradle
 
     private
 
-    # Deliberately does *not* claim a token leak. Measured on this tree: ActiveSupport's
+    # One message, four doors — and it names both harms because which one you get depends
+    # on the door, measured on this tree. Through JSON, ActiveSupport's
     # +Enumerable#as_json+ shadows +Object#as_json+, so a collection serialized as its
-    # fetched records, never as its ivars — the client it holds was never walked. The
-    # harm is the unbounded fetch and the records that came out with it.
+    # fetched records and the client in its ivars was never walked: the harm is the
+    # unbounded fetch. +Marshal+ and Psych have no such shadow and walked the ivars
+    # instead, reaching the token and writing it wherever the dump went.
+    #
+    # Naming only the fetch would have told a +Rails.cache.write+ caller their credential
+    # was slow to write rather than at rest in Redis — a wrong diagnosis being worse than
+    # a missing one. Naming both keeps one refusal per resource, which is what stops the
+    # doors drifting apart.
+    #
+    # The remedy is two-part for the same reason. <tt>.to_a</tt> alone is enough for JSON,
+    # where a model serializes as its record — but the array it hands back is full of
+    # models that each hold the client, so <tt>Marshal.dump(bc.messages.to_a)</tt> lands
+    # straight back here. Measured, not assumed.
     def serialization_refusal
-      "#{self.class} is a lazy, auto-paginating query, not a record, so there is no one " \
-      "record to serialize. Serializing it runs a page-by-page GET loop over the whole " \
-      "resource from inside your renderer, and emits every record it fetched. Call " \
-      ".to_a (or .first(n), or .filter(...).to_a) and serialize that — then how much you " \
-      "fetch is a visible act in your own code."
+      "#{self.class} is a lazy, auto-paginating query holding your connection, not a " \
+      "record, so there is no one record to serialize. Serializing it either runs a " \
+      "page-by-page GET loop over the whole resource from inside your renderer and " \
+      "emits every record it fetched, or writes out the connection it holds — your " \
+      "bc_uat_ token with it. Call .to_a (or .first(n), or .filter(...).to_a) and " \
+      "serialize that — then how much you fetch is a visible act in your own code. " \
+      "Marshal and YAML reach the client through the records too, so dump the wire " \
+      "records rather than the models: .to_a.map(&:to_h)."
     end
   end
 end

data/lib/basecradle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BaseCradle
-  VERSION = "0.10.2"
+  VERSION = "0.11.0"
 end