analytics_ops 0.1.0 → 0.2.0

data/lib/analytics_ops/reports/definition.rb

@@ -10,10 +10,12 @@ module AnalyticsOps
       API_NAME = /\A[a-z][a-zA-Z0-9_]*(?::[a-zA-Z][a-zA-Z0-9_]*)?\z/
       REPORT_NAME = /\A[a-z][a-z0-9_]{0,63}\z/
       RANGE_NAME = /\A[a-z][a-z0-9_]{0,39}\z/
+      ABSOLUTE_DATE = /\A\d{4}-\d{2}-\d{2}\z/
       RELATIVE_DATE = /\A(\d{1,4})daysAgo\z/
       MATCH_TYPES = %w[exact begins_with ends_with contains full_regexp partial_regexp].freeze
       NUMERIC_OPERATIONS = %w[equal less_than less_than_or_equal greater_than greater_than_or_equal].freeze
       MAX_LIMIT = 100_000
+      INT64_RANGE = (-(2**63))..((2**63) - 1)
 
       attr_reader :name, :kind, :dimensions, :metrics, :date_ranges,
                   :dimension_filter, :metric_filter, :order_bys, :offset, :limit
@@ -22,8 +24,8 @@ module AnalyticsOps
                      metric_filter: nil, order_bys: [], offset: 0, limit: 100)
         @name = validate_name(name)
         @kind = validate_kind(kind)
-        @dimensions = api_names(dimensions, "dimensions", maximum: realtime_kind?(kind) ? 4 : 9)
-        @metrics = api_names(metrics, "metrics", maximum: 10)
+        @dimensions = api_names(dimensions, "dimensions", minimum: 0, maximum: realtime_kind?(kind) ? 4 : 9)
+        @metrics = api_names(metrics, "metrics", minimum: 1, maximum: 10)
         @date_ranges = ranges(date_ranges)
         @dimension_filter = string_filter(dimension_filter)
         @metric_filter = numeric_filter(metric_filter)
@@ -71,10 +73,11 @@ module AnalyticsOps
         value == "realtime"
       end
 
-      def api_names(values, label, maximum:)
-        unless values.is_a?(Array) && values.any? && values.length <= maximum &&
+      def api_names(values, label, minimum:, maximum:)
+        unless values.is_a?(Array) && values.length.between?(minimum, maximum) &&
                values.all? { |value| valid_api_name?(value) }
-          raise InvalidRequestError, "Report #{label} must contain 1 to #{maximum} valid Data API names"
+          raise InvalidRequestError,
+                "Report #{label} must contain #{minimum} to #{maximum} valid Data API names"
         end
         unless values.uniq.length == values.length
           raise InvalidRequestError,
@@ -92,23 +95,28 @@ module AnalyticsOps
         raise InvalidRequestError, "date_ranges must be an array" unless values.is_a?(Array)
         raise InvalidRequestError, "A report can contain at most four date ranges" if values.length > 4
 
-        normalized = values.map do |range|
-          hash = string_hash(range, "date range", %w[start_date end_date name])
-          start_date = date(hash.fetch("start_date") { invalid!("Missing start_date") })
-          end_date = date(hash.fetch("end_date") { invalid!("Missing end_date") })
-          validate_date_order!(start_date, end_date)
-
-          result = { "start_date" => start_date, "end_date" => end_date }
-          if hash.key?("name")
-            range_name = hash.fetch("name")
-            invalid!("Date range name is invalid") unless range_name.is_a?(String) && RANGE_NAME.match?(range_name)
-            result["name"] = range_name
-          end
-          result
-        end
+        normalized = values.map { |range| normalize_range(range) }
+        names = normalized.filter_map { |range| range["name"] }
+        invalid!("Date range names must be unique") unless names.uniq.length == names.length
+
         Canonical.immutable(normalized)
       end
 
