chronos-ruby 0.1.0.pre.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 203d12bad0a790efdb2bb89bcbc9127f067fc096507c6345aefbbdc7ed13966c
+  data.tar.gz: 2fb4eb956405f099b10b3e6f9429800446faf24127bc35b3e092dce316c1edb2
+SHA512:
+  metadata.gz: 30be78abcf064b43e2f395c7493f5e7b037c8f1b8ac8dd5a4fc507ea86eae7c89fe0104f094551e3e92d68b4dded9010949fc9a79e43c01880217266bcebaa9c
+  data.tar.gz: 907ba0c16f873d533714b1a06448e857e7a4c8bfcf2b524a150bf0906244d507cf5e6b961d3db219bf63da6d3bf6933474e25360f3715d3e93b0e7d07929db21

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes are documented here. The project follows Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0.pre.2] - 2026-07-19
+
+### Changed
+
+- prepared the second public pre-release;
+- aligned the release tag with the RubyGems version format.
+
+## [0.1.0.pre.1] - 2026-07-19
+
+### Added
+
+- framework-independent `Chronos` facade;
+- validated immutable configuration;
+- exception, backtrace, cause, and runtime normalization;
+- versioned JSON exception envelope;
+- bounded serialization and payload size enforcement;
+- Net::HTTP transport with TLS, proxy, timeout, and response classification;
+- fixed-capacity asynchronous queue and lazy worker pool;
+- flush, timed shutdown, double-close, and fork handling;
+- Ruby 2.2.10–2.6 legacy test matrix;
+- contract, unit, integration, failure, and performance test assets.
+
+### Known limitations
+
+- no advanced sensitive-data sanitizer;
+- no retry or backlog;
+- no automatic Rack, Rails, or job integration;
+- no performance monitoring or deploy events.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at antoniojeferson96@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Open an issue before adding a public API, runtime dependency, framework integration, or protocol field.
+
+For each change:
+
+1. keep syntax compatible with Ruby 2.2.10 on the 0.x line;
+2. write or update unit, contract, and integration tests;
+3. keep Core independent of frameworks and HTTP;
+4. bound every queue, buffer, collection, timeout, and retry;
+5. document public classes with responsibility, motivation, limits, collaborators, thread safety, compatibility, examples, errors, and performance where relevant;
+6. update module documentation, ADRs, README, and changelog;
+7. do not declare compatibility before its dedicated CI gate succeeds.
+
+Run:
+
+```bash
+bin/setup
+bundle _1.17.3_ exec rake
+ruby script/verify_docs
+```
+
+Do not include credentials, personal data, production payloads, or proprietary third-party code in issues, fixtures, or pull requests.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Antonio Jefferson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,251 @@
+# Chronos Ruby
+
+Chronos Ruby is the framework-independent client for sending Ruby application errors to Chronos. Version 0.1 is the legacy foundation: it captures exceptions manually, builds a bounded JSON event, and delivers it synchronously or through a fixed-size asynchronous queue.
+
+## What the gem collects
+
+For each exception, version 0.1 can collect:
+
+- exception class, message, structured backtrace, and chained causes;
+- timestamp, severity, tags, and an optional fingerprint;
+- application-supplied context, parameters, session, and user fields;
+- Ruby version, engine, platform, process ID, opaque thread ID, and hostname;
+- application version, environment, and service name.
+
+See [Data collected](docs/data-collected.md) for the complete field table.
+
+## What is not collected by default
+
+Chronos Ruby does not inspect environment variables, request bodies, cookies, HTTP headers, source code, database contents, or installed gems. Version 0.1 does not automatically sanitize application-supplied context. Do not pass passwords, tokens, cookies, personal documents, or payment data. Advanced redaction belongs to version 0.2.
+
+## Supported Ruby and Rails versions
+
+Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.1 is independent of Rails and does not yet declare support for any Rails integration. All supported combinations must pass dedicated CI before being listed as supported.
+
+See [Compatibility](docs/compatibility.md).
+
+## Plain Ruby installation
+
+The current public build is a pre-release. Add its exact version to the application's `Gemfile`:
+
+```ruby
+gem "chronos-ruby", "0.1.0.pre.2"
+```
+
+Install with a Bundler version compatible with the application. For the oldest supported runtime:
+
+```bash
+gem install bundler -v 1.17.3
+bundle _1.17.3_ install
+```
+
+Without Bundler:
+
+```bash
+gem install chronos-ruby --pre
+```
+
+## Rails installation
+
+Rails automatic integration is not part of version 0.1. A Rails application may use the plain Ruby API, but this does not constitute declared Rails support. Rack and Rails adapters are planned for later legacy releases.
+
+## Minimum configuration
+
+`project_id`, `project_key`, and an HTTPS `host` are required while the agent is enabled:
+
+```ruby
+require "chronos"
+
+Chronos.configure do |config|
+  config.project_id = ENV["CHRONOS_PROJECT_ID"]
+  config.project_key = ENV["CHRONOS_PROJECT_KEY"]
+  config.host = "https://chronos.example.com"
+  config.environment = ENV["APP_ENV"] || "production"
+  config.service_name = "billing"
+  config.app_version = ENV["APP_VERSION"]
+end
+```
+
+HTTPS verification is enabled by default. HTTP requires explicitly setting `ssl_verify = false` and should only be used with a local test server.
+
+## Automatic capture
+
+Automatic exception capture is not implemented in version 0.1. Applications must call `Chronos.notify` or `Chronos.notify_sync`. Rack, Rails, and worker hooks will be introduced only after their compatibility suites exist.
+
+## Manual capture
+
+Asynchronous capture is recommended for application code:
+
+```ruby
+begin
+  perform_payment
+rescue StandardError => error
+  Chronos.notify(error, :tags => ["payment"])
+  raise
+end
+```
+
+Synchronous capture waits for the HTTP result and is useful in scripts or controlled shutdown paths:
+
+```ruby
+delivered = Chronos.notify_sync(RuntimeError.new("import failed"))
+```
+
+Both methods return `false` instead of allowing an internal agent error to escape.
+
+## User context
+
+User data is opt-in and must contain only values your application is allowed to send:
+
+```ruby
+Chronos.notify(error, :user => {"id" => "customer-42", "role" => "operator"})
+```
+
+Avoid names, e-mail addresses, documents, tokens, and other personal or secret fields in version 0.1.
+
+## Breadcrumbs
+
+Breadcrumbs are not implemented in version 0.1.
+
+## Filters and LGPD
+
+Version 0.1 limits depth, collection length, string length, backtrace length, and total payload size. It does not provide the recursive sensitive-data filter planned for version 0.2. Review all supplied context before production use. See [Privacy and LGPD](docs/privacy-lgpd.md).
+
+## Ignore rules
+
+Entire environments can be ignored:
+
+```ruby
+Chronos.configure do |config|
+  # required options omitted
+  config.ignored_environments = ["development", "test"]
+end
+```
+
+Exception-specific ignore rules are not available in version 0.1.
+
+## Performance monitoring
+
+Request, SQL, cache, job, and external HTTP monitoring are not implemented in version 0.1. The local capture pipeline is bounded and HTTP delivery runs outside the caller thread when `Chronos.notify` is used.
+
+## Sidekiq and Active Job
+
+Sidekiq and Active Job integrations are not implemented in version 0.1. Calling the manual API from a job is possible, but automatic capture and deduplication are not yet guaranteed.
+
+## Deploy tracking
+
+Deploy notifications are not implemented in version 0.1. `app_version` may be included in exception events for release correlation.
+
+## Asynchronous queue
+
+The queue has a fixed capacity and drops the newest event when full. Worker threads are created lazily after the first accepted event. The default capacity is 100 events with one worker.
+
+```mermaid
+flowchart LR
+  E[Exception] --> N[Notice builder]
+  N --> S[Bounded serializer]
+  S --> Q[Bounded queue]
+  Q --> W[Fixed worker pool]
+  W --> H[Net::HTTP transport]
+```
+
+Use `Chronos.flush(timeout)` to wait for accepted events and `Chronos.close(timeout)` during shutdown. Workers are recreated after a process fork.
+
+## Retry and backlog
+
+Version 0.1 classifies network failures, `429`, `4xx`, and `5xx`, but does not retry or persist events. Failed deliveries are dropped after the attempt. Bounded retry and backlog are planned for version 0.3.
+
+## How it works internally
+
+The code follows hexagonal boundaries:
+
+- `Chronos::Core` contains immutable notices and normalization;
+- `Chronos::Application` coordinates capture;
+- `Chronos::Ports` defines delivery behavior;
+- `Chronos::Adapters` implements Net::HTTP delivery;
+- `Chronos::Internal` owns bounded queueing, workers, and defensive logging.
+
+The core has no dependency on Rails, Rack, Sidekiq, or ActiveSupport. See [Architecture](docs/architecture.md).
+
+## Environment-specific configuration
+
+Configuration values are explicit; the gem never scans the process environment. Read only the variables your application chooses:
+
+```ruby
+Chronos.configure do |config|
+  config.project_id = ENV["CHRONOS_PROJECT_ID"]
+  config.project_key = ENV["CHRONOS_PROJECT_KEY"]
+  config.host = ENV["CHRONOS_HOST"]
+  config.environment = ENV["APP_ENV"] || "production"
+  config.enabled = ENV["CHRONOS_ENABLED"] != "false"
+  config.queue_size = 100
+  config.workers = 1
+  config.timeout = 5.0
+  config.open_timeout = 2.0
+end
+```
+
+All options are documented in [Configuration](docs/configuration.md).
+
+## Troubleshooting
+
+Configuration errors are raised during `Chronos.configure`. Capture and delivery errors are contained and optionally reported to the configured logger. Verify credentials, HTTPS certificates, timeouts, and `Chronos.flush` results. See [Troubleshooting](docs/troubleshooting.md).
+
+## Benchmark
+
+Run the version 0.1 benchmarks with:
+
+```bash
+bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
+bundle _1.17.3_ exec ruby benchmarks/serialization.rb
+bundle _1.17.3_ exec ruby benchmarks/queue.rb
+```
+
+Results depend on runtime, hardware, and payload. No performance comparison is claimed until repeatable measurements are published.
+
+## Migration from Airbrake
+
+An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.1 does not claim API compatibility or automatic replacement.
+
+## Local development
+
+Clone the repository, install Bundler 1.17.3, and run setup:
+
+```bash
+gem install bundler -v 1.17.3
+bin/setup
+```
+
+Open an interactive console:
+
+```bash
+bin/console
+```
+
+Install the current source locally:
+
+```bash
+bundle _1.17.3_ exec rake install
+```
+
+## Tests
+
+Run the complete suite on the current Ruby:
+
+```bash
+bundle _1.17.3_ exec rake
+```
+
+The legacy CI matrix covers Ruby 2.2.10, 2.3.8, 2.4.10, 2.5.9, and 2.6.10. Network integration tests use a local fake HTTP server.
+
+## Contributing
+
+Open an issue before introducing a new public API or dependency. Every public class requires YARD documentation, tests, module documentation, and compatibility evidence. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+Never include credentials in event context or logs. Report vulnerabilities privately according to [SECURITY.md](SECURITY.md). Ruby 2.2 through 2.6 are end-of-life; Chronos provides technical compatibility, not runtime security maintenance.
+
+## License
+
+Chronos Ruby is distributed under the terms of the MIT License. See [LICENSE.txt](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,9 @@
+# Security policy
+
+Do not report vulnerabilities in a public issue. Send a private report to `antoniojeferson96@gmail.com` with the affected version, impact, reproduction steps, and any suggested mitigation.
+
+Never include live project keys, customer payloads, personal data, or production credentials in a report.
+
+The Chronos 0.x line provides technical compatibility with end-of-life Ruby versions. It cannot provide security maintenance for the Ruby runtime, OpenSSL, operating system, Rails, or other dependencies used by the host application.
+
+Security fixes in the agent will be assessed for backporting to maintained Chronos version lines. No response-time commitment is made before a formal security process is published.

data/contracts/event-v1.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/event-v1.schema.json",
+  "title": "Chronos event envelope v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "event_id",
+    "event_type",
+    "occurred_at",
+    "sent_at",
+    "project_key",
+    "environment",
+    "service",
+    "runtime",
+    "context",
+    "payload"
+  ],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "event_id": {"type": "string", "minLength": 1},
+    "event_type": {"enum": ["exception"]},
+    "occurred_at": {"type": "string"},
+    "sent_at": {"type": "string"},
+    "project_key": {"type": "string", "minLength": 1},
+    "environment": {"type": "string"},
+    "service": {
+      "type": "object",
+      "required": ["name", "version", "instance_id"],
+      "properties": {
+        "name": {"type": ["string", "null"]},
+        "version": {"type": ["string", "null"]},
+        "instance_id": {"type": ["string", "null"]}
+      }
+    },
+    "runtime": {"type": "object"},
+    "context": {"type": "object"},
+    "payload": {
+      "type": "object",
+      "required": ["exception", "severity"],
+      "properties": {
+        "exception": {
+          "type": "object",
+          "required": ["class", "message", "backtrace", "causes"]
+        },
+        "severity": {"type": "string"}
+      }
+    }
+  }
+}

