ecoportal-api-graphql 2.2.1 → 3.0.0

data/lib/ecoportal/api/graphql/input/page/update.rb

@@ -1,3 +1,5 @@
+require 'securerandom'
+
 module Ecoportal
   module API
     class GraphQL
@@ -15,7 +17,19 @@ module Ecoportal
               # patchVer is always included when present (required for concurrency control).
               #
               # Options:
-              #   stage_id:           ID      — target a specific stage (required for stage submit/close-out)
+              #   stage_id:           ID      — target a specific stage. Optional even for a
+              #                                 PHASED page: when omitted, it is DERIVED from
+              #                                 the owning stage of the data fields being
+              #                                 updated in this same call (see #derive_stage_id)
+              #                                 — a PHASED `updatePage` has been observed to 500
+              #                                 without a `stageId` on an Image Gallery / File
+              #                                 field write (live-diagnosed, page
+              #                                 a customer's phased page), and sending it
+              #                                 whenever derivable is always safe even where it
+              #                                 turns out not to be strictly required. Pass this
+              #                                 explicitly to override the derivation, or to
+              #                                 target a stage submit/close-out when no field on
+              #                                 that stage is dirty yet.
               #   submit:             Boolean — submit the stage (triggers task transitions server-side)
               #   publish:            Boolean — publish a draft page
               #   show_hidden_data:   Boolean — include hidden data in the mutation response
@@ -37,17 +51,31 @@ module Ecoportal
               #   location_ids:       [ID]    — set page locations (PageInput.locations); the
               #                                 model's locations embed is read_only, so this is
               #                                 the way to write them
-              #   client_mutation_id: String
+              #   client_mutation_id: String  — correlation id for tracing this call in logs /
+              #                                 the server's own activity trail. Defaults to a
+              #                                 fresh `SecureRandom.uuid` PER CALL — every
+              #                                 mutation this input builds is now traceable by
+              #                                 default, not just the ones a caller remembered
+              #                                 to tag. Pass an explicit id to correlate several
+              #                                 calls under one value, or `''`/`nil` to omit the
+              #                                 key entirely. NOTE: this is for CORRELATION only
+              #                                 — the server does NOT dedupe mutations on it, so
+              #                                 it buys no idempotency; a retried call with the
+              #                                 same clientMutationId still re-applies the write.
+              #                                 Any idempotency has to be client-side (e.g. this
+              #                                 gem's own dirty-tracking not re-sending a field
+              #                                 that already round-tripped).
               def from_model(model, stage_id: nil, submit: nil, publish: nil, show_hidden_data: nil,
                              task: nil, complete_page_task: false, sign_off: nil, review_notes: nil,
-                             location_ids: nil, client_mutation_id: '', **_kargs)
+                             location_ids: nil, client_mutation_id: SecureRandom.uuid, **_kargs)
                 task = resolve_task(task, complete_page_task, sign_off, review_notes)
-                require_stage!(stage_id, submit, task)
                 page_input = (model.as_update || {}).slice(*PAGE_FIELD_KEYS)
                 # Page locations are read_only on the model (excluded from the as_update diff),
                 # so set them explicitly here → PageInput.locations = [LocationInput{ id }].
                 page_input = page_input.merge(locations: Array(location_ids).map { |lid| { id: lid } }) unless location_ids.nil?
                 data_fields = build_data_fields(model)
+                stage_id  ||= derive_stage_id(model, data_fields)
+                require_stage!(stage_id, submit, task)
 
                 no_changes = page_input.empty? && data_fields.empty?
                 no_op      = publish.nil? && submit.nil? && stage_id.nil? && task.nil?
@@ -66,13 +94,88 @@ module Ecoportal
 
               private
 
