trifle-stats 2.5.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '014813aa6a45f6fece54f7fc332272c85023a37236cd3b4eeb270f3f00fed3a0'
-  data.tar.gz: f83d0bfecc64f03cd3160e3762eb09a12d76ea8c9cda78c8108ee063bd8caf50
+  metadata.gz: 70c1c7a45dc8833c358ebab3d93a55e15f1f42f4459eb0d5fab14b7383de0a04
+  data.tar.gz: c09506de6ef9cd69b35733a616d43a09aa62ad8c6013f32552d1a0b7dcf870f6
 SHA512:
-  metadata.gz: 71ecb7d927d16ec3f29fec1f57624b8f72bb482841a7a6c0d948ddf8ddc42b0d8b88b858f12436a330189a0731ba41d9514332cfc25e4721c3b7387f11d1c809
-  data.tar.gz: da222c50726b1241f2fbfe86c21553c1fea4393c80e53c065e94ea4895fbf755fb6f1e59d15b61b3d1219d114fb444b1bc4eb935b21e9970a4b704b0348a23fc
+  metadata.gz: c980da761d8029b971ad9520d898d1971ba164c7cb2a1d7ffdbad60c67820cbb7eecf0ca25fa547518f06615dbe71411f376e20f2672dac1c9fca5c5dddaa5aa
+  data.tar.gz: 23266f716645654a5b642abf1558bbc85667b069dfb1caa98cfa1cc0899fd732769d2e0628107d06397b9b50996630b24a8f4ad6b634c5a8851d9984a66c7ad0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    trifle-stats (2.5.0)
+    trifle-stats (2.7.0)
       tzinfo (~> 2.0)
 
 GEM
@@ -11,7 +11,7 @@ GEM
     bigdecimal (4.0.1)
     bson (4.12.1)
     byebug (11.1.3)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.8)
     diff-lcs (1.4.4)
     dotenv (2.7.6)
     mini_portile2 (2.8.9)

data/README.md

@@ -80,6 +80,7 @@ series.aggregate.sum(path: 'count')
 
 | Driver | Backend | Best for |
 |--------|---------|----------|
+| **API** | Trifle Cloud Projects | Hosted metrics without your own database |
 | **Postgres** | JSONB upsert | Most production apps |
 | **Redis** | Hash increment | High-throughput counters |
 | **MongoDB** | Document upsert | Document-oriented stacks |

data/lib/trifle/stats/configuration.rb

@@ -42,6 +42,7 @@ module Trifle
 
       def storage
         return driver unless buffer_enabled
+        return driver if driver.respond_to?(:bypass_buffer?) && driver.bypass_buffer?
 
         @storage ||= Trifle::Stats::Buffer.new(
           driver: driver,

data/lib/trifle/stats/driver/api.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'stringio'
+require 'time'
+require 'uri'
+require 'zlib'
+require_relative '../version'
+
+module Trifle
+  module Stats
+    module Driver
+      class Api
+        ENDPOINT = URI('https://app.trifle.io/api/v1/metrics')
+        TIMEOUT = 10
+        ERROR_BODY_LIMIT = 1024
+
+        class Error < Trifle::Stats::Error
+          attr_reader :status, :response_body, :retry_after, :delivery_unknown
+
+          def initialize(message, status: nil, response_body: nil, retry_after: nil, delivery_unknown: false)
+            super(message)
+            @status = status
+            @response_body = response_body
+            @retry_after = retry_after
+            @delivery_unknown = delivery_unknown
+          end
+        end
+
+        class NetHttpTransport
+          def call(uri:, request:, timeout:)
+            Net::HTTP.start(
+              uri.hostname,
+              uri.port,
+              use_ssl: uri.scheme == 'https',
+              open_timeout: timeout,
+              read_timeout: timeout
+            ) { |http| http.request(request) }
+          end
+        end
+
+        attr_reader :token, :project_id
+
+        def initialize(token:, project_id:, transport: NetHttpTransport.new)
+          raise ArgumentError, 'token must not be empty' if token.to_s.strip.empty?
+          raise ArgumentError, 'project_id must not be empty' if project_id.to_s.strip.empty?
+
+          @token = token.to_s
+          @project_id = project_id.to_s
+          @transport = transport
+        end
+
+        def description
+          self.class.name
+        end
+
+        def bypass_buffer?
+          true
+        end
+
+        def direct_write(operation:, key:, at:, values:, untracked: false)
+          payload = api_payload(operation, key, at, values, untracked)
+          deliver(build_request(payload))
+        rescue Error
+          raise
+        rescue StandardError => e
+          raise Error.new("Trifle API request failed: #{e.message}", delivery_unknown: true), cause: e
+        end
+
+        def inc(*)
+          unsupported!(:track)
+        end
+
+        def set(*)
+          unsupported!(:assert)
+        end
+
+        def get(*)
+          unsupported!(:values)
+        end
+
+        def ping(*)
+          unsupported!(:beam)
+        end
+
+        def scan(*)
+          unsupported!(:scan)
+        end
+
+        private
+
+        def api_payload(operation, key, at, values, untracked)
+          {
+            operation: operation.to_s,
+            key: key,
+            at: at.to_time.iso8601(6),
+            values: values,
+            untracked: untracked
+          }
+        end
+
+        def build_request(payload)
+          request = Net::HTTP::Post.new(ENDPOINT, request_headers)
+          request.body = gzip(JSON.generate(payload))
+          request
+        end
+
+        def request_headers
+          {
+            'Authorization' => "Bearer #{token}",
+            'X-Trifle-Source-Id' => project_id,
+            'Content-Type' => 'application/json',
+            'Accept' => 'application/json',
+            'Content-Encoding' => 'gzip',
+            'User-Agent' => "trifle-stats-ruby/#{Trifle::Stats::VERSION}"
+          }
+        end
+
+        def deliver(request)
+          response = @transport.call(uri: ENDPOINT, request: request, timeout: TIMEOUT)
+          return true if response.code.to_i.between?(200, 299)
+
+          raise_response_error(response)
+        end
+
+        def raise_response_error(response)
+          raise Error.new(
+            "Trifle API returned HTTP #{response.code}",
+            status: response.code.to_i,
+            response_body: response.body.to_s.byteslice(0, ERROR_BODY_LIMIT),
+            retry_after: response['Retry-After']
+          )
+        end
+
+        def gzip(value)
+          output = StringIO.new
+          Zlib::GzipWriter.wrap(output) { |writer| writer.write(value) }
+          output.string
+        end
+
+        def unsupported!(operation)
+          message = "#{operation} must be called through Trifle::Stats; " \
+                    'API driver does not support direct storage operations'
+          raise Error, message
+        end
+      end
+    end
+  end
+end

data/lib/trifle/stats/nocturnal.rb

@@ -26,7 +26,8 @@ module Trifle
         item = from.dup
         while item <= to
           list << item
-          item = new(item, config: config).add(offset, unit)
+          candidate = new(item, config: config).add(offset, unit)
+          item = new(candidate, config: config).floor(offset, unit)
         end
         list
       end
@@ -49,53 +50,21 @@ module Trifle
 
         case unit
         when :second
-          time + offset
+          add_elapsed(offset)
         when :minute
-          time + (offset * 60)
+          add_elapsed(offset * 60)
         when :hour
-          time + (offset * 3600)
+          add_elapsed(offset * 3600)
         when :day
-          time + (offset * 86_400)
+          add_days(calendar_offset(offset))
         when :week
-          time + (offset * 604_800)
+          add_days(calendar_offset(offset) * 7)
         when :month
-          # Handle months carefully due to varying lengths
-          result = time
-          offset.times do
-            result = add_one_month(result)
-          end
-          result
+          add_months(calendar_offset(offset))
         when :quarter
-          # Add 3 months for each quarter
-          result = time
-          (offset * 3).times do
-            result = add_one_month(result)
-          end
-          result
+          add_months(calendar_offset(offset) * 3)
         when :year
-          # Handle years carefully due to leap years
-          begin
-            Time.new(
-              time.year + offset,
-              time.month,
-              time.day,
-              time.hour,
-              time.min,
-              time.sec,
-              config.tz.utc_offset
-            )
-          rescue ArgumentError
-            # Handle edge cases like Feb 29 in non-leap years
-            Time.new(
-              time.year + offset,
-              time.month,
-              [time.day, days_in_month(time.year + offset, time.month)].min,
-              time.hour,
-              time.min,
-              time.sec,
-              time.utc_offset
-            )
-          end
+          add_years(calendar_offset(offset))
         end
       end
 
@@ -104,89 +73,193 @@ module Trifle
         raise ArgumentError, 'Segment size must be positive' unless offset.positive?
         raise ArgumentError, "Invalid unit: #{unit}" unless Trifle::Stats::Nocturnal::UNIT_MAP.values.include?(unit)
 
+        source = localized_time
+
         case unit
         when :second
           # Floor to second segment boundary
-          total_seconds = time.sec
+          total_seconds = source.sec
           floored_seconds = (total_seconds / offset) * offset
-          Time.new(time.year, time.month, time.day, time.hour, time.min, floored_seconds, time.utc_offset)
+          subtract_elapsed(source, (total_seconds - floored_seconds) + source.subsec)
 
         when :minute
           # Floor to minute segment boundary (segments start from beginning of hour)
-          minutes_from_hour_start = time.min
+          minutes_from_hour_start = source.min
           floored_minutes = (minutes_from_hour_start / offset) * offset
-          Time.new(time.year, time.month, time.day, time.hour, floored_minutes, 0, time.utc_offset)
+          seconds = ((minutes_from_hour_start - floored_minutes) * 60) + source.sec + source.subsec
+          subtract_elapsed(source, seconds)
 
         when :hour
-          # Floor to hour segment boundary (segments start from beginning of day)
-          hours_from_day_start = time.hour
-          floored_hours = (hours_from_day_start / offset) * offset
-          Time.new(time.year, time.month, time.day, floored_hours, 0, 0, time.utc_offset)
+          # Hour segments are elapsed durations anchored at local day start.
+          day_start = local_midnight(source.to_date, source)
+          segment = offset * 3600
+          elapsed = source - day_start
+          add_elapsed_to(day_start, (elapsed / segment).floor * segment)
 
         when :day
           # Floor to day segment boundary (segments start from beginning of year)
-          days_from_year_start = time.yday - 1 # yday is 1-indexed, we want 0-indexed
+          days_from_year_start = source.yday - 1 # yday is 1-indexed, we want 0-indexed
           floored_days = (days_from_year_start / offset) * offset
-          year_start = Time.new(time.year, 1, 1, 0, 0, 0, time.utc_offset)
-          result_date = year_start.to_date + floored_days
-          Time.new(result_date.year, result_date.month, result_date.day, 0, 0, 0, time.utc_offset)
+          result_date = Date.new(source.year, 1, 1) + floored_days
+          local_midnight(result_date, source)
 
         when :week
           # Floor to week segment boundary (segments start from beginning of year)
-          year_start = Time.new(time.year, 1, 1, 0, 0, 0, time.utc_offset)
+          year_start_date = Date.new(source.year, 1, 1)
 
           # Find the first week boundary of the year based on week_start
-          week_start_offset = DAYS_INTO_WEEK.fetch(
-            config.beginning_of_week
-          )
-          year_start_wday = year_start.wday
+          week_start_offset = DAYS_INTO_WEEK.fetch(config.beginning_of_week)
+          year_start_wday = year_start_date.wday
           days_to_first_week_start = (week_start_offset - year_start_wday) % 7
-          first_week_start = year_start.to_date + days_to_first_week_start
-          first_week_start_time = Time.new(first_week_start.year, first_week_start.month, first_week_start.day, 0, 0, 0, time.utc_offset) # rubocop:disable Layout/LineLength
+          first_week_start = year_start_date + days_to_first_week_start
 
           # If current time is before first week boundary, use year start
-          if time < first_week_start_time
-            year_start
+          if source.to_date < first_week_start
+            local_midnight(year_start_date, source)
           else
-            # Calculate weeks since first week start
-            weeks_since_first = ((time - first_week_start_time) / (7 * 86_400)).to_i
+            weeks_since_first = ((source.to_date - first_week_start).to_i / 7)
             floored_weeks = (weeks_since_first / offset) * offset
 
             result_date = first_week_start + (floored_weeks * 7)
-            Time.new(result_date.year, result_date.month, result_date.day, 0, 0, 0, time.utc_offset)
+            local_midnight(result_date, source)
           end
 
         when :month
           # Floor to month segment boundary (from start of year)
-          months_from_jan = time.month - 1 # 0-indexed
+          months_from_jan = source.month - 1 # 0-indexed
           floored_months = (months_from_jan / offset) * offset
-          Time.new(time.year, floored_months + 1, 1, 0, 0, 0, time.utc_offset)
+          date = Date.new(source.year, floored_months + 1, 1)
+          local_midnight(date, source)
 
         when :quarter
           # Floor to quarter segment boundary
-          current_quarter = ((time.month - 1) / 3) # 0-indexed quarters
+          current_quarter = ((source.month - 1) / 3) # 0-indexed quarters
           floored_quarters = (current_quarter / offset) * offset
           quarter_start_month = (floored_quarters * 3) + 1
-          Time.new(time.year, quarter_start_month, 1, 0, 0, 0, time.utc_offset)
+          date = Date.new(source.year, quarter_start_month, 1)
+          local_midnight(date, source)
 
         when :year
           # Floor to year segment boundary
-          floored_years = (time.year / offset) * offset
-          Time.new(floored_years, 1, 1, 0, 0, 0, time.utc_offset)
+          floored_years = (source.year / offset) * offset
+          date = Date.new(floored_years, 1, 1)
+          local_midnight(date, source)
         end
       end
 
       private
 
-      def add_one_month(time) # rubocop:disable Metrics/AbcSize
-        next_month = time.month == 12 ? 1 : time.month + 1
-        next_year = time.month == 12 ? time.year + 1 : time.year
+      def add_elapsed(seconds)
+        add_elapsed_to(time, seconds)
+      end
+
+      def add_elapsed_to(source, seconds)
+        config.tz.utc_to_local((source + seconds).getutc)
+      end
+
+      def subtract_elapsed(source, seconds)
+        config.tz.utc_to_local((source - seconds).getutc)
+      end
+
+      def add_days(days)
+        source = localized_time
+        local_time_for_source(source.to_date + days, source)
+      end
+
+      def add_months(months)
+        source = localized_time
+        total_months = (source.year * 12) + (source.month - 1) + months
+        year, month_index = total_months.divmod(12)
+        month = month_index + 1
+        day = [source.day, days_in_month(year, month)].min
+
+        local_time_for_source(Date.new(year, month, day), source)
+      end
+
+      def add_years(years)
+        source = localized_time
+        year = source.year + years
+        day = [source.day, days_in_month(year, source.month)].min
+
+        local_time_for_source(Date.new(year, source.month, day), source)
+      end
+
+      def localized_time
+        config.tz.utc_to_local(time.getutc)
+      end
+
+      def calendar_offset(offset)
+        return offset if offset.is_a?(Integer)
+
+        raise ArgumentError, 'Offset must be an integer for calendar units'
+      end
+
+      def local_midnight(date, source)
+        local_time(date, source: source, hour: 0, minute: 0, second: 0)
+      end
+
+      def local_time_for_source(date, source)
+        local_time(
+          date,
+          source: source,
+          hour: source.hour,
+          minute: source.min,
+          second: source.sec,
+          sub_second: source.subsec
+        )
+      end
 
-        # Handle the case where the day doesn't exist in the next month (e.g., Jan 31 -> Feb 31)
-        max_day = days_in_month(next_year, next_month)
-        day = [time.day, max_day].min
+      def local_time(date, source:, **clock)
+        clock = { hour: 0, minute: 0, second: 0, sub_second: 0 }.merge(clock)
+        config.tz.local_time(
+          date.year, date.month, date.day,
+          clock[:hour], clock[:minute], clock[:second], clock[:sub_second], source.dst?
+        )
+      rescue TZInfo::AmbiguousTime
+        resolve_ambiguous_time(date, clock, source)
+      rescue TZInfo::PeriodNotFound
+        resolve_missing_time(date, clock, source)
+      end
+
+      def resolve_ambiguous_time(date, clock, source)
+        timestamp = local_timestamp(date, clock)
+        periods = config.tz.periods_for_local(timestamp)
+        period = periods.find { |candidate| candidate.observed_utc_offset == source.utc_offset } || periods.first
+        config.tz.utc_to_local(Time.at(timestamp.to_r - period.observed_utc_offset).utc)
+      end
+
+      def resolve_missing_time(date, clock, source)
+        timestamp = local_timestamp(date, clock)
+        transition = missing_time_transition(timestamp)
+        raise TZInfo::PeriodNotFound, timestamp.to_s unless transition
+
+        gap = transition.offset.observed_utc_offset - transition.previous_offset.observed_utc_offset
+        shifted = timestamp + gap
+        shifted_clock = { hour: shifted.hour, minute: shifted.min, second: shifted.sec, sub_second: shifted.subsec }
+        local_time(shifted.to_date, source: source, **shifted_clock)
+      end
+
+      def missing_time_transition(timestamp)
+        config.tz.transitions_up_to(timestamp + 172_800, timestamp - 172_800).find do |transition|
+          missing_time_transition?(timestamp, transition)
+        end
+      end
+
+      def missing_time_transition?(timestamp, transition)
+        previous_offset = transition.previous_offset.observed_utc_offset
+        next_offset = transition.offset.observed_utc_offset
+        return false unless next_offset > previous_offset
+
+        start_at = transition.at.to_time + previous_offset
+        end_at = transition.at.to_time + next_offset
+        timestamp >= start_at && timestamp < end_at
+      end
 
-        Time.new(next_year, next_month, day, time.hour, time.min, time.sec, config.tz.utc_offset)
+      def local_timestamp(date, clock)
+        Time.utc(
+          date.year, date.month, date.day,
+          clock[:hour], clock[:minute], clock[:second] + clock[:sub_second]
+        )
       end
 
       def days_in_month(year, month)

data/lib/trifle/stats/operations/timeseries/increment.rb

@@ -26,6 +26,30 @@ module Trifle
           end
 
           def perform
+            return direct_write if direct_write?
+
+            buffered_write
+          end
+
+          def tracking_key
+            @untracked ? '__untracked__' : nil
+          end
+
+          private
+
+          def direct_write?
+            config.driver.respond_to?(:direct_write)
+          end
+
+          def direct_write
+            config.driver.direct_write(**direct_payload)
+          end
+
+          def direct_payload
+            { operation: :track, key: key, at: @at, values: values, untracked: @untracked }
+          end
+
+          def buffered_write
             payload = {
               keys: config.granularities.map { |granularity| key_for(granularity: granularity) },
               values: values
@@ -38,12 +62,6 @@ module Trifle
             end
           end
 
-          def tracking_key
-            @untracked ? '__untracked__' : nil
-          end
-
-          private
-
           def localized_time(time)
             base_time = time.is_a?(Time) ? time : time.to_time
             config.tz.utc_to_local(base_time.getutc)

data/lib/trifle/stats/operations/timeseries/set.rb

@@ -26,6 +26,30 @@ module Trifle
           end
 
           def perform
+            return direct_write if direct_write?
+
+            buffered_write
+          end
+
+          def tracking_key
+            @untracked ? '__untracked__' : nil
+          end
+
+          private
+
+          def direct_write?
+            config.driver.respond_to?(:direct_write)
+          end
+
+          def direct_write
+            config.driver.direct_write(**direct_payload)
+          end
+
+          def direct_payload
+            { operation: :assert, key: key, at: @at, values: values, untracked: @untracked }
+          end
+
+          def buffered_write
             payload = {
               keys: config.granularities.map { |granularity| key_for(granularity: granularity) },
               values: values
@@ -38,12 +62,6 @@ module Trifle
             end
           end
 
-          def tracking_key
-            @untracked ? '__untracked__' : nil
-          end
-
-          private
-
           def localized_time(time)
             base_time = time.is_a?(Time) ? time : time.to_time
             config.tz.utc_to_local(base_time.getutc)

data/lib/trifle/stats/version.rb

@@ -2,6 +2,6 @@
 
 module Trifle
   module Stats
-    VERSION = '2.5.0'
+    VERSION = '2.7.0'
   end
 end

data/lib/trifle/stats.rb

@@ -99,3 +99,5 @@ module Trifle
     end
   end
 end
+
+require 'trifle/stats/driver/api'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trifle-stats
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Jozef Vaclavik
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-14 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -225,6 +225,7 @@ files:
 - lib/trifle/stats/designator/geometric.rb
 - lib/trifle/stats/designator/linear.rb
 - lib/trifle/stats/driver/README.md
+- lib/trifle/stats/driver/api.rb
 - lib/trifle/stats/driver/mongo.rb
 - lib/trifle/stats/driver/mysql.rb
 - lib/trifle/stats/driver/postgres.rb