analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/configuration/writer.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "json"
 require "securerandom"
+require "tmpdir"
 
 module AnalyticsOps
   module Configuration
@@ -12,11 +13,14 @@ module AnalyticsOps
       class Result
         attr_reader :path
 
-        def initialize(path:, created:)
-          raise ArgumentError, "created must be true or false" unless [true, false].include?(created)
+        def initialize(path:, created:, updated: false)
+          unless [true, false].include?(created) && [true, false].include?(updated) && !(created && updated)
+            raise ArgumentError, "created and updated must be distinct booleans"
+          end
 
           @path = path.to_s.dup.freeze
           @created = created
+          @updated = updated
           freeze
         end
 
@@ -24,15 +28,23 @@ module AnalyticsOps
           @created
         end
 
+        def updated?
+          @updated
+        end
+
+        def changed?
+          created? || updated?
+        end
+
         def to_h
-          { "path" => path, "created" => created? }
+          { "path" => path, "created" => created?, "updated" => updated? }
         end
       end
 
       def write_minimal(path, profile:, property_id:)
         state = validated_state(profile, property_id)
         expanded = File.expand_path(path)
-        return existing_result(expanded, state) if File.exist?(expanded)
+        return existing_result(File.realpath(expanded), state) if File.exist?(expanded)
 
         FileUtils.mkdir_p(File.dirname(expanded))
         temporary = temporary_path(expanded)
@@ -70,11 +82,12 @@ module AnalyticsOps
       end
 
       def existing_result(path, state)
+        source = read_source(path)
         configuration = Configuration.load(path)
         unless configuration.profiles.key?(state.profile)
-          raise ConfigurationError,
-                "Configuration #{Redaction.message(path)} already exists without profile " \
-                "#{state.profile.inspect}; setup will not rewrite it"
+          updated = append_profile(source, state)
+          atomic_replace(path, original: source, replacement: updated)
+          return Result.new(path:, created: false, updated: true)
         end
 
         existing = configuration.profile(state.profile)
@@ -85,6 +98,12 @@ module AnalyticsOps
         end
 
         Result.new(path:, created: false)
+      rescue EnvironmentVariableError
+        replacement = replace_generator_placeholder(source, state)
+        raise unless replacement
+
+        atomic_replace(path, original: source, replacement:)
+        Result.new(path:, created: false, updated: true)
       end
 
       def document(state)
@@ -100,6 +119,92 @@ module AnalyticsOps
       def temporary_path(path)
         File.join(File.dirname(path), ".#{File.basename(path)}.#{Process.pid}.#{SecureRandom.hex(6)}.tmp")
       end