+              # Derives the default `stageId` for a PHASED page update from the STAGE(S) that
+              # own the data fields being changed in THIS call (updates/additions/deletions).
+              #
+              # Platform fact, live-diagnosed against a customer's phased page (the
+              # org's own service account): `updatePage` on a PHASED page 500s when `stageId`
+              # is missing on an Image Gallery / File field write. The live-verified
+              # a customer collection's integration guide (§5) documents a related but
+              # narrower nuance — omitting `stageId` is judged against the ROOT page's
+              # `PagePolicy#update?` rather than being an unconditional failure, so it is
+              # "optional but preferable" for an account whose edit right arrives through
+              # page-level administration rather than a stage. Sending it whenever it CAN be
+              # derived is correct either way: never wrong for an account that did not need
+              # it, and fixes the account/field combination that does. A `BasicPage` has no
+              # `#stages` at all — returns `nil` (stageId OMITTED from the input entirely,
+              # never sent as an explicit `null`; `build_input`'s nil-guard already drops a
+              # nil operation key).
+              #
+              # Multi-stage calls: if the fields being updated in this ONE call span MORE
+              # THAN ONE stage, this raises rather than guessing which stage's id to send (a
+              # single `updatePage` input can only carry one `stageId`). The caller must split
+              # such a change into one `from_model`/mutation call PER STAGE, in stage order,
+              # threading the model's (fresh, server-returned) `patchVer` from each response
+              # into the next call — the same pattern the org-side reference implementation
+              # (a downstream script repo's `-file-attach` case, `persist_file_updates`/
+              # `persist_gallery`) already uses at the call-site level, re-fetching the page
+              # between groups. Pass `stage_id:` explicitly to bypass this derivation for any
+              # other need (e.g. targeting a stage submit with no dirty field on it yet).
+              def derive_stage_id(model, data_fields)
+                return nil unless model.respond_to?(:stages)
+
+                field_ids = changed_field_ids(data_fields)
+                return nil if field_ids.empty?
+
+                owning_stage_ids = Array(model.stages).filter_map do |stage|
+                  stage.id if Array(stage.stage_field_ids).intersect?(field_ids)
+                end.uniq
+
+                case owning_stage_ids.size
+                when 0 then nil
+                when 1 then owning_stage_ids.first
+                else
+                  raise ArgumentError,
+                        "This update's data fields span #{owning_stage_ids.size} different " \
+                        "stages (#{owning_stage_ids.join(', ')}) — a single updatePage call " \
+                        'can only target one stageId. Split into one from_model/mutation call ' \
+                        "per stage, in stage order, re-fetching the page (fresh patchVer) " \
+                        'between calls, or pass stage_id: explicitly to target just one.'
+                end
+              end
+
+              # Every field id touched by this call's dataFields command (updates, additions,
+              # deletions) — the raw DataFieldInput hashes are `{ typeKey: { id:, ... } }`, so
+              # `id` is read generically off the first (only) value, regardless of field type.
+              def changed_field_ids(data_fields)
+                ids = Array(data_fields[:updates]).filter_map { |cmd| field_id_from_command(cmd) }
+                ids.concat(Array(data_fields[:additions]).filter_map { |cmd| field_id_from_command(cmd) })
+                ids.concat(Array(data_fields[:deletions]))
+                ids.compact.uniq
+              end
+
+              def field_id_from_command(command)
+                return nil unless command.is_a?(Hash)
+
+                inner = command.values.first
+                inner.is_a?(Hash) ? inner[:id] : nil
+              end
+
               # Platform invariant: a stage submit / sign-off MUST target a specific stage.
               # Page tasks (and the people-field permissions scoped to them) apply to ONE
               # stage; without a stageId the server cannot route the submit to the stage the
               # work was done on. Fail loudly here rather than silently omit stageId (the
