basecamp-sdk 0.17.0 → 0.19.0

data/lib/basecamp/person_id_sites.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Basecamp
+  # Decodes a person's id at the response paths the reference reads it as
+  # +types.FlexibleInt64+, keyed by operation id.
+  #
+  # Go decodes every generated read through +Parse<Op>Response+, and
+  # +generated.Person.Id+ is +types.FlexibleInt64+
+  # (go/pkg/types/flexible_int64.go:27): an untagged +{"creator":{"id":"7"}}+
+  # is 7 there. Ruby returns the parsed Hash, and the normalizer converts only
+  # a person carrying +personable_type+ (plus creator/participants on the gauge
+  # and notification surfaces), so that id reached the caller as the string
+  # "7" (SPEC §10 "Person Ids Off the Wire").
+  #
+  # The fix is NOT a wider normalizer walk. The same key names hold plain int64
+  # ids in the reference (+UpcomingSchedulePerson+, +MyAssignmentAssignee+,
+  # +OutOfOfficePerson+, +TemplateLibraryConfirmationPerson+), where a string
+  # is a decode error. So the sites come from the generated table in
+  # +generated/metadata.json+ ("personIdSites"), which +generate-metadata.rb+
+  # selects on the +x-go-type+ marker of +Person.id+ and never on a key name:
+  # an operation not in the table, or a path not under it, is never touched.
+  #
+  # Runs AFTER {Http.normalize_person_ids} on the same body. Idempotent: a
+  # second pass finds only integers and leaves them.
+  module PersonIdSites
+    HINT = "A person id in this response is neither a 64-bit integer nor a string, " \
+           "or is a string out of int64 range; the response cannot be read."
+
+    # Operations whose FOLLOWED pages the reference does not decode as the
+    # generated types. Go runs page 1 through Parse<Op>Response (Person.Id is
+    # FlexibleInt64, so a null id fails), but decodes each kept item of a
+    # followed page into a hand-written type whose Person.ID is a plain int64
+    # after the positional normalizer — gauges.go:236-241 (Gauge),
+    # gauges.go:307-312 (GaugeNeedle), my_notifications.go:285-305
+    # (Notification) — and encoding/json leaves a plain int64 at zero for null.
+    # So there a null id reads rather than fails. Go-SDK behaviour, not schema,
+    # hence a hand-written list rather than a generated one.
+    NULL_ID_READS_ON_FOLLOWED_PAGES = %w[ListGauges ListGaugeNeedles GetBubbleUps].freeze
+
+    class << self
+      # Decodes the person ids at +operation+'s sites in +body+, in place.
+      #
+      # +body+ is a whole response: a single read, or the FIRST page of a
+      # paginated one (the array for a bare-array list, the wrapper object for
+      # a wrapped one), which the reference decodes whole through
+      # Parse<Op>Response before any cap applies. A followed page goes through
+      # {decode_item!} instead.
+      #
+      # @param body [Object] parsed, normalized JSON
+      # @param operation [String, nil] canonical operation id
+      # @return [Object] +body+
+      # @raise [ApiError] non-retryable, when a site's id cannot be decoded
+      def decode!(body, operation)
+        paths = operation && table[operation]
+        return body unless paths
+
+        paths.each { |path, array_site| visit(body, path, 0, array_site, operation) }
+        body
+      end
+
+      # Decodes ONE item of a FOLLOWED page, at the sites under that item only.
+      #
+      # The reference never decodes a followed page whole. A bare-array list
+      # collects the page as raw items, trims them to the cap and decodes only
+      # what it kept (client.go:604-631, followPagination), so the caller
+      # decodes each item as it is kept. A wrapped listing decodes only the
+      # items under its key — GetPersonProgress unmarshals struct{ Events }
+      # and never reads the page's person (timeline.go:444-457) — so the
+      # wrapper's other keys are not touched here either.
+      #
+      # @param item [Object] one parsed, normalized item
+      # @param operation [String, nil] canonical operation id
+      # @param key [String, nil] the wrapped listing's key; nil for a bare array
+      # @return [Object] +item+
+      # @raise [ApiError] non-retryable, when a site's id cannot be decoded
+      def decode_item!(item, operation, key: nil)
+        paths = operation && item_table(operation, key)
+        return item unless paths
+
+        null_reads = NULL_ID_READS_ON_FOLLOWED_PAGES.include?(operation)
+        paths.each { |path, array_site| visit(item, path, 0, array_site, operation, null_reads: null_reads) }
+        item
+      end
+
+      # {operationId => [[components, array_site], ...]} relative to the whole
+      # body, memoized. Benign race: concurrent first loads compute identical
+      # values.
+      def table
+        @table ||= raw_table.transform_values do |paths|
+          paths.map { |components| split_site(components) }.freeze
+        end.freeze
+      end
+
+      private
+
+      # {operationId => [components, ...]}, each the full "."-split path.
+      def raw_table
+        @raw_table ||= JSON.parse(
+          File.read(File.join(__dir__, "generated", "metadata.json"), encoding: "UTF-8")
+        ).fetch("personIdSites").transform_values do |paths|
+          paths.map { |path| (path == "$" ? [] : path.split(".")).freeze }.freeze
+        end.freeze
+      end
+
+      # The operation's sites relative to one item: those under "[]" for a
+      # bare array, or under "<key>.[]" for a wrapped listing, prefix removed.
+      # An item that is itself the person ("[]", "<key>.[]") is the empty path.
+      def item_table(operation, key)
+        (@item_tables ||= {})[[ operation, key ]] ||= begin
+          prefix = key ? [ key, "[]" ] : [ "[]" ]
+          (raw_table[operation] || []).filter_map do |components|
+            next unless components.first(prefix.length) == prefix
+
+            split_site(components.drop(prefix.length))
+          end.freeze
+        end
+      end
+
+      # A path ending in "[]" names an array of people.
+      def split_site(components)
+        array_site = components.last == "[]"
+        [ (array_site ? components[0...-1] : components).freeze, array_site ].freeze
+      end
+
+      # Follows the components; a value of another shape on the way ends the
+      # walk with nothing done. Go zero-fills or refuses those as part of its
+      # whole-body decode, which this lenient tier does for no field — that
+      # residual is not the person id's to close.
+      def visit(value, components, index, array_site, operation, null_reads: false)
+        if index == components.length
+          if array_site
+            value.each { |person| decode_person(person, components, operation, null_reads) } if value.is_a?(Array)
+          else
+            decode_person(value, components, operation, null_reads)
+          end
+          return
+        end
+
+        component = components[index]
+        if component == "[]"
+          value.each { |element| visit(element, components, index + 1, array_site, operation, null_reads: null_reads) } if value.is_a?(Array)
+        elsif value.is_a?(Hash) && value.key?(component)
+          visit(value[component], components, index + 1, array_site, operation, null_reads: null_reads)
+        end
+      end
+
+      # FlexibleInt64.UnmarshalJSON on one person's "id", present only: an
+      # absent key is the zero value with no call in Go, so it stays absent.
+      def decode_person(person, components, operation, null_reads)
+        return unless person.is_a?(Hash) && person.key?("id")
+
+        raw = person["id"]
+        # A plain int64 reads null as zero (see NULL_ID_READS_ON_FOLLOWED_PAGES);
+        # left as null, the same representation residual as an absent id.
+        return if null_reads && raw.nil?
+
+        # One rule for a person id off the wire: {Ids.person_from_wire} is the
+        # flexible decoder — an int64 passes, a string goes through ParseInt
+        # (ErrSyntax reads 0, flexible_int64.go:46; ErrRange fails,
+        # flexible_int64.go:43), and a float, null, boolean, array, object or
+        # out-of-range number fails (json.Number.Int64, flexible_int64.go:57).
+        # No system_label: the decoder writes none.
+        id = Ids.person_from_wire(raw)
+        raise refusal(raw, components, operation) if id.nil?
+
+        person["id"] = id unless raw.is_a?(Integer)
+      end
+
+      # Names the operation, the site and the value's kind — not the value,
+      # which is the response's and travels into logs from here.
+      def refusal(raw, components, operation)
+        site = components.empty? ? "the response body" : components.join(".")
+        shape = case raw
+        when String, Integer then "an out-of-range #{raw.class}"
+        when nil then "null"
+        else "a #{raw.class}"
+        end
+        ApiError.new("#{operation} returned a person id at #{site} that is #{shape}", hint: HINT, retryable: false)
+      end
+    end
+  end
+end