+      def normalize_range(range)
+        hash = string_hash(range, "date range", %w[start_date end_date name])
+        start_date = date(hash.fetch("start_date") { invalid!("Missing start_date") })
+        end_date = date(hash.fetch("end_date") { invalid!("Missing end_date") })
+        validate_date_order!(start_date, end_date)
+        result = { "start_date" => start_date, "end_date" => end_date }
+        return result unless hash.key?("name")
+
+        range_name = hash.fetch("name")
+        valid = range_name.is_a?(String) && RANGE_NAME.match?(range_name) &&
+                !range_name.start_with?("date_range_")
+        invalid!("Date range name is invalid or reserved") unless valid
+        result.merge("name" => range_name)
+      end
+
       def date(value)
         invalid!("Invalid report date") unless value.is_a?(String)
         return value if %w[today yesterday].include?(value)
@@ -116,6 +124,8 @@ module AnalyticsOps
         relative = RELATIVE_DATE.match(value)
         return value if relative && relative[1].to_i <= 3650
 
+        invalid!("Invalid report date") unless ABSOLUTE_DATE.match?(value)
+
         Date.iso8601(value)
         value
       rescue Date::Error
@@ -123,12 +133,25 @@ module AnalyticsOps
       end
 
       def validate_date_order!(start_date, end_date)
-        return unless start_date.match?(/\A\d{4}-/) && end_date.match?(/\A\d{4}-/)
-        return if Date.iso8601(start_date) <= Date.iso8601(end_date)
+        if ABSOLUTE_DATE.match?(start_date) && ABSOLUTE_DATE.match?(end_date)
+          return if Date.iso8601(start_date) <= Date.iso8601(end_date)
+        else
+          start_offset = relative_date_offset(start_date)
+          end_offset = relative_date_offset(end_date)
+          return unless start_offset && end_offset
+          return if start_offset >= end_offset
+        end
 
         invalid!("Report start_date must not be after end_date")
       end
 
+      def relative_date_offset(value)
+        return 0 if value == "today"
+        return 1 if value == "yesterday"
+
+        RELATIVE_DATE.match(value)&.[](1)&.to_i
+      end
+
       def string_filter(value)
         return nil if value.nil?
 
@@ -157,35 +180,49 @@ module AnalyticsOps
         field = hash.fetch("field") { invalid!("Missing metric filter field") }
         operation = hash.fetch("operation") { invalid!("Missing metric filter operation") }
         number = hash.fetch("value") { invalid!("Missing metric filter value") }
-        valid = valid_api_name?(field) && metrics.include?(field) &&
-                NUMERIC_OPERATIONS.include?(operation) && number.is_a?(Numeric)
+        valid = valid_api_name?(field) && metrics.include?(field) && NUMERIC_OPERATIONS.include?(operation)
         invalid!("Metric filter is invalid or references an unselected metric") unless valid
-        invalid!("Metric filter value must be finite") unless number.finite?
+        unless valid_numeric_filter_value?(number)
+          invalid!("Metric filter value must be a finite int64 Integer or Float")
+        end
 
         Canonical.immutable("field" => field, "operation" => operation, "value" => number)
       end
 
+      def valid_numeric_filter_value?(number)
+        (number.is_a?(Integer) && INT64_RANGE.cover?(number)) || (number.is_a?(Float) && number.finite?)
+      end
+
       def orders(values)
         raise InvalidRequestError, "order_bys must be an array" unless values.is_a?(Array)
         raise InvalidRequestError, "A report can contain at most ten order clauses" if values.length > 10
 
-        normalized = values.map do |order|
-          hash = string_hash(order, "report order", %w[metric dimension desc])
-          selectors = %w[metric dimension].select { |key| hash.key?(key) }
-          invalid!("Report order requires exactly one metric or dimension") unless selectors.length == 1
-
-          selector = selectors.first
-          api_name = hash.fetch(selector)
-          selected = selector == "metric" ? metrics : dimensions
-          unless valid_api_name?(api_name) && selected.include?(api_name)
-            invalid!("Report order references an unselected #{selector}")
-          end
+        normalized = values.map { |order| normalize_order(order) }
+        identities = normalized.map { |order| order_identity(order) }
+        invalid!("Report order clauses must reference unique fields") unless identities.uniq.length == identities.length
 