-              # nil-guard in build_input would otherwise drop it — the exact bug that let a
-              # customer submission go out stage-less). A plain field update or publish
-              # needs no stage and is unaffected.
+              # nil-guard in build_input would otherwise drop it — the exact bug that let an
+              # some customer submissions go out stage-less).
+              #
+              # CORRECTED comment (this used to say "a plain field update ... needs no stage
+              # and is unaffected" — wrong for a PHASED page: `updatePage` 500s there without
+              # a `stageId` on ANY write, plain field update included; see `#derive_stage_id`,
+              # which is called BEFORE this guard and already fills it in from the fields
+              # being changed whenever it can). This guard now only fires for the case
+              # `#derive_stage_id` genuinely cannot resolve — no dirty field to derive from
+              # (a stage-submit-only call) or a `BasicPage` (no stages at all, where a submit
+              # makes no sense anyway) — same platform invariant, just reached less often now.
               def require_stage!(stage_id, submit, task)
                 return unless stage_id.nil?
                 return unless submit || task

data/lib/ecoportal/api/graphql/input/search_conf.rb

@@ -96,7 +96,7 @@ module Ecoportal
           # A register FIELD key carries a `<type>.<hash>` shape (e.g. 'date.zab1bddc3');
           # system/top-level keys (created_at, external_id, state) have no such prefix.
           # Field filters need the nested `membranes.<type>` path — see
-          # the repo's internal docs.
+          # the repo's internal docs
           # ---------------------------------------------------------------------------
           module MembranePath
             module_function

data/lib/ecoportal/api/graphql/model/temp_image.rb

@@ -0,0 +1,10 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        class TempImage < Base::TempImage
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/binding.rb

@@ -0,0 +1,60 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # A force binding — `addBinding`/`editBinding`'s `referenceId` is the field (or field
+          # placeholder) the binding points at. `reference_id=` accepts either a raw id/String
+          # OR a `Field` (or any object answering `#ref`) so a caller can write
+          # `binding.reference_id = some_field` and let the SAME just-created-or-real-id
+          # resolution `Field#ref` already does apply here automatically — no separate
+          # "resolve the field id" step for the caller to remember.
+          class Binding
+            include Node
+
+            PLACEHOLDER_PREFIX = 'bnd'.freeze
+
+            BINDING_TYPE = 'field'.freeze
+
+            attr_reader :template, :force, :type
+            attr_accessor :name
+
+            def initialize(template:, force:, id: nil, name: nil, reference_id: nil, type: BINDING_TYPE)
+              @template     = template
+              @force        = force
+              @id           = id
+              @name         = name
+              @type         = type
+              self.reference_id = reference_id
+              @snapshot = snapshot_attrs.freeze
+            end
+
+            attr_writer :reference_id
+
+            # Resolved at read time: the referenced node's own `#ref` when it is one (a `Field`
+            # or anything else in this tree), otherwise the raw value as given.
+            def reference_id
+              @reference_id.respond_to?(:ref) ? @reference_id.ref : @reference_id
+            end
+
+            def dirty?
+              !removed? && !new? && snapshot_attrs != @snapshot
+            end
+
+            def changed_attributes
+              return {} if new? || removed?
+
+              snapshot_attrs.each_with_object({}) { |(k, v), h| h[k] = v if v != @snapshot[k] }
+            end
+
+            private
+
+            def snapshot_attrs
+              { name: name, reference_id: reference_id }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/command_grouper.rb