data/lib/basecamp/recording_routing_error.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised for a recording pointer +summarize+ cannot route, before any request
+  # is made. Two kinds:
+  #
+  # * +no_recording_type+ — an event type that names no recording type, which is
+  #   +boost.*+: the row points at the boost's target and does not carry that
+  #   target's type. A consumer resolves those from its own record of what it
+  #   posted, not through +summarize+.
+  # * +unknown_recording_type+ — neither the event type nor the recording type
+  #   names a type in the routing table. The table is a DELIBERATE set, not an
+  #   exhaustive one (see +RecordingsExtensions::RECORDING_TYPES+), so a type
+  #   outside it is this error by design, whether or not the SDK has an id-only
+  #   read for it.
+  #
+  # +code+ is +usage+: nothing was asked of the API, and the caller's own
+  # pointer is what cannot be routed.
+  class RecordingRoutingError < RecordingSummaryError
+    NO_RECORDING_TYPE = "no_recording_type"
+    UNKNOWN_RECORDING_TYPE = "unknown_recording_type"
+
+    # @return [String] the recording type or event type that could not be routed
+    attr_reader :routing_key
+
+    # @param kind [String] {NO_RECORDING_TYPE} or {UNKNOWN_RECORDING_TYPE}
+    # @param routing_key [String, nil] the type string that could not be routed
+    def initialize(kind:, routing_key:)
+      reason = kind == NO_RECORDING_TYPE ? "event type names no recording type" : "no typed read for recording type"
+      super(
+        kind: kind,
+        code: ErrorCode::USAGE,
+        message: "#{reason}: #{routing_key.to_s.inspect}"
+      )
+      @routing_key = routing_key.to_s
+    end
+
+    # @param routing_key [String, nil]
+    # @return [RecordingRoutingError]
+    def self.no_recording_type(routing_key)
+      new(kind: NO_RECORDING_TYPE, routing_key: routing_key)
+    end
+
+    # @param routing_key [String, nil]
+    # @return [RecordingRoutingError]
+    def self.unknown_recording_type(routing_key)
+      new(kind: UNKNOWN_RECORDING_TYPE, routing_key: routing_key)
+    end
+  end
+end