+
+      def read_source(path)
+        source = File.binread(path, Loader::MAX_BYTES + 1)
+        if source.bytesize > Loader::MAX_BYTES
+          raise ConfigurationError, "Configuration exceeds #{Loader::MAX_BYTES} bytes"
+        end
+
+        source
+      end
+
+      def append_profile(source, state)
+        profiles = profiles_mapping(source)
+        indentation = " " * profiles.children.first.start_column
+        snippet = "#{indentation}#{state.profile}:\n" \
+                  "#{indentation}  property_id: #{JSON.generate(state.property_id)}\n"
+        lines = source.lines
+        index = profiles.end_line
+        complete_final_line(lines, index)
+        lines.insert(index, snippet)
+        lines.join
+      rescue Psych::Exception => error
+        raise ConfigurationError, "Configuration cannot be updated safely: #{Redaction.message(error.message)}"
+      end
+
+      def profiles_mapping(source)
+        root = Psych.parse(source)&.root
+        raise ConfigurationError, "Configuration root must be a mapping" unless root.is_a?(Psych::Nodes::Mapping)
+
+        profiles = root.children.each_slice(2).find do |key, _value|
+          key.is_a?(Psych::Nodes::Scalar) && key.value == "profiles"
+        end&.last
+        unless profiles.is_a?(Psych::Nodes::Mapping) && profiles.children.any?
+          raise ConfigurationError, "Configuration profiles mapping cannot be updated safely"
+        end
+
+        profiles
+      end
+
+      def complete_final_line(lines, insertion_index)
+        return unless insertion_index == lines.length && lines.last && !lines.last.end_with?("\n")
+
+        lines[-1] = "#{lines.last}\n"
+      end
+
+      def replace_generator_placeholder(source, state)
+        placeholder = '"${GA4_PROPERTY_ID}"'
+        return nil unless source.scan(placeholder).length == 1
+
+        candidate = source.sub(placeholder, JSON.generate(state.property_id))
+        temporary_document(candidate, state)
+        candidate
+      end
+
+      def atomic_replace(path, original:, replacement:)
+        temporary_document(replacement)
+        temporary = temporary_path(path)
+        mode = File.stat(path).mode & 0o777
+        File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, mode) do |file|
+          file.write(replacement)
+          file.flush
+          file.fsync
+        end
+        unless File.binread(path, Loader::MAX_BYTES + 1) == original
+          raise ConfigurationError, "Configuration #{Redaction.message(path)} changed while setup was running"
+        end
+
+        File.rename(temporary, path)
+        File.chmod(mode, path)
+      ensure
+        File.unlink(temporary) if temporary && File.exist?(temporary)
+      end
+
+      def temporary_document(source, expected_state = nil)
+        temporary = File.join(Dir.tmpdir, "analytics-ops-config-#{Process.pid}-#{SecureRandom.hex(6)}.yml")
+        File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write(source) }
+        configuration = Configuration.load(temporary)
+        if expected_state
+          actual = configuration.profile(expected_state.profile)
+          unless actual.property_id == expected_state.property_id
+            raise ConfigurationError, "Generated configuration does not match the selected property"
+          end
+        end
+        configuration
+      ensure
+        File.unlink(temporary) if temporary && File.exist?(temporary)
+      end
     end
   end
 end

data/lib/analytics_ops/desired_state.rb

@@ -7,10 +7,12 @@ module AnalyticsOps
   class DesiredState
     attr_reader :profile, :property_id, :streams, :retention, :key_events,
                 :custom_dimensions, :custom_metrics, :manual_requirements,
-                :google_signals
+                :google_signals, :labels, :reports, :health, :funnels,
+                :bigquery, :governance
 
     def initialize(profile:, property_id:, streams:, retention:, key_events:, custom_dimensions:, custom_metrics:,
-                   manual_requirements:, google_signals:)
+                   manual_requirements:, google_signals:, labels: {}, reports: {}, health: nil, funnels: {},
+                   bigquery: nil, governance: nil)
       @profile = Canonical.immutable(profile)
       @property_id = Canonical.immutable(property_id)
       @streams = Canonical.immutable(streams)
@@ -20,6 +22,12 @@ module AnalyticsOps
       @custom_metrics = Canonical.immutable(custom_metrics)
       @manual_requirements = Canonical.immutable(manual_requirements)
       @google_signals = Canonical.immutable(google_signals)
+      @labels = Canonical.immutable(labels)
+      @reports = immutable_values(reports)
+      @health = Canonical.immutable(health)
+      @funnels = immutable_values(funnels)
+      @bigquery = Canonical.immutable(bigquery)
+      @governance = Canonical.immutable(governance)
       freeze
     end
 
@@ -33,8 +41,25 @@ module AnalyticsOps
         "custom_dimensions" => custom_dimensions,
         "custom_metrics" => custom_metrics,
         "manual_requirements" => manual_requirements,
-        "google_signals" => google_signals
+        "google_signals" => google_signals,
+        "labels" => labels,
+        "reports" => reports.transform_values(&:to_h),
+        "health" => health,
+        "funnels" => funnels.transform_values { |value| value.respond_to?(:to_h) ? value.to_h : value },
+        "bigquery" => bigquery,
+        "governance" => governance
       }
     end
+
+    private
+
+    def immutable_values(value)
+      raise ArgumentError, "Expected a Hash" unless value.is_a?(Hash)
+
+      value.each_value do |child|
+        raise ArgumentError, "Expected immutable configured values" unless child.frozen?
+      end
+      value.dup.freeze
+    end
   end
 end