@@ -0,0 +1,107 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # Groups an ordered command batch into chunks no larger than `chunk_size`, never
+          # splitting a placeholder-minting command away from any OTHER command in the SAME
+          # batch that references that placeholder (a `placeholderId` is only valid within the
+          # ONE `executeWorkflowCommands`/`updatePageTemplate` call that mints it —
+          # `18_template_editor_save_path.md` section B.1). Connected components (union-find
+          # over "which commands share a placeholder token") are packed into chunks in
+          # first-appearance order, so a chunk boundary only ever falls BETWEEN independent
+          # groups, never inside one.
+          module CommandGrouper
+            PLACEHOLDER_RE = /\Aph_/
+
+            class << self
+              # @param commands [Array<Hash>] built command hashes (`{ commandKey => input }`).
+              # @param chunk_size [Integer]
+              # @return [Array<Array<Hash>>] ordered chunks.
+              def chunk(commands, chunk_size)
+                slice_groups(group(commands), chunk_size)
+              end
+
+              # Every `ph_...` token referenced ANYWHERE in `commands` (minted or referenced).
+              # Public: `StagedExecutor`'s stale-placeholder guard uses this directly.
+              def tokens_in(commands)
+                commands.flat_map { |c| placeholder_tokens(c) }.uniq
+              end
+
+              private
+
+              def group(commands)
+                parent = {}
+                find = find_proc(parent)
+                token_owner = {}
+
+                commands.each_index do |i|
+                  find.call(i)
+                  placeholder_tokens(commands[i]).each do |tok|
+                    token_owner.key?(tok) ? union(parent, find, i, token_owner[tok]) : (token_owner[tok] = i)
+                  end
+                end
+
+                buckets = Hash.new { |h, k| h[k] = [] }
+                commands.each_index { |i| buckets[find.call(i)] << commands[i] }
+                buckets.values
+              end
+
+              def find_proc(parent)
+                find = nil
+                find = lambda do |x|
+                  parent[x] ||= x
+                  parent[x] = find.call(parent[x]) unless parent[x] == x
+                  parent[x]
+                end
+              end
+
+              def union(parent, find, idx_a, idx_b)
+                root_a = find.call(idx_a)
+                root_b = find.call(idx_b)
+                parent[root_a] = root_b unless root_a == root_b
+              end
+
+              def slice_groups(groups, chunk_size)
+                chunks  = []
+                current = []
+                groups.each do |members|
+                  guard_group_size!(members, chunk_size)
+                  if current.size + members.size > chunk_size
+                    chunks << current
+                    current = []
+                  end
+                  current.concat(members)
+                end
+                chunks << current unless current.empty?
+                chunks
+              end
+
+              def guard_group_size!(members, chunk_size)
+                return if members.size <= chunk_size
+
+                tally = members.map { |c| c.keys.first }.tally
+                raise "CommandGrouper: a placeholder-connected group of #{members.size} commands " \
+                      "exceeds chunk_size (#{chunk_size}) and cannot be split without breaking a " \
+                      "same-batch placeholder reference. Key tally: #{tally}"
+              end
+
+              def placeholder_tokens(command)
+                command.values.flat_map { |v| scan(v) }
+              end
+
+              def scan(value)
+                case value
+                when String then PLACEHOLDER_RE.match?(value) ? [value] : []
+                when Hash   then value.values.flat_map { |v| scan(v) }
+                when Array  then value.flat_map { |v| scan(v) }
+                else []
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/command_normalizer.rb