data/docs/adr/ADR-001-core-and-integrations.md

@@ -0,0 +1,25 @@
+# ADR-001 — Separate core and integrations
+
+## Status
+
+Accepted.
+
+## Context
+
+Chronos must support plain Ruby and several incompatible framework generations without coupling event modeling to Rails or worker libraries.
+
+## Decision
+
+Use hexagonal boundaries: Core, Application, Ports, Adapters, and Internal. The public `Chronos` module remains a thin facade.
+
+## Alternatives
+
+A single notifier class was rejected because framework hooks, HTTP, and domain rules would evolve together. A plugin framework was rejected for version 0.1 because it would add abstractions without current integrations.
+
+## Positive consequences
+
+Core tests run without Rails, transports are replaceable, and legacy integrations can use feature detection.
+
+## Negative consequences
+
+The repository contains more small files and explicit composition code.

data/docs/adr/ADR-002-version-lines.md

@@ -0,0 +1,25 @@
+# ADR-002 — Compatibility through version lines
+
+## Status
+
+Accepted.
+
+## Context
+
+One dependency and syntax baseline cannot safely serve Ruby 2.2 and modern fiber-aware Ruby releases indefinitely.
+
+## Decision
+
+Use 0.x for Ruby 2.2.10–2.6, 1.x for transitional Ruby 2.7–3.2, and 2.x for Ruby 3.3 and newer. Support is declared only after the required CI and integration evidence exists.
+
+## Alternatives
+
+A single ever-growing major line was rejected because modern dependencies would eventually break installation in legacy applications.
+
+## Positive consequences
+
+Legacy applications receive conservative fixes while modern code can adopt runtime capabilities safely.
+
+## Negative consequences
+
+Critical protocol and security fixes may need backports across maintained lines.

