liteguard 0.2.20260314 → 0.3.20260315

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f23791b98c679f5725e164d63279b9b4b9119c997a00239fdf7b2cdef79cc75
-  data.tar.gz: e8747b2ff6273315d5ec0eb9c8e420f4ff7543b0c40e358cf45eeec39e6f2854
+  metadata.gz: c5639cf9bfedbd8a5410e0d33addc0c5d2668ef4048fd53562698af2d23b47d7
+  data.tar.gz: 4f5160aae968869e16db59db5b687b9e3e314073cb48557c54c34e78dad80fb7
 SHA512:
-  metadata.gz: e9555143d0eaaa6776dc6081efb0303a5fee8957a27bbc804f9464325debb5fd16d87e0cf91815194a043081128038becfee9620c453d00fbcaaab287fa60136
-  data.tar.gz: afd0bfa6f21f799c2d5e04452c5711f7cce44af23ec8c8f061274f3c98edc362e0ec05ac0737b5b382898482649476c53dd7ad269b3266155536752c8c7bacdd
+  metadata.gz: 3da6c94e15e9638769a7a24608293ec1804d6267d99def6087614c4660808970a092aa4002c796717778fa638c6e7dcb63d0cbfc62fc5526fc5ad2c70f7b4f85
+  data.tar.gz: eb8674f429b011190e951feed26376f88f5f27baa68331823eb841d8c282b9de89ab068e2dc15b7b7d8ffada8e89fd1133fd939b214262b57d5bde77c208270e

data/README.md

@@ -23,7 +23,7 @@ Requires Ruby 3.1+.
 require "liteguard"
 
 client = Liteguard::Client.new(
-  "pckid-...",
+  "pct-...",
   environment: "production"
 )
 client.start
@@ -39,7 +39,7 @@ client.shutdown
 
 ## Primary API
 
-- `Liteguard::Client.new(project_client_key_id, **options)` creates a client.
+- `Liteguard::Client.new(project_client_token, **options)` creates a client.
 - `client.start` fetches the initial bundle and starts refresh and flush workers.
 - `client.create_scope(**properties)` creates an immutable scope.
 - `scope.open?(name, **options)` evaluates locally.
@@ -62,5 +62,5 @@ make test-ruby
 
 ## License
 
-Apache 2.0 — see [LICENSE](https://github.com/liteguard/liteguard/blob/main/LICENSE).
+Apache 2.0 see [LICENSE](https://github.com/liteguard/liteguard/blob/main/LICENSE).
 

data/lib/liteguard/client.rb

@@ -31,7 +31,7 @@ module Liteguard
     #
     # The client remains idle until {#start} is called.
     #
-    # @param project_client_key_id [String] project client key identifier from
+    # @param project_client_token [String] project client token from
     #   the Liteguard control plane
     # @param opts [Hash] initialization options
     # @option opts [String, nil] :environment environment slug to send with API
@@ -51,8 +51,8 @@ module Liteguard
     # @option opts [Boolean] :quiet suppress warning output when `true`
     # @option opts [Boolean] :disable_measurement disable telemetry measurements
     # @return [void]
-    def initialize(project_client_key_id, opts = {})
-      @project_client_key_id = project_client_key_id
+    def initialize(project_client_token, opts = {})
+      @project_client_token = project_client_token
       @environment = opts.fetch(:environment, "").to_s
       @fallback = opts.fetch(:fallback, false)
       @refresh_rate = normalize_positive_option(opts[:refresh_rate_seconds], DEFAULT_REFRESH_RATE)
@@ -83,7 +83,6 @@ module Liteguard
 
       @signal_buffer = []
       @dropped_signals_pending = 0
-      @reported_unadopted_guards = {}
       @pending_unadopted_guards = {}
       @rate_limit_state = {}
     end
@@ -460,21 +459,23 @@ module Liteguard
     # Signals
     # ---------------------------------------------------------------------
 
-    # Flush all buffered telemetry and unadopted guard reports.
+    # Flush all buffered telemetry and unadopted guard observations.
     #
     # @return [void]
     def flush_signals
-      batch, unadopted_guard_names = @monitor.synchronize do
+      batch, unadopted_observations = @monitor.synchronize do
         buffered = @signal_buffer.dup
         @signal_buffer.clear
-        names = @pending_unadopted_guards.keys.sort
+        observations = @pending_unadopted_guards.keys.sort.map do |name|
+          finalize_unadopted_observation(@pending_unadopted_guards[name])
+        end
         @pending_unadopted_guards.clear
-        [buffered, names]
+        [buffered, observations]
       end
-      return if batch.empty? && unadopted_guard_names.empty?
+      return if batch.empty? && unadopted_observations.empty?
 
       flush_signal_batch(batch) unless batch.empty?
-      flush_unadopted_guards(unadopted_guard_names) unless unadopted_guard_names.empty?
+      flush_unadopted_guards(unadopted_observations) unless unadopted_observations.empty?
     end
 
     # Upload a batch of buffered signals.
@@ -486,7 +487,7 @@ module Liteguard
     # @return [void]
     def flush_signal_batch(batch)
       payload = JSON.generate(
-        projectClientKeyId: @project_client_key_id,
+        projectClientToken: @project_client_token,
         environment: @environment,
         signals: batch.map do |signal|
           {
@@ -518,21 +519,29 @@ module Liteguard
       end
     end
 
-    # Upload unadopted guard names discovered during evaluation.
+    # Upload unadopted guard observations discovered during evaluation.
     #
-    # @param unadopted_guard_names [Array<String>] guard names to report
+    # @param unadopted_observations [Array<UnadoptedGuardObservation>] observations to report
     # @return [void]
-    def flush_unadopted_guards(unadopted_guard_names)
+    def flush_unadopted_guards(unadopted_observations)
       payload = JSON.generate(
-        projectClientKeyId: @project_client_key_id,
+        projectClientToken: @project_client_token,
         environment: @environment,
-        guardNames: unadopted_guard_names
+        observations: unadopted_observations.map do |observation|
+          {
+            guardName: observation.guard_name,
+            firstSeenMs: observation.first_seen_ms,
+            lastSeenMs: observation.last_seen_ms,
+            checkCount: observation.check_count,
+            estimatedChecksPerMinute: observation.estimated_checks_per_minute,
+          }
+        end
       )
       post_json("/api/v1/unadopted-guards", payload)
     rescue => e
       log "[liteguard] unadopted guard flush failed: #{e}"
       @monitor.synchronize do
-        unadopted_guard_names.each { |name| @pending_unadopted_guards[name] = true }
+        unadopted_observations.each { |observation| merge_pending_unadopted_observation(observation) }
       end
     end
 
@@ -746,7 +755,7 @@ module Liteguard
       protected_context = bundle.protected_context ? copy_protected_context(bundle.protected_context) : nil
 
       payload = {
-        projectClientKeyId: @project_client_key_id,
+        projectClientToken: @project_client_token,
         environment: @environment
       }
       if protected_context
@@ -758,7 +767,7 @@ module Liteguard
 
       uri = URI("#{@backend_url}/api/v1/guards")
       req = Net::HTTP::Post.new(uri)
-      req["Authorization"] = "Bearer #{@project_client_key_id}"
+      req["Authorization"] = "Bearer #{@project_client_token}"
       req["Content-Type"] = "application/json"
       req["If-None-Match"] = bundle.etag unless bundle.etag.to_s.empty?
       req.body = JSON.generate(payload)
@@ -864,7 +873,7 @@ module Liteguard
     def post_json(path, payload)
       uri = URI("#{@backend_url}#{path}")
       req = Net::HTTP::Post.new(uri)
-      req["Authorization"] = "Bearer #{@project_client_key_id}"
+      req["Authorization"] = "Bearer #{@project_client_token}"
       req["Content-Type"] = "application/json"
       req["X-Liteguard-Environment"] = @environment unless @environment.empty?
       req.body = payload
@@ -1163,19 +1172,64 @@ module Liteguard
       payload
     end
 
-    # Track an unadopted guard so it can be reported once.
+    # Track an unadopted guard so it can be reported with observation metadata.
     #
     # @param name [String] guard name to record
     # @return [void]
     def record_unadopted_guard(name)
       @monitor.synchronize do
-        return if @reported_unadopted_guards[name]
+        now = (Time.now.to_f * 1000).to_i
+        observation = @pending_unadopted_guards[name]
+        if observation
+          @pending_unadopted_guards[name] = observation.with(
+            last_seen_ms: now,
+            check_count: observation.check_count + 1
+          )
+        else
+          @pending_unadopted_guards[name] = UnadoptedGuardObservation.new(
+            guard_name: name,
+            first_seen_ms: now,
+            last_seen_ms: now,
+            check_count: 1,
+            estimated_checks_per_minute: 0.0
+          )
+        end
+      end
+    end
 
-        @reported_unadopted_guards[name] = true
-        @pending_unadopted_guards[name] = true
+    def finalize_unadopted_observation(observation)
+      observation.with(
+        estimated_checks_per_minute: estimate_checks_per_minute(
+          observation.first_seen_ms,
+          observation.last_seen_ms,
+          observation.check_count
+        )
+      )
+    end
+
+    def merge_pending_unadopted_observation(observation)
+      existing = @pending_unadopted_guards[observation.guard_name]
+      if existing
+        @pending_unadopted_guards[observation.guard_name] = existing.with(
+          first_seen_ms: [existing.first_seen_ms, observation.first_seen_ms].min,
+          last_seen_ms: [existing.last_seen_ms, observation.last_seen_ms].max,
+          check_count: existing.check_count + observation.check_count,
+          estimated_checks_per_minute: 0.0
+        )
+      else
+        @pending_unadopted_guards[observation.guard_name] = observation.with(
+          estimated_checks_per_minute: 0.0
+        )
       end
     end
 
+    def estimate_checks_per_minute(first_seen_ms, last_seen_ms, check_count)
+      return 0.0 if check_count.to_i <= 0
+
+      window_ms = [last_seen_ms - first_seen_ms, 1000].max
+      (check_count * 60_000.0) / window_ms
+    end
+
     # Capture a stable callsite identifier outside of Liteguard internals.
     #
     # @return [String] `path:line` identifier, or `unknown`
@@ -1258,11 +1312,15 @@ module Liteguard
       end
     end
 
-    # Return pending unadopted-guard names for tests.
+    # Return pending unadopted-guard observations for tests.
     #
-    # @return [Array<String>] pending unadopted guard names
+    # @return [Array<UnadoptedGuardObservation>] pending unadopted guard observations
     def pending_unadopted_guards_for_testing
-      @monitor.synchronize { @pending_unadopted_guards.keys.sort }
+      @monitor.synchronize do
+        @pending_unadopted_guards.keys.sort.map do |name|
+          finalize_unadopted_observation(@pending_unadopted_guards[name])
+        end
+      end
     end
 
     # Return the number of cached bundles for tests.

data/lib/liteguard/evaluation.rb

@@ -1,5 +1,5 @@
 module Liteguard
-  # Local rule evaluation engine — all evaluation is done without network calls.
+  # Local rule evaluation engine. All evaluation is done without network calls.
   module Evaluation
     # Evaluate a guard against a property hash.
     #

data/lib/liteguard/types.rb

@@ -1,7 +1,7 @@
-# Code generated by tools/src/proto-codegen.ts — DO NOT EDIT.
+# Code generated by tools/src/proto-codegen.ts DO NOT EDIT.
 # Source of truth: proto/liteguard.proto  Run: make proto
 
-# Data-plane types — generated from proto/liteguard.proto.
+# Data-plane types. Generated from proto/liteguard.proto.
 module Liteguard
 
   OPERATORS = %i[equals not_equals in not_in regex gt gte lt lte].freeze
@@ -37,7 +37,7 @@ module Liteguard
 
   # GetGuardsRequest (mirrors proto message).
   GetGuardsRequest = Data.define(
-    :project_client_key_id,
+    :project_client_token,
     :environment,
     :protected_context
   )
@@ -102,11 +102,20 @@ module Liteguard
     :measurement
   )
 
+  # UnadoptedGuardObservation (mirrors proto message).
+  UnadoptedGuardObservation = Data.define(
+    :guard_name,
+    :first_seen_ms,
+    :last_seen_ms,
+    :check_count,
+    :estimated_checks_per_minute
+  )
+
   # SendUnadoptedGuardsRequest (mirrors proto message).
   SendUnadoptedGuardsRequest = Data.define(
-    :project_client_key_id,
+    :project_client_token,
     :environment,
-    :guard_names
+    :observations
   )
 
   # SendUnadoptedGuardsResponse (mirrors proto message).
@@ -116,7 +125,7 @@ module Liteguard
 
   # Default values for {Liteguard::Client} initialization options.
   CLIENT_OPTION_DEFAULTS = {
-    project_client_key_id:  nil,
+    project_client_token:   nil,
     environment:            nil,
     fallback:               false,
     refresh_rate_seconds:   30,

data/lib/liteguard.rb

@@ -7,7 +7,7 @@ require_relative "liteguard/client"
 #
 #   require 'liteguard'
 #
-#   client = Liteguard::Client.new('pckid-...', environment: 'production')
+#   client = Liteguard::Client.new('pct-...', environment: 'production')
 #   client.start
 #   scope = client.create_scope(user_id: 'user-123', plan: 'pro')
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: liteguard
 version: !ruby/object:Gem::Version
-  version: 0.2.20260314
+  version: 0.3.20260315
 platform: ruby
 authors:
 - Liteguard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-15 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -40,7 +40,7 @@ dependencies:
         version: '3.23'
 description: Liteguard gives you feature guards, observability, and CVE auto-disable
   in one gem. Guards are evaluated entirely in-process against rules fetched once
-  at startup — every open? check is sub-millisecond with no network round-trip.
+  at startup. Every open? check is sub-millisecond with no network round-trip.
 email:
 executables: []
 extensions: []