@@ -0,0 +1,116 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # Normalises an ordered batch of built `WorkflowCommand` hashes
+          # (`[{ commandKey => { ...input } }, ...]`) so that batches produced by DIFFERENT
+          # emitters -- each of which mints its own placeholder/id tokens (`Builder::
+          # TemplateBuilder`'s `ph_stg_1`, `Diff::CommandSynthesizer`'s `ph_stg_0`,
+          # `CommandSynthesis`'s `ph_stg_1`, a self-version replay's real server ids, the downstream
+          # writers' caller-chosen tokens) -- can be compared for STRUCTURAL equivalence.
+          #
+          # Two normalisations, both pure (no mutation of the input):
+          #
+          #   1. REFERENCE-TOKEN POSITIONING. Every value carried under a key this class
+          #      recognises as an id/placeholder REFERENCE (see `REFERENCE_KEYS`) is replaced
+          #      by a positional token `"ph_<n>"`, assigned in FIRST-APPEARANCE order across
+          #      the whole ordered batch (scanning left to right, top to bottom, depth-first
+          #      within each command's own Hash). The SAME source value always maps to the
+          #      SAME token wherever it recurs (so a mint-then-reference pair, e.g. `addStage`'s
+          #      `placeholderId` and a later `addStageSection`'s `stageId`, stays linked). Only
+          #      the KEY decides whether a String is a reference -- literal content
+          #      (`label`/`name`/`value`/`script`/`url`/...) is never touched, so a coincidental
+          #      value match with a real id never causes a false substitution.
+          #   2. KEY ORDER + correlation stripping. Each command's own input Hash (and any
+          #      nested Hash, e.g. `byType`) is recursively re-sorted by key so two batches that
+          #      differ only in the Hash literal's construction order compare equal, and any
+          #      `CORRELATION_KEYS` entry (never part of the compared shape) is dropped.
+          #
+          # Two normalised batches are STRUCTURALLY EQUIVALENT iff `Normalizer.normalize(a) ==
+          # Normalizer.normalize(b)` -- byte-identical once serialised (`to_json`), per the
+          # DSL-08 acceptance test.
+          class CommandNormalizer
+            # Keys whose String value addresses a node (mint or reference), across every
+            # `WorkflowCommand` input class this repo ships plus the downstream writers' own commands
+            # (`placeholderId`/`stageId`/`sectionId`/`dataFieldId`/`data_field_id`/`optionId`/
+            # `forceId`/`referenceId`/`anchorId`/`id`) -- verified against every `VALID_KEYS`
+            # list under `lib/ecoportal/api/graphql/input/workflow_command/`. Deliberately a
+            # CLOSED, named set (not "every String") so a literal content String (a label, a
+            # script, a URL) is never mistaken for a reference.
+            REFERENCE_KEYS = %i[
+              placeholderId stageId sectionId dataFieldId data_field_id optionId
+              forceId referenceId anchorId id
+            ].freeze
+
+            # Fields that exist only for request bookkeeping, never part of the compared shape.
+            CORRELATION_KEYS = %i[clientMutationId correlationId].freeze
+
+            # @param commands [Array<Hash>] an ordered batch, each a single-key Hash
+            #   (`{ commandKey => { ...input } }`).
+            # @return [Array<Hash>] the same batch, reference tokens repositioned, keys sorted,
+            #   correlation-only keys dropped. Deterministic and comparable with `==`.
+            def self.normalize(commands)
+              new.normalize(commands)
+            end
+
+            def normalize(commands)
+              @tokens     = {}
+              @next_index = 0
+              Array(commands).map { |command| normalize_command(command) }
+            end
+
+            private
+
+            def normalize_command(command)
+              command_key = command.keys.first
+              body        = command[command_key]
+              { command_key => deep_sort(normalize_hash(body)) }
+            end
+
+            def normalize_hash(hash)
+              hash.each_with_object({}) do |(key, value), out|
+                next if CORRELATION_KEYS.include?(key.to_sym)
+
+                out[key] = normalize_value(key, value)
+              end
+            end
+
+            def normalize_value(key, value)
+              case value
+              when Hash  then normalize_hash(value)
+              when Array then value.map { |element| normalize_value(key, element) }
+              when String then reference_key?(key) ? token_for(value) : value
+              else value
+              end
+            end
+
+            def reference_key?(key)
+              REFERENCE_KEYS.include?(key.to_sym)
+            end
+
+            # The SAME source value (whatever token/id format the emitter minted) always maps
+            # to the SAME positional token -- first appearance decides the number.
+            def token_for(raw_value)
+              @tokens[raw_value] ||= begin
+                @next_index += 1
+                "ph_#{@next_index}"
+              end
+            end
+
+            # Recursively re-sorts every Hash (top-level input and any nested sub-hash, e.g.
+            # `byType`) by key, so construction-order differences never cause a false mismatch.
+            # Arrays keep their own order (option/command ORDER is part of what is compared).
+            def deep_sort(value)
+              case value
+              when Hash  then value.map { |k, v| [k, deep_sort(v)] }.sort_by { |(k, _)| k.to_s }.to_h
+              when Array then value.map { |element| deep_sort(element) }
+              else value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end