data/docs/adr/ADR-003-net-http-legacy-transport.md

@@ -0,0 +1,25 @@
+# ADR-003 — Net::HTTP for legacy transport
+
+## Status
+
+Accepted.
+
+## Context
+
+An HTTP client dependency can abandon old Ruby versions or conflict with the host application bundle.
+
+## Decision
+
+Implement the version 0.x transport with `Net::HTTP`, explicit timeouts, TLS verification, optional proxy support, no automatic redirects, and result classification.
+
+## Alternatives
+
+Faraday and other clients were deferred because they add dependencies and version-resolution risk.
+
+## Positive consequences
+
+The agent has no runtime gem dependency and controls legacy behavior directly.
+
+## Negative consequences
+
+Connection pooling and middleware conveniences require explicit implementation later.

data/docs/adr/ADR-004-bounded-queue.md

@@ -0,0 +1,25 @@
+# ADR-004 — Bounded queue and drop policy
+
+## Status
+
+Accepted.
+
+## Context
+
+An unavailable endpoint or event burst must not grow host application memory indefinitely.
+
+## Decision
+
+Use a fixed-capacity in-memory queue. Producers never wait for space. When full, the newest event is dropped and counted. Worker count is fixed and threads start lazily.
+
+## Alternatives
+
+An unbounded queue and one thread per event were rejected. Blocking producers was rejected because telemetry must not stall application work.
+
+## Positive consequences
+
+Memory and thread growth are bounded and overload behavior is measurable.
+
+## Negative consequences
+
+Events may be dropped under sustained pressure.