data/lib/basecamp/recording_summary_error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Base class for the identities +RecordingsExtensions#summarize+ raises.
+  #
+  # These are the composite's OWN outcomes, not HTTP answers: "this pointer
+  # names no recording type", "this chat line is under no Campfire you can
+  # currently see", "discovery could not be carried to a conclusion", "the read
+  # came back from another bucket". A consumer matches the CLASS — or {#kind},
+  # the same vocabulary the conformance fixture pins — rather than parsing the
+  # message or reading a status off it.
+  #
+  # +code+ stays inside SPEC section 6's closed taxonomy, which is the
+  # HTTP-status mapping and has no room for composite identities. Each subclass
+  # documents the canonical code it chose and why; the code is the coarse
+  # category a CLI exits on, the class is the identity.
+  class RecordingSummaryError < Error
+    # The composite identity, in the conformance fixture's vocabulary
+    # (+no_recording_type+, +unknown_recording_type+, +recording_unresolved+,
+    # +campfire_discovery_incomplete+, +bucket_mismatch+).
+    # @return [String]
+    attr_reader :kind
+
+    # @param kind [String] the composite identity
+    # @param message [String]
+    # @param code [String] a canonical {ErrorCode}
+    # @param hint [String, nil]
+    def initialize(kind:, message:, code:, hint: nil)
+      super(code: code, message: message, hint: hint)
+      @kind = kind
+    end
+  end
+end