-          { selector => api_name, "desc" => hash.key?("desc") ? boolean(hash.fetch("desc"), "desc") : false }
-        end
         Canonical.immutable(normalized)
       end
 
+      def normalize_order(order)
+        hash = string_hash(order, "report order", %w[metric dimension desc])
+        selectors = %w[metric dimension].select { |key| hash.key?(key) }
+        invalid!("Report order requires exactly one metric or dimension") unless selectors.length == 1
+
+        selector = selectors.first
+        api_name = hash.fetch(selector)
+        selected = selector == "metric" ? metrics : dimensions
+        valid = valid_api_name?(api_name) && selected.include?(api_name)
+        invalid!("Report order references an unselected #{selector}") unless valid
+
+        { selector => api_name, "desc" => hash.key?("desc") ? boolean(hash.fetch("desc"), "desc") : false }
+      end
+
+      def order_identity(order)
+        selector = order.key?("metric") ? "metric" : "dimension"
+        [selector, order.fetch(selector)]
+      end
+
       def validate_shape!
         invalid!("Realtime reports cannot include date ranges") if realtime? && !date_ranges.empty?
         invalid!("Realtime reports do not support offset") if realtime? && offset.positive?

data/lib/analytics_ops/reports/overview.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Reports
+    # Internal catalog for the small reports shown by Workspace#overview.
+    module Overview
+      DEFINITIONS = [
+        Definition.new(
+          name: "overview_totals",
+          kind: "standard",
+          dimensions: [],
+          metrics: %w[activeUsers sessions keyEvents],
+          date_ranges: Catalog::STANDARD_DATE_RANGE,
+          limit: 1
+        ),
+        Definition.new(
+          name: "overview_trend",
+          kind: "standard",
+          dimensions: %w[date],
+          metrics: %w[activeUsers sessions keyEvents],
+          date_ranges: Catalog::STANDARD_DATE_RANGE,
+          order_bys: [{ "dimension" => "date", "desc" => false }],
+          limit: 31
+        ),
+        Definition.new(
+          name: "overview_acquisition",
+          kind: "standard",
+          dimensions: %w[sessionDefaultChannelGroup],
+          metrics: %w[sessions activeUsers keyEvents],
+          date_ranges: Catalog::STANDARD_DATE_RANGE,
+          order_bys: [{ "metric" => "sessions", "desc" => true }],
+          limit: 10
+        ),
+        Definition.new(
+          name: "overview_landing_pages",
+          kind: "standard",
+          dimensions: %w[landingPagePlusQueryString],
+          metrics: %w[sessions activeUsers keyEvents],
+          date_ranges: Catalog::STANDARD_DATE_RANGE,
+          order_bys: [{ "metric" => "sessions", "desc" => true }],
+          limit: 10
+        ),
+        Definition.new(
+          name: "overview_devices",
+          kind: "standard",
+          dimensions: %w[deviceCategory],
+          metrics: %w[activeUsers sessions keyEvents],
+          date_ranges: Catalog::STANDARD_DATE_RANGE,
+          order_bys: [{ "metric" => "activeUsers", "desc" => true }],
+          limit: 10
+        )
+      ].freeze
+    end
+  end
+end