data/docs/adr/ADR-005-sanitize-before-backlog.md

@@ -0,0 +1,25 @@
+# ADR-005 — Sanitize before backlog
+
+## Status
+
+Proposed for versions 0.2 and 0.3; no backlog exists in 0.1.
+
+## Context
+
+Persisting unsanitized events would increase privacy and credential exposure risk.
+
+## Decision
+
+Any future retry or persistent backlog must receive only data that has already passed sanitization and structural limits.
+
+## Alternatives
+
+Sanitizing only during final delivery is rejected because backlog data would remain exposed.
+
+## Positive consequences
+
+Retry storage cannot contain raw pre-filter payloads by design.
+
+## Negative consequences
+
+Filtering decisions cannot be changed retroactively for already accepted events.

data/docs/adr/ADR-006-versioned-event-contract.md

@@ -0,0 +1,25 @@
+# ADR-006 — Versioned event contract
+
+## Status
+
+Accepted.
+
+## Context
+
+Clients and the Chronos SaaS evolve independently and require a testable compatibility boundary.
+
+## Decision
+
+All events use a common envelope with `schema_version`. Version 0.1 emits exception events using schema `1.0`, UUID event IDs, ISO-8601 UTC timestamps, JSON primitives, and an idempotency header.
+
+## Alternatives
+
+Sending Ruby object serialization or an unversioned free-form hash was rejected.
+
+## Positive consequences
+
+Payloads can be validated, replayed safely, and evolved with backward compatibility.
+
+## Negative consequences
+
+Schema evolution requires explicit server and client coordination.