data/lib/basecamp/services/comments_extensions.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Mention-expanding comment writes, prepended onto the generated
+    # {CommentsService} (see the +on_load+ hook in +basecamp.rb+).
+    #
+    # Both methods compose public generated operations — +people.get+ and
+    # +comments.create+ — so hooks observe those two wire operations under their
+    # own identities, never a synthetic composite (SPEC.md section 18 rule 3).
+    module CommentsExtensions
+      # Returns content that mentions each of the given people, for posting as a
+      # comment — or, since the markup is the same, as a rich-text Campfire line.
+      #
+      # Every requested id is read through +people.get+ for its
+      # +attachable_sgid+ — one read per distinct id, ALWAYS: an sgid already in
+      # the content is unsigned and cannot prove the person is mentioned, so it
+      # never stands in for the read — and the mentions are placed as
+      # {Basecamp::Mentions.with_mentions} places them, which adds nothing for a
+      # person whose exact +attachable_sgid+ the content already carries.
+      #
+      # A person read that fails — an id that is not a person in this account, a
+      # 403 — fails the expansion; nothing is posted on a partial mention list.
+      # That error is raised unchanged rather than wrapped: in Ruby the error's
+      # CLASS and +code+ are the identity a caller matches on, and re-raising a
+      # wrapper to carry "which person" in the message would cost both.
+      #
+      # The rendered mentions round-trip:
+      # {Basecamp::Mentions.mentioned_person_ids} on the returned content reports
+      # every id passed here, and +recordings.summarize+ reports them on the
+      # comment once posted.
+      #
+      # @param content [String] the comment's rich text
+      # @param person_ids [Array<Integer>, nil] people to mention
+      # @return [String] the content with the mentions placed
+      # @raise [Basecamp::UsageError] on a non-positive person id
+      def expand_mentions(content:, person_ids: nil)
+        content = require_content(content)
+        person_ids = Array(person_ids)
+        return content if person_ids.empty?
+
+        seen = {}
+        people = []
+        person_ids.each do |person_id|
+          id = Ids.integer(person_id, "mention person id")
+          raise UsageError.new("invalid mention person id #{person_id.inspect}") unless id.positive?
+          next if seen.key?(id)
+
+          seen[id] = true
+          # Collected with an explicit push rather than by filter_map. That
+          # dropped every FALSY return as well as the duplicates it was meant
+          # to skip, so a people read answering JSON null or false removed the
+          # mention and let the comment post without it — the exact opposite of
+          # what this method's own doc promises, and a defect a comment saying
+          # "nothing is posted on a partial mention list" made harder to see.
+          people << read_person(id, @client.people.get(person_id: id))
+        end
+
+        Mentions.with_mentions(content, people)
+      end
+
+      # Creates a comment on a recording whose content mentions the given people:
+      # {#expand_mentions}, then the generated +create+. The mention reads happen
+      # before the write, so a failed lookup posts nothing.
+      #
+      # @param recording_id [Integer] the recording to comment on
+      # @param content [String] the comment's rich text
+      # @param person_ids [Array<Integer>, nil] people to mention
+      # @return [Hash] the created comment
+      # @raise [Basecamp::UsageError] when the content is empty, or on a
+      #   non-positive person id
+      def create_with_mentions(recording_id:, content:, person_ids: nil)
+        # Checked as a STRING, not as `content.to_s.empty?`. That validated a
+        # coerced copy and then handed the ORIGINAL to create, so a Hash was
+        # posted as a JSON object when no mentions were requested and was
+        # rendered into Ruby text by with_mentions when they were — two
+        # different wire bodies for one argument, neither of them the documented
+        # String. The reference takes `content string`, so a non-string cannot
+        # reach it at all; this is the equivalent refusal in a tier that has to
+        # make it explicitly.
+        content = require_content(content)
+        raise UsageError.new("comment content is required") if content.empty?
+
+        # Typed, not bounded. Ruby has no int64 to receive this in, so a value
+        # that is not an id at all is refused here — but the reference validates
+        # the CONTENT only and sends whatever id it is given, so a zero or a
+        # negative goes to the wire and comes back a 404, as it does there.
+        recording_id = Ids.integer(recording_id, "recording id")
+
+        create(recording_id: recording_id, content: expand_mentions(content: content, person_ids: person_ids))
+      end
+
+      private
+
+      # The comment's rich text, which has to be a String before anything is
+      # measured, written or posted.
+      def require_content(content)
+        return content if content.is_a?(String)
+
+        raise UsageError.new("comment content must be a string, got #{content.class}")
+      end
+
+      # The people read's body, which has to be an object before a mention is
+      # built from it.
+      #
+      # The reference decodes into a typed Person, so a scalar, an array or a
+      # null body fails the read there and never reaches the write. Here they
+      # reached {Basecamp::Mentions.with_mentions}, which would have gone on to
+      # index them.
+      def read_person(id, person)
+        return person if person.is_a?(Hash)
+
+        raise MergeSafe.malformed(
+          "the read for person #{id} returned #{MergeSafe.describe(person)}, not a person object",
+          "Every requested mention is resolved before the comment is written, so a person that " \
+            "cannot be read fails the whole write rather than posting without that mention."
+        )
+      end
+    end
+  end
+end