data/lib/analytics_ops/errors.rb

@@ -2,8 +2,40 @@
 
 # Public typed errors.
 
+require_relative "redaction"
+
 module AnalyticsOps
-  class Error < StandardError; end
+  # Base for every expected, safely reportable Analytics Ops failure.
+  class Error < StandardError
+    attr_reader :remote_reason, :remote_metadata, :remote_code
+
+    def initialize(message = nil, remote_reason: nil, remote_metadata: nil, remote_code: nil)
+      @remote_reason = safe_remote_value(remote_reason, 128)
+      @remote_metadata = safe_remote_metadata(remote_metadata)
+      @remote_code = safe_remote_value(remote_code, 64)
+      super(message)
+    end
+
+    private
+
+    def safe_remote_value(value, limit)
+      return nil if value.nil?
+
+      Redaction.message(value).slice(0, limit).freeze
+    end
+
+    def safe_remote_metadata(value)
+      return {}.freeze if value.nil?
+      return {}.freeze unless value.respond_to?(:to_h)
+
+      value.to_h.first(32).to_h do |key, child|
+        [safe_remote_value(key, 128), safe_remote_value(child, 256)]
+      end.freeze
+    rescue StandardError
+      {}.freeze
+    end
+  end
+
   class ConfigurationError < Error; end
   class EnvironmentVariableError < ConfigurationError; end
   class UnsupportedVersionError < ConfigurationError; end

data/lib/analytics_ops/funnels.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # User-defined, aggregate funnels executed through the optional BigQuery adapter.
+  module Funnels
+    # One named GA4 event in an ordered funnel.
+    class Step < Resources::Value
+      fields :name, :event_name
+    end
+
+    # Immutable definition for an aggregate, ordered BigQuery funnel.
+    class Definition
+      NAME = /\A[A-Za-z][A-Za-z0-9_]{0,63}\z/
+      EVENT_NAME = /\A[A-Za-z][A-Za-z0-9_]{0,39}\z/
+      CONTROL = /[\u0000-\u001f\u007f]/
+
+      attr_reader :name, :steps
+
+      def initialize(name:, steps:)
+        raise InvalidRequestError, "Funnel name is invalid" unless name.is_a?(String) && NAME.match?(name)
+        unless steps.is_a?(Array) && steps.length.between?(2, 10)
+          raise InvalidRequestError, "A funnel requires 2 to 10 steps"
+        end
+
+        @name = name.dup.freeze
+        @steps = steps.map.with_index { |step, index| normalize_step(step, index) }.freeze
+        unless @steps.map(&:name).uniq.length == @steps.length
+          raise InvalidRequestError, "Funnel step names must be unique"
+        end
+
+        freeze
+      end
+
+      def to_h
+        { "name" => name, "experimental" => true, "steps" => steps.map(&:to_h) }
+      end
+
+      private
+
+      def normalize_step(value, index)
+        unless value.is_a?(Hash) && value.keys.all?(String) && (value.keys - %w[name event_name]).empty?
+          raise InvalidRequestError, "Funnel step #{index + 1} is invalid"
+        end
+
+        name = value["name"]
+        event_name = value["event_name"]
+        unless name.is_a?(String) && !name.empty? && name.length <= 64 && !name.match?(CONTROL)
+          raise InvalidRequestError, "Funnel step #{index + 1} name is invalid"
+        end
+        unless event_name.is_a?(String) && EVENT_NAME.match?(event_name)
+          raise InvalidRequestError, "Funnel step #{index + 1} event_name is invalid"
+        end
+
+        Step.new(name:, event_name:)
+      end
+    end
+  end
+end