data/docs/architecture.md

@@ -0,0 +1,31 @@
+# Architecture
+
+Chronos Ruby 0.1 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
+
+```mermaid
+flowchart TB
+  Facade[Chronos facade] --> Application[Application / CaptureException]
+  Application --> Core[Core / Notice and serialization]
+  Application --> Ports[Ports / Transport contract]
+  Ports --> Adapter[Adapters / NetHttpTransport]
+  Application --> Internal[Internal / BoundedQueue and WorkerPool]
+  Internal --> Ports
+```
+
+## Boundaries
+
+- Domain/Core owns immutable event values and Ruby normalization.
+- Application owns use-case ordering and failure containment.
+- Ports define behavior expected from infrastructure.
+- Adapters contain Net::HTTP and TLS behavior.
+- Internal contains private concurrency and diagnostic mechanisms.
+
+The `Chronos` module is a thin facade. Rails, Rack, ActiveSupport, Sidekiq, and job libraries must not be required by the core.
+
+## Capture flow
+
+An exception becomes an immutable notice, then a bounded JSON envelope. Asynchronous capture inserts the serialized event into a bounded queue. A fixed worker sends it through the transport. Synchronous capture bypasses the queue.
+
+## Failure policy
+
+Explicit invalid configuration raises `Chronos::ConfigurationError`. Capture, serialization, logger, worker, TLS, network, and HTTP failures do not escape into the host application. They produce `false`, a transport result, or a bounded logger diagnostic.