data/lib/basecamp/services/merge_safe.rb

@@ -202,12 +202,25 @@ module Basecamp
       # replaces (<tt>(body[key] || []).map { |p| p["id"] }</tt>) has three ways
       # to go wrong on malformed data: a non-Array has no +map+ (or, for a Hash,
       # maps over its pairs), a non-Hash element raises TypeError on +[]+, and a
-      # non-Integer +id+ rides through verbatim into the full-replace PUT — the
+      # wrong-typed +id+ rides through verbatim into the full-replace PUT — the
       # same corruption as a wrong-typed string, one level down.
       #
-      # +true+/+false+ are refused explicitly: they are not Integers in Ruby, so
-      # +is_a?(Integer)+ already rejects them, but the message names them as ids
-      # rather than as an unexplained type error.
+      # What it must NOT do is refuse an id the reference ACCEPTS, which is the
+      # other half of the same defect and the one this guard had (#913). A
+      # person's id is the single field in the generated model the reference
+      # decodes flexibly, and +fieldsFromTodo+ appends what that produced with
+      # no filter of any kind — 0 included.
+      #
+      # It must not lean on {Basecamp::Http}'s pre-decode normalizer having
+      # reached the person first. Which people that walk finds is the walk's
+      # rule — the reference's positional pass covers +creator+ and
+      # +participants+ and nothing else — and a person it did not find arrives
+      # here exactly as BC3 sent it. How often that is a String the fixtures
+      # cannot say (none of the person objects in +spec/fixtures+ carries one);
+      # what they show is that the marker the +personable_type+ pass keys on is
+      # often missing, on 3 of 7 +assignees+ people. The rule itself lives in
+      # {Basecamp::Ids.person_from_wire}, where the read path already reads one,
+      # so the two cannot drift.
       def writable_id_list(body, key, record:, escape:)
         value = body[key]
         return [] if value.nil?
@@ -225,7 +238,23 @@ module Basecamp
       end
 
       # Validates one element of an id-list field and returns its id.
+      #
+      # Three element shapes are accepted that a strict reading would refuse,
+      # each because the reference accepts it:
+      #
+      # * a +nil+ element is 0 — a JSON null in the array decodes to the
+      #   reference's zero Person, whose id is 0 and is appended like any other;
+      # * an element with NO "id" is 0, the zero value, with no error;
+      # * an element whose "id" is a String is whatever ParseInt makes of it,
+      #   and a String that is not a number at all is the system actor 0.
+      #
+      # An explicit <tt>"id" => nil</tt> is NOT the same as an absent one and
+      # still fails the read, which is why the absent case is tested with
+      # +key?+ rather than by asking for the value: see
+      # {Basecamp::Ids.person_from_wire} for the decoder line that splits them.
       def person_id(element, index, key, record:, escape:)
+        return 0 if element.nil?
+
         unless element.is_a?(Hash)
           raise malformed(
             "#{record} field #{key.inspect}[#{index}] is not an object: #{describe(element)}",
@@ -233,17 +262,12 @@ module Basecamp
           )
         end
 
-        id = element["id"]
-        if id.nil?
-          raise malformed(
-            "#{record} field #{key.inspect}[#{index}] has no \"id\"",
-            format(RESEND_HINT, escape: escape)
-          )
-        end
+        return 0 unless element.key?("id")
 
-        unless id.is_a?(Integer)
+        id = Ids.person_from_wire(element["id"])
+        if id.nil?
           raise malformed(
-            "#{record} field #{key.inspect}[#{index}].id is not an integer: #{describe(id)}",
+            "#{record} field #{key.inspect}[#{index}].id is not a person id: #{describe(element["id"])}",
             format(RESEND_HINT, escape: escape)
           )
         end