data/lib/analytics_ops/governance.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Read-only inspection of broader, mostly alpha Admin API capabilities.
+  module Governance
+    # Normalized read-only settings for one GA4 web stream.
+    class StreamSettings < Resources::Value
+      fields :stream_id, :stream_name, :enhanced_measurement, :data_redaction
+    end
+
+    # Immutable snapshot of experimental governance resources for one property.
+    class Snapshot
+      MAX_RESOURCES = 10_000
+
+      attr_reader :property_id, :stream_settings, :reporting_identity, :attribution,
+                  :channel_groups, :calculated_metrics, :event_create_rules,
+                  :event_edit_rules, :bigquery_links
+
+      def initialize(property_id:, stream_settings:, reporting_identity:, attribution:,
+                     channel_groups:, calculated_metrics:, event_create_rules:,
+                     event_edit_rules:, bigquery_links:)
+        validate_property_id!(property_id)
+        validate_streams!(property_id, stream_settings)
+        validate_resources!(
+          reporting_identity,
+          attribution,
+          channel_groups,
+          calculated_metrics,
+          event_create_rules,
+          event_edit_rules,
+          bigquery_links
+        )
+
+        @property_id = property_id.dup.freeze
+        @stream_settings = stream_settings.dup.freeze
+        @reporting_identity = Canonical.immutable(reporting_identity)
+        @attribution = Canonical.immutable(attribution)
+        @channel_groups = Canonical.immutable(channel_groups)
+        @calculated_metrics = Canonical.immutable(calculated_metrics)
+        @event_create_rules = Canonical.immutable(event_create_rules)
+        @event_edit_rules = Canonical.immutable(event_edit_rules)
+        @bigquery_links = Canonical.immutable(bigquery_links)
+        freeze
+      end
+
+      def to_h
+        {
+          "property_id" => property_id,
+          "stream_settings" => stream_settings.map(&:to_h),
+          "reporting_identity" => reporting_identity,
+          "attribution" => attribution,
+          "channel_groups" => channel_groups,
+          "calculated_metrics" => calculated_metrics,
+          "event_create_rules" => event_create_rules,
+          "event_edit_rules" => event_edit_rules,
+          "bigquery_links" => bigquery_links
+        }
+      end
+
+      private
+
+      def validate_property_id!(value)
+        return if value.is_a?(String) && value.match?(/\A\d{1,50}\z/)
+
+        raise RemoteError, "Governance property ID is invalid"
+      end
+
+      def validate_streams!(property_id, streams)
+        unless streams.is_a?(Array) && streams.all?(StreamSettings)
+          raise RemoteError, "Governance stream settings are invalid"
+        end
+
+        streams.each do |stream|
+          expected = "properties/#{property_id}/dataStreams/#{stream.stream_id}"
+          valid = stream.stream_id.is_a?(String) &&
+                  stream.stream_id.match?(/\A\d{1,50}\z/) &&
+                  stream.stream_name == expected &&
+                  stream.enhanced_measurement.is_a?(Hash) &&
+                  stream.data_redaction.is_a?(Hash)
+          raise RemoteError, "Governance stream belongs to a different property" unless valid
+        end
+      end
+
+      def validate_resources!(identity, attribution, *collections)
+        valid = identity.is_a?(Hash) &&
+                attribution.is_a?(Hash) &&
+                collections.all? do |collection|
+                  collection.is_a?(Array) &&
+                    collection.length <= MAX_RESOURCES &&
+                    collection.all?(Hash)
+                end
+        raise RemoteError, "Governance snapshot collections are invalid" unless valid
+      end
+    end
+
+    # One deterministic governance mismatch.
+    class Finding < Resources::Value
+      fields :severity, :code, :resource, :message
+    end
+
+    # Governance snapshot paired with its configured findings.
+    class Result
+      attr_reader :snapshot, :findings
+
+      def initialize(snapshot:, findings:)
+        raise ArgumentError, "snapshot must be a governance snapshot" unless snapshot.is_a?(Snapshot)
+        unless findings.is_a?(Array) && findings.all?(Finding)
+          raise ArgumentError,
+                "findings must be governance findings"
+        end
+
+        @snapshot = snapshot
+        @findings = findings.dup.freeze
+        freeze
+      end
+
+      def compliant?
+        findings.empty?
+      end
+
+      def to_h
+        {
+          "experimental" => true,
+          "compliant" => compliant?,
+          "snapshot" => snapshot.to_h,
+          "findings" => findings.map(&:to_h)
+        }
+      end
+    end
+
+    # Bounded, deidentified Admin API change-history result.
+    class ChangeHistory
+      EVENT_KEYS = %w[actor_type change_time changes changes_filtered id].freeze
+      CHANGE_KEYS = %w[action resource].freeze
+      MAX_EVENTS = 200
+      MAX_CHANGES = 1_000
+
+      attr_reader :property_id, :events
+
+      def initialize(property_id:, events:)
+        unless property_id.is_a?(String) && property_id.match?(/\A\d{1,50}\z/) &&
+               events.is_a?(Array) && events.length <= MAX_EVENTS && events.all? { |event| valid_event?(event) }
+          raise RemoteError, "Change history is invalid"
+        end
+
+        @property_id = property_id.dup.freeze
+        @events = Canonical.immutable(events)
+        freeze
+      end
+
+      def to_h
+        { "experimental" => true, "property_id" => property_id, "events" => events }
+      end
+
+      private
+
+      def valid_event?(event)
+        event.is_a?(Hash) &&
+          event.keys.all?(String) &&
+          event.keys.sort == EVENT_KEYS &&
+          printable?(event["id"], 256) &&
+          printable?(event["change_time"], 128) &&
+          printable?(event["actor_type"], 128) &&
+          [true, false].include?(event["changes_filtered"]) &&
+          valid_changes?(event["changes"])
+      end
+
+      def valid_changes?(changes)
+        changes.is_a?(Array) &&
+          changes.length <= MAX_CHANGES &&
+          changes.all? do |change|
+            change.is_a?(Hash) &&
+              change.keys.all?(String) &&
+              change.keys.sort == CHANGE_KEYS &&
+              printable?(change["resource"], 1_024) &&
+              printable?(change["action"], 128)
+          end
+      end
+
+      def printable?(value, maximum)
+        value.is_a?(String) &&
+          value.length.between?(1, maximum) &&
+          value.valid_encoding? &&
+          !value.match?(/[\u0000-\u001f\u007f]/)
+      end
+    end
+
+    # Bounded aggregate report of Data API quota usage.
+    class AccessReport
+      attr_reader :property_id, :dimension_headers, :metric_headers, :rows, :row_count, :quota
+
+      def initialize(property_id:, dimension_headers:, metric_headers:, rows:, row_count:, quota:)
+        validate_property_id!(property_id)
+        headers = validate_headers!(dimension_headers, metric_headers)
+        validate_rows!(rows, headers)
+        validate_summary!(rows, row_count, quota)
+
+        @property_id = property_id.dup.freeze
+        @dimension_headers = Canonical.immutable(dimension_headers)
+        @metric_headers = Canonical.immutable(metric_headers)
+        @rows = Canonical.immutable(rows)
+        @row_count = row_count
+        @quota = Canonical.immutable(quota)
+        freeze
+      end
+
+      def to_h
+        {
+          "experimental" => true,
+          "property_id" => property_id,
+          "dimension_headers" => dimension_headers,
+          "metric_headers" => metric_headers,
+          "rows" => rows,
+          "row_count" => row_count,
+          "quota" => quota
+        }
+      end
+
+      private
+
+      def validate_property_id!(value)
+        return if value.is_a?(String) && value.match?(/\A\d{1,50}\z/)
+
+        raise RemoteError, "Access report is invalid"
+      end
+
+      def validate_headers!(dimensions, metrics)
+        headers = Array(dimensions) + Array(metrics)
+        valid = dimensions.is_a?(Array) &&
+                metrics.is_a?(Array) &&
+                headers.length.between?(1, 64) &&
+                headers.all? { |header| valid_header?(header) } &&
+                headers.uniq.length == headers.length
+        raise RemoteError, "Access report is invalid" unless valid
+
+        headers
+      end
+
+      def validate_rows!(rows, headers)
+        valid = rows.is_a?(Array) &&
+                rows.length <= 100_000 &&
+                rows.all? { |row| valid_row?(row, headers) }
+        raise RemoteError, "Access report is invalid" unless valid
+      end
+
+      def validate_summary!(rows, row_count, quota)
+        return if row_count.is_a?(Integer) && row_count >= rows.length && quota.is_a?(Hash)
+
+        raise RemoteError, "Access report is invalid"
+      end
+
+      def valid_header?(value)
+        value.is_a?(String) && value.match?(/\A[A-Za-z][A-Za-z0-9_]{0,127}\z/)
+      end
+
+      def valid_row?(row, headers)
+        row.is_a?(Hash) &&
+          row.keys.all?(String) &&
+          row.keys.sort == headers.sort &&
+          row.values.all? do |value|
+            value.is_a?(String) && value.valid_encoding? && value.bytesize <= 1_048_576
+          end
+      end
+    end
+
+    # Compares a governance snapshot with strict local expectations.
+    class Auditor
+      EXPECTED_COLLECTIONS = {
+        "expected_channel_groups" => %w[channel_groups display_name],
+        "expected_calculated_metrics" => %w[calculated_metrics display_name],
+        "expected_event_create_rules" => %w[event_create_rules destination_event],
+        "expected_event_edit_rules" => %w[event_edit_rules display_name]
+      }.freeze
+
+      def initialize(snapshot:, settings:)
+        @snapshot = snapshot
+        @settings = settings || {}
+      end
+
+      def call
+        findings = []
+        findings.concat(stream_findings)
+        findings.concat(identity_findings)
+        findings.concat(collection_findings)
+        Result.new(snapshot: @snapshot, findings:)
+      end
+
+      private
+
+      def stream_findings
+        if @snapshot.stream_settings.empty? && stream_requirements?
+          return [
+            finding(
+              "missing_web_stream",
+              "stream_settings",
+              "A web stream is required before stream-level governance settings can be checked"
+            )
+          ]
+        end
+
+        @snapshot.stream_settings.flat_map do |stream|
+          findings = []
+          if @settings["enhanced_measurement_required"] &&
+             !stream.enhanced_measurement.fetch("stream_enabled", false)
+            findings << finding("enhanced_measurement_disabled", stream.stream_name,
+                                "Enhanced measurement is required but disabled")
+          end
+          if @settings["email_redaction_required"] &&
+             !stream.data_redaction.fetch("email_redaction_enabled", false)
+            findings << finding("email_redaction_disabled", stream.stream_name,
+                                "Email redaction is required but disabled")
+          end
+          if @settings["query_parameter_redaction_required"] &&
+             !stream.data_redaction.fetch("query_parameter_redaction_enabled", false)
+            findings << finding("query_redaction_disabled", stream.stream_name,
+                                "Query-parameter redaction is required but disabled")
+          end
+          findings
+        end
+      end
+
+      def stream_requirements?
+        %w[
+          enhanced_measurement_required email_redaction_required
+          query_parameter_redaction_required
+        ].any? { |name| @settings[name] }
+      end
+
+      def identity_findings
+        findings = []
+        expected = @settings["reporting_identity"]
+        actual = @snapshot.reporting_identity["reporting_identity"]
+        if expected && expected != actual
+          findings << finding(
+            "reporting_identity_mismatch",
+            "reporting_identity",
+            "Reporting identity is #{actual.inspect}; expected #{expected.inspect}"
+          )
+        end
+        if @settings["bigquery_link_required"] && @snapshot.bigquery_links.empty?
+          findings << finding("missing_bigquery_link", "bigquery_links", "At least one BigQuery link is required")
+        end
+        findings
+      end
+
+      def collection_findings
+        EXPECTED_COLLECTIONS.flat_map do |setting, (collection, identity)|
+          actual = @snapshot.public_send(collection).filter_map { |item| item[identity] }
+          Array(@settings[setting]).filter_map do |expected|
+            next if actual.include?(expected)
+
+            finding("missing_#{collection.delete_suffix("s")}", collection,
+                    "Expected #{collection.tr("_", " ")} entry #{expected.inspect} was not found")
+          end
+        end
+      end
+
+      def finding(code, resource, message)
+        Finding.new(severity: "warning", code:, resource:, message:)
+      end
+    end
+  end
+end