data/lib/analytics_ops/reports/overview_result.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Reports
+    # Immutable collection of the bounded reports that make up an overview.
+    class OverviewResult
+      MAX_REPORTS = 5
+      PROPERTY_ID = /\A\d{1,50}\z/
+
+      attr_reader :property_id, :reports, :property_quota
+
+      def initialize(property_id:, reports:)
+        unless property_id.is_a?(String) && PROPERTY_ID.match?(property_id)
+          raise RemoteError, "Overview property ID is invalid"
+        end
+        unless reports.is_a?(Array) && reports.length.between?(1, MAX_REPORTS) &&
+               reports.all? { |report| report.is_a?(Result) && report.kind == "standard" }
+          raise RemoteError, "Overview must contain 1 to #{MAX_REPORTS} standard report results"
+        end
+
+        names = reports.map(&:name)
+        raise RemoteError, "Overview report names must be unique" unless names.uniq.length == names.length
+
+        @property_id = property_id.dup.freeze
+        @reports = reports.dup.freeze
+        @property_quota = Canonical.immutable(latest_quota)
+        freeze
+      end
+
+      def report(name)
+        reports.find { |result| result.name == name.to_s } ||
+          raise(KeyError, "Unknown overview report #{name.inspect}")
+      end
+
+      def to_h
+        {
+          "property_id" => property_id,
+          "reports" => reports.map(&:to_h),
+          "property_quota" => property_quota
+        }
+      end
+
+      private
+
+      def latest_quota
+        reports.reverse_each do |result|
+          quota = result.metadata["property_quota"]
+          return quota if quota
+        end
+        {}
+      end
+    end
+  end
+end

data/lib/analytics_ops/reports/result.rb

@@ -4,24 +4,21 @@ module AnalyticsOps
   module Reports
     # Immutable normalized Data API response.
     class Result
-      attr_reader :name, :kind, :dimension_headers, :metric_headers, :rows, :row_count, :metadata
+      attr_reader :name, :kind, :dimension_headers, :metric_headers, :headers, :rows, :row_count, :metadata
 
       def initialize(name:, kind:, dimension_headers:, metric_headers:, rows:, row_count:, metadata:)
         @name = string(name, "name")
         @kind = kind_value(kind)
         @dimension_headers = normalize_headers(dimension_headers, "dimension_headers")
         @metric_headers = normalize_headers(metric_headers, "metric_headers")
+        @headers = Canonical.immutable(@dimension_headers + @metric_headers)
         validate_header_uniqueness!
         @rows = normalized_rows(rows)
         @row_count = count(row_count)
-        @metadata = hash(metadata, "metadata")
+        @metadata = normalized_metadata(metadata)
         freeze
       end
 
-      def headers
-        dimension_headers + metric_headers
-      end
-
       def to_h
         {
           "name" => name,
@@ -37,7 +34,7 @@ module AnalyticsOps
       private
 
       def string(value, label)
-        return value.dup.freeze if value.is_a?(String) && !value.empty?
+        return value.dup.freeze if valid_utf8?(value) && !value.empty?
 
         raise RemoteError, "Report result #{label} is invalid"
       end
@@ -49,9 +46,10 @@ module AnalyticsOps
       end
 
       def normalize_headers(values, label)
-        unless values.is_a?(Array) && values.all? { |value| value.is_a?(String) && !value.empty? }
-          raise RemoteError, "Report result #{label} is invalid"
+        valid = values.is_a?(Array) && values.all? do |value|
+          valid_utf8?(value) && !value.empty? && value.length <= 128 && !value.match?(/[\u0000-\u001f\u007f]/)
         end
+        raise RemoteError, "Report result #{label} is invalid" unless valid
 
         Canonical.immutable(values)
       end
@@ -66,6 +64,9 @@ module AnalyticsOps
         normalized = values.map do |row|
           value = hash(row, "row")
           raise RemoteError, "Report result row fields do not match headers" unless value.keys.sort == headers.sort
+          unless value.values.all? { |item| valid_utf8?(item) }
+            raise RemoteError, "Report result row values must be valid UTF-8 strings"
+          end
 
           value
         end
@@ -85,6 +86,34 @@ module AnalyticsOps
 
         Canonical.immutable(value)
       end
+
+      def normalized_metadata(value)
+        raise RemoteError, "Report result metadata must be an object" unless value.is_a?(Hash)
+
+        validate_metadata_value!(value, "metadata")
+        Canonical.immutable(value)
+      end
+
+      def validate_metadata_value!(value, path)
+        case value
+        when Hash
+          raise RemoteError, "Report result #{path} keys must be strings" unless value.keys.all?(String)
+
+          value.each { |key, child| validate_metadata_value!(child, "#{path}.#{key}") }
+        when Array
+          value.each.with_index { |child, index| validate_metadata_value!(child, "#{path}[#{index}]") }
+        when String, Integer, TrueClass, FalseClass, NilClass
+          raise RemoteError, "Report result #{path} must be valid UTF-8" if value.is_a?(String) && !valid_utf8?(value)
+        when Float
+          raise RemoteError, "Report result #{path} must be finite" unless value.finite?
+        else
+          raise RemoteError, "Report result #{path} has an unsupported value"
+        end
+      end
+
+      def valid_utf8?(value)
+        value.is_a?(String) && value.encoding == Encoding::UTF_8 && value.valid_encoding?
+      end
     end
   end
 end

data/lib/analytics_ops/reports.rb

@@ -4,7 +4,9 @@
 
 require_relative "reports/definition"
 require_relative "reports/catalog"
+require_relative "reports/overview"
 require_relative "reports/result"
+require_relative "reports/overview_result"
 
 module AnalyticsOps
   # Immutable Data API definitions, recipes, and normalized results.

data/lib/analytics_ops/resources.rb

@@ -73,7 +73,8 @@ module AnalyticsOps
 
     # Registered custom metric.
     class CustomMetric < Value
-      fields :name, :parameter_name, :display_name, :description, :scope, :measurement_unit
+      fields :name, :parameter_name, :display_name, :description, :scope, :measurement_unit,
+             :restricted_metric_types
     end
   end
 end

data/lib/analytics_ops/service_account.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+
+module AnalyticsOps
+  # The single supported Google authentication source.
+  class ServiceAccount
+    MAX_KEY_BYTES = 64 * 1024
+    READ_SCOPE = "https://www.googleapis.com/auth/analytics.readonly"
+    EDIT_SCOPE = "https://www.googleapis.com/auth/analytics.edit"
+    ACCESS_SCOPES = {
+      read: [READ_SCOPE].freeze,
+      edit: [READ_SCOPE, EDIT_SCOPE].freeze
+    }.freeze
+    REQUIRED_FIELDS = %w[type client_email private_key token_uri].freeze
+    CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/
+
+    attr_reader :path
+
+    def self.load(path: nil, store: Store.new)
+      new(path || store.read)
+    end
+
+    def initialize(path)
+      @path = validated_path(path).freeze
+      validate_key!
+      freeze
+    end
+
+    def credentials(access: :read)
+      build_credentials(scopes_for(access))
+    end
+    private :credentials
+
+    private
+
+    def scopes_for(access)
+      ACCESS_SCOPES.fetch(access) { raise ArgumentError, "access must be :read or :edit" }
+    end
+
+    def build_credentials(scopes)
+      require "googleauth"
+      File.open(path, "rb") do |key|
+        Google::Auth::ServiceAccountCredentials.make_creds(json_key_io: key, scope: scopes)
+      end
+    rescue LoadError => error
+      raise UnsupportedCapabilityError,
+            "Google authentication support is unavailable: #{Redaction.message(error.message)}"
+    rescue AnalyticsOps::Error
+      raise
+    rescue StandardError
+      raise AuthenticationError, "The configured service-account key could not be loaded"
+    end
+
+    def validated_path(value)
+      unless value.is_a?(String) && !value.empty? && !value.match?(CONTROL_CHARACTERS)
+        raise AuthenticationError, "A valid service-account key path is required"
+      end
+
+      expanded = File.expand_path(value)
+      unless File.file?(expanded)
+        raise AuthenticationError,
+              "The configured service-account key is unavailable; run " \
+              "`analytics-ops setup --service-account /absolute/path/to/service-account.json`"
+      end
+      if File.size(expanded) > MAX_KEY_BYTES
+        raise AuthenticationError, "The configured service-account key is too large"
+      end
+
+      File.realpath(expanded)
+    rescue AnalyticsOps::Error
+      raise
+    rescue SystemCallError
+      raise AuthenticationError,
+            "The configured service-account key is unavailable; run " \
+            "`analytics-ops setup --service-account /absolute/path/to/service-account.json`"
+    end
+
+    def validate_key!
+      document = JSON.parse(File.binread(path, MAX_KEY_BYTES + 1), max_nesting: 8)
+      valid = document.is_a?(Hash) &&
+              document["type"] == "service_account" &&
+              REQUIRED_FIELDS.all? { |field| document[field].is_a?(String) && !document[field].empty? }
+      return if valid
+
+      raise AuthenticationError, "The selected JSON file is not a Google service-account key"
+    rescue AnalyticsOps::Error
+      raise
+    rescue JSON::ParserError, ArgumentError, SystemCallError
+      raise AuthenticationError, "The selected JSON file is not a valid Google service-account key"
+    end
+
+    # User-level pointer to a validated key. The key itself is never copied.
+    class Store
+      VERSION = 1
+      MAX_BYTES = 16 * 1024
+      FIELDS = %w[service_account_path version].freeze
+
+      attr_reader :path
+
+      def self.default_path
+        File.join(Dir.home, ".config", "analytics_ops", "connection.json")
+      rescue ArgumentError
+        raise AuthenticationError, "Cannot determine the user configuration directory"
+      end
+
+      def initialize(path: nil)
+        candidate = path || self.class.default_path
+        unless candidate.is_a?(String) && !candidate.empty? && !candidate.match?(CONTROL_CHARACTERS)
+          raise AuthenticationError, "The Analytics Ops connection path is invalid"
+        end
+
+        @path = File.expand_path(candidate).freeze
+      end
+
+      def read
+        unless File.file?(path)
+          raise AuthenticationError,
+                "No service account is configured; run " \
+                "`analytics-ops setup --service-account /absolute/path/to/service-account.json`"
+        end
+        raise AuthenticationError, "The saved Analytics Ops connection is too large" if File.size(path) > MAX_BYTES
+
+        document = JSON.parse(File.binread(path, MAX_BYTES + 1), max_nesting: 4)
+        valid = document.is_a?(Hash) &&
+                document.keys.sort == FIELDS &&
+                document["version"] == VERSION &&
+                document["service_account_path"].is_a?(String)
+        return document.fetch("service_account_path") if valid
+
+        raise AuthenticationError, invalid_connection_message
+      rescue AnalyticsOps::Error
+        raise
+      rescue JSON::ParserError, ArgumentError, SystemCallError
+        raise AuthenticationError, invalid_connection_message
+      end
+
+      def write(service_account_path)
+        normalized = ServiceAccount.new(service_account_path).path
+        directory = File.dirname(path)
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        File.chmod(0o700, directory)
+        temporary = File.join(directory, ".connection.#{Process.pid}.#{SecureRandom.hex(6)}.tmp")
+        payload = JSON.generate("version" => VERSION, "service_account_path" => normalized) << "\n"
+
+        File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+          file.write(payload)
+          file.flush
+          file.fsync
+        end
+        File.rename(temporary, path)
+        File.chmod(0o600, path)
+        path
+      rescue AnalyticsOps::Error
+        raise
+      rescue SystemCallError
+        raise AuthenticationError, "Cannot save the Analytics Ops service-account connection"
+      ensure
+        File.unlink(temporary) if temporary && File.exist?(temporary)
+      end
+
+      private
+
+      def invalid_connection_message
+        "The saved Analytics Ops connection is invalid; rerun setup with --service-account"
+      end
+    end
+  end
+end