closeyourit-ruby 0.9.4 → 0.10.2

data/lib/closeyourit/transport.rb

@@ -6,17 +6,22 @@ require "uri"
 require "timeout"
 
 module CloseYourIt
-  # Spedisce un payload a un path di ingest (errori → /events, metriche → /metrics) via HTTP POST
-  # con `Authorization: Bearer`. Mai solleva: ogni errore di rete è loggato e ingoiato.
+  # Sends a payload to an ingest path (errors → /events, metrics → /metrics) via HTTP POST
+  # with `Authorization: Bearer`. Never raises: every network error is logged and swallowed.
   class Transport
     OPEN_TIMEOUT = 2
     READ_TIMEOUT = 3
-    # Net::HTTP non segue i redirect: l'host canonico può rispondere 301 (es. apex → www).
-    # Ri-POSTiamo a Location preservando metodo + body, così l'evento non si perde in silenzio.
+    # Net::HTTP does not follow redirects: the canonical host may answer 301 (e.g. apex → www).
+    # We re-POST to Location keeping method + body, so the event is not silently lost.
     MAX_REDIRECTS = 2
 
-    # Un timeout di rete (apertura o lettura) è un fallimento d'invio speciale: lo isoliamo dai non-2xx
-    # e dagli altri errori di rete perché segnala tipicamente problemi di connettività (CYRB-12).
+    # Maximum duration of ONE send_event: open + read, repeated for every followed redirect. It is the
+    # cap the end-of-life drain must be able to wait for, otherwise it abandons a still healthy send
+    # (CYRB-24).
+    MAX_REQUEST_SECONDS = (OPEN_TIMEOUT + READ_TIMEOUT) * (MAX_REDIRECTS + 1)
+
+    # A network timeout (open or read) is a special send failure: we keep it apart from non-2xx and
+    # other network errors because it typically signals connectivity problems (CYRB-12).
     TIMEOUT_ERRORS = [ Net::OpenTimeout, Net::ReadTimeout, Timeout::Error ].freeze
 
     def initialize(configuration)
@@ -30,7 +35,7 @@ module CloseYourIt
         CloseYourIt.notify_diagnostic(:send, status: response.code.to_i)
       else
         CloseYourIt.stats.increment(:failed)
-        CloseYourIt.internal_logger.warn("CloseYourIt transport: HTTP #{response.code}#{error_detail(response)} su #{path}")
+        CloseYourIt.internal_logger.warn("CloseYourIt transport: HTTP #{response.code}#{error_detail(response)} on #{path}")
         CloseYourIt.notify_diagnostic(:drop, reason: :response, status: response.code.to_i)
       end
       response
@@ -75,8 +80,8 @@ module CloseYourIt
       http.read_timeout = READ_TIMEOUT
 
       request = Net::HTTP::Post.new(uri.request_uri)
-      # Il Bearer è un segreto d'ingest: non ri-inviarlo dopo un redirect verso un host diverso
-      # (o un downgrade https→http), per non consegnarlo a un endpoint non fidato.
+      # The Bearer is an ingest secret: do not resend it after a redirect to a different host
+      # (or an https→http downgrade), so it is never handed to an untrusted endpoint.
       request["Authorization"] = "Bearer #{@configuration.token}" if authorize
       request["Content-Type"] = "application/json"
       request["User-Agent"] = "closeyourit-ruby/#{VERSION}"
@@ -85,16 +90,16 @@ module CloseYourIt
       http.request(request)
     end
 
-    # Location può essere assoluto (https://www.…) o relativo (/api/…): risolvilo sull'URI corrente.
+    # Location may be absolute (https://www.…) or relative (/api/…): resolve it against the current URI.
     def redirect_uri(current, location)
       target = URI.parse(location)
       target.relative? ? current + target : target
     end
 
-    # Il Bearer va ri-inviato solo se il redirect resta sull'autorità dell'endpoint configurato:
-    # stesso host (o la sua variante www), stessa porta effettiva e senza downgrade https→http.
-    # La porta fa parte del confine di fiducia (CYRB-22): sullo stesso server una porta diversa è
-    # un servizio distinto, che non deve ricevere il segreto d'ingest.
+    # The Bearer is resent only if the redirect stays on the configured endpoint's authority:
+    # same host (or its www variant), same effective port and no https→http downgrade.
+    # The port is part of the trust boundary (CYRB-22): on the same server a different port is a
+    # separate service, which must not receive the ingest secret.
     def same_authority?(origin, target)
       return false if origin.scheme == "https" && target.scheme != "https"
       return false unless canonical_host(origin) == canonical_host(target)
@@ -102,21 +107,21 @@ module CloseYourIt
       origin.port == target.port || canonical_upgrade?(origin, target)
     end
 
-    # Un endpoint configurato in `http` che redirige a `https` resta fidato: la porta cambia solo
-    # perché cambia lo schema (80 → 443), non perché punti a un servizio su porta non standard.
+    # An endpoint configured as `http` that redirects to `https` stays trusted: the port changes only
+    # because the scheme changes (80 → 443), not because it points to a service on a non-standard port.
     def canonical_upgrade?(origin, target)
       origin.scheme == "http" && target.scheme == "https" &&
         origin.port == origin.default_port && target.port == target.default_port
     end
 
-    # Una porta esplicita pari alla default (`:443` su https) equivale a ometterla: `URI#port` la
-    # normalizza già, qui resta solo da neutralizzare la variante www dell'host canonico.
+    # An explicit port equal to the default (`:443` on https) is the same as omitting it: `URI#port`
+    # already normalizes it, only the www variant of the canonical host is left to neutralize here.
     def canonical_host(uri)
       uri.host.to_s.sub(/\Awww\./, "")
     end
 
-    # Estrae " R…: messaggio" dall'envelope d'errore del backend, così il dev vede il codice d'errore
-    # nel log diagnostico (non solo lo status HTTP). Silenzioso se il body non è l'envelope atteso.
+    # Extracts " R…: message" from the backend error envelope, so the dev sees the error code in the
+    # diagnostic log (not only the HTTP status). Silent if the body is not the expected envelope.
     def error_detail(response)
       body = JSON.parse(response.body.to_s)
       error = body["error"]

data/lib/closeyourit/usage_registry.rb

@@ -3,25 +3,26 @@
 require "concurrent"
 
 module CloseYourIt
-  # CYSK-29 — la telemetria d'uso: registra QUALI simboli girano davvero (route come
-  # `Controller#action`, job, chiavi custom letterali) e li flusha in una POST ogni
-  # `usage_flush_interval` secondi per processo. Sul percorso caldo: una lookup e un increment.
+  # CYSK-29 — usage telemetry: records WHICH symbols actually run (routes as `Controller#action`,
+  # jobs, literal custom keys) and flushes them in one POST every `usage_flush_interval` seconds per
+  # process. On the hot path: one lookup and one increment.
   #
-  # Le regole che rendono il sistema immune alle perdite:
-  # - i conteggi sono INDICATIVI, solo `last_seen_at` è portante: un flush perso costa una finestra
-  #   su un simbolo che si rivede subito dopo;
-  # - il registro SI SVUOTA a ogni flush: il tetto (`usage_max_symbols`) limita i simboli distinti
-  #   visti in una finestra — una grandezza legata al traffico, non alla dimensione del codice;
-  # - oltre il tetto il flush porta `truncated: true`, e lato scanner quel flag SQUALIFICA il kind;
-  # - nessun sampling, mai: un campionamento su una rotta chiamata 3 volte al mese fabbrica
-  #   esattamente il falso «mai vista» che il sistema esiste per evitare;
-  # - `route` è `Controller#action`, MAI l'URL: niente path, parametri, user, IP.
+  # The rules that make the system immune to losses:
+  # - counts are INDICATIVE, only `last_seen_at` is load-bearing: a lost flush costs one window on a
+  #   symbol that shows up again right after;
+  # - the registry is EMPTIED on every flush: the cap (`usage_max_symbols`) limits the distinct
+  #   symbols seen in one window — a quantity tied to traffic, not to code size;
+  # - beyond the cap the flush carries `truncated: true`, and on the scanner side that flag
+  #   DISQUALIFIES the kind;
+  # - no sampling, ever: sampling a route called 3 times a month fabricates exactly the false
+  #   "never seen" the system exists to avoid;
+  # - `route` is `Controller#action`, NEVER the URL: no path, parameters, user, IP.
   class UsageRegistry
-    # I simboli vengono da payload di framework o da stringhe letterali: il pattern è il contratto.
+    # Symbols come from framework payloads or literal strings: the pattern is the contract.
     SYMBOL_FORMAT = %r{\A[A-Za-z0-9_:#./-]{1,200}\z}
     KINDS = %w[route job custom].freeze
 
-    attr_reader :timer # esposto per i test (verifica dell'intervallo configurato)
+    attr_reader :timer # exposed for tests (checks the configured interval)
 
     def initialize(client:, configuration:)
       @client = client
@@ -61,8 +62,8 @@ module CloseYourIt
 
       @client.flush_usage(**payload)
     rescue StandardError => e
-      # Il flush gira sul thread timer: un errore non deve propagare nell'app né uccidere il
-      # TimerTask. La semantica portante è last_seen_at: una finestra persa non falsifica niente.
+      # The flush runs on the timer thread: an error must not propagate into the app nor kill the
+      # TimerTask. The load-bearing semantics is last_seen_at: a lost window falsifies nothing.
       CloseYourIt.internal_logger.error("CloseYourIt usage registry: #{e.class}: #{e.message}")
     end
 

data/lib/closeyourit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  VERSION = "0.9.4"
+  VERSION = "0.10.2"
 end