activejob-temporal 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd1d95e1a889d180f79f3d2eeb2ec31d5c5b4338776cc41656b9077cbdd96da7
-  data.tar.gz: 66c78d747c740b51e0320ca131d480160ef37af78496cf77632c68bfc1b7915d
+  metadata.gz: 8a0aefb6003d5c49d08c531d80ac7ce5ff82ee038a81aee31d3c5f0d2d438f61
+  data.tar.gz: c0f3f46a2e57f35a0c05290d129d9905f64c6dbe9be30371e79f99d0905d3cd0
 SHA512:
-  metadata.gz: 2d87ef5a4b8a31de5990da5a9effd53bc7e9b1c4a59ad185d632a31d73b23c9b566358785ae5e469a3c96322b092b7b46b6387dd08d9b245d044da102690eafd
-  data.tar.gz: b51db2d419c9301934241e0bb4b308ea7b398ecf3ba964cc8f7c82e73d75dfbf829839e79d1a42347dfe539b3d2cf289a74dff1516299806b0874face1e13449
+  metadata.gz: 16bd26f8f58993b6c60b21a16f0216fe928eb4ad341aad19483fe77cd3f2c2c21ecf67695969df2137fa2b4953a8f984ff1d446696ce9691e33e0431fa3af177
+  data.tar.gz: b06bd6d8ca772947228dacfe065e5582156d15fccc8501bff3ec14e8f3c18454d22d2b28c09cb1a59788462997067eaa9f12204ac265fd10273468cd653346ef

data/AGENTS.md

@@ -0,0 +1 @@
+./CLAUDE.md

data/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-06
+
+### Added
+- Bearer-token authentication: `api_key` (sent as the `Authorization: Bearer` header) and `api_key_file`, read through the same hardened path as TLS files — for example a projected Kubernetes ServiceAccount token. `api_key_watch` watches the token file and applies rotated tokens to the live connection via the new `ActiveJob::Temporal.refresh_api_key!` (no reconnect); enqueue-side processes using a rotating token file should call `refresh_api_key!` on their own schedule. `api_key` is redacted from `Configuration#inspect`. Caution: the Temporal SDK enables TLS when an API key is set and `tls` is nil — set `tls = false` explicitly for plaintext in-cluster servers (see the worker setup guide).
+- Custom activity hosting: `worker_activities` registers additional activity classes (or class names) on the worker — for example activities invoked by workflows owned by another service, where only the activity name and JSON payloads travel over the wire. `worker_activejob_workloads = false` turns off the built-in ActiveJob workflows and activities for activities-only workers. Entries must be `Temporalio::Activity::Definition` subclasses; anything else fails worker startup with a `WorkerRegistrationError`.
+- `graceful_shutdown_period` is passed to the Temporal worker, so a shutting-down worker lets running activities finish before their tasks are cancelled instead of cancelling them immediately.
+- Configuration validation for the new attributes: `api_key_file` must be a readable regular file, `api_key_watch` requires `api_key_file`, disabling `worker_activejob_workloads` requires `worker_activities`, and `graceful_shutdown_period` must be >= 0.
+
+### Changed
+- Allow temporalio 1.5 and 1.6 (dependency constraint is now `>= 1.4.0, < 1.7`); both added to the SDK contract-test matrix. Note for consumers upgrading within the range: temporalio 1.6 enables gzip gRPC transport compression by default — opt out with `grpc_compression` if an intermediary cannot handle it.
+
+## [0.2.0] - 2026-08-06
+
+### Security
+- Reject payload-declared serializers not permitted by the configured `payload_serializer`, closing a `Marshal.load` code-execution path from attacker-supplied workflow input.
+- Derive the AES-GCM payload encryption context from the activity context instead of the payload, so captured ciphertexts cannot be replayed into other workflows or namespaces.
+- Reject legacy V1 (context-unbound) encrypted payloads by default; `allow_legacy_encrypted_payloads` opts back in during migration.
+- Validate values interpolated into Temporal visibility queries with a strict allowlist, preventing query-structure injection through job IDs and class names in cancel/inspect APIs.
+- Redact encryption keys and TLS settings from `Configuration#inspect`.
+- Cap request line length and header count and enforce a whole-request deadline in the health check and metrics HTTP servers.
+
+### Fixed
+- Retry certificate reloads after a failure so cert+key rotation pairs written within the debounce window are not dropped.
+- Accept symlinked TLS certificate paths (resolved via `File.realpath`), unblocking Kubernetes secret volume mounts.
+- Rescue `SystemCallError` in health check and metrics accept loops so errors like `EMFILE` no longer kill the listener silently.
+- Reject overlapping worker pool health check and metrics port ranges at validation time instead of crash-looping the colliding child.
+- Raise the documented `TemporalConnectionError` from client connect failures.
+- Surface dead letter queue query failures instead of silently dropping entries, and fetch entries concurrently.
+
 <!-- github_changelog_generator:start -->
 
 **Implemented enhancements:**

data/CLAUDE.md

@@ -0,0 +1,274 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**activejob-temporal** is a Ruby gem providing a production-ready ActiveJob adapter backed by Temporal's durable execution engine. It enables Rails applications to leverage Temporal's reliability, observability, and fault-tolerance while maintaining full ActiveJob compatibility.
+
+### Architecture Pattern
+
+The gem uses a **Temporal Workflow + Activity** pattern:
+1. **Adapter** (`lib/activejob/temporal/adapter.rb`): Translates ActiveJob's `perform_later` calls into Temporal workflow starts
+2. **Workflow** (`lib/activejob/temporal/workflows/aj_workflow.rb`): Orchestrates job execution with durable timers for scheduled jobs
+3. **Activity** (`lib/activejob/temporal/activities/aj_runner_activity.rb`): Executes the actual job logic
+4. **Supporting Services**: Payload serialization, retry mapping, search attributes, logging
+
+Each enqueued job becomes a workflow execution, with optional activities for the job logic and retry handling managed through Temporal's native mechanisms.
+
+## Key Components
+
+- **Configuration** (`lib/activejob/temporal.rb`): DSL-style setup with automatic validation (validates at end of configure block)
+- **Client** (`lib/activejob/temporal/client.rb`): Temporal gRPC client builder with target/namespace/credentials handling
+- **RetryMapper** (`lib/activejob/temporal/retry_mapper.rb`): Introspects ActiveJob `retry_on`/`discard_on` and converts to Temporal retry policies
+- **Payload** (`lib/activejob/temporal/payload.rb`): Job argument serialization/deserialization with size validation
+- **SearchAttributes** (`lib/activejob/temporal/search_attributes.rb`): Generates metadata for Temporal UI filtering
+- **Logger** (`lib/activejob/temporal/logger.rb`): Structured logging with context awareness
+- **Cancel** (`lib/activejob/temporal/cancel.rb`): Job cancellation API and workflow termination logic
+
+## Development Commands
+
+### Testing
+
+```bash
+# Run all tests (unit + integration)
+bundle exec rake spec
+
+# Unit tests only (faster feedback)
+bundle exec rake spec:unit
+
+# Integration tests only (requires Temporal running)
+bundle exec rake spec:integration
+
+# Run a specific test file
+bundle exec ruby -Ilib -Ispec spec/unit/adapter_spec.rb
+
+# Run a specific test example
+bundle exec ruby -Ilib -Ispec spec/unit/adapter_spec.rb --name /example name/
+```
+
+Tests are organized by type in `spec/unit/` and `spec/integration/`. Integration tests use real Temporal workers to validate end-to-end behavior. See `spec/support/temporal_test_server.rb` for test Temporal setup.
+
+### Linting and Code Quality
+
+```bash
+# Check for Rubocop violations
+bundle exec rake rubocop
+
+# Auto-fix violations
+bundle exec rake rubocop:autocorrect
+
+# JSON output for CI
+./tools/lint.sh
+```
+
+All files must have `# frozen_string_literal: true` at the top.
+
+### Documentation
+
+```bash
+# Generate YARD documentation
+bundle exec rake yard
+```
+
+Use YARD annotations extensively:
+- `@param` for arguments (include types)
+- `@return` for return values
+- `@raise` for exceptions
+- `@example` for usage patterns
+- `@note` for important caveats
+- `@api private` for internal methods
+
+### Temporal Setup (Local Development)
+
+```bash
+# Start Temporal server, UI, and PostgreSQL
+docker-compose up
+
+# Temporal UI: http://localhost:8080
+# Server: localhost:7233
+```
+
+### Running a Worker
+
+The `temporal-worker` executable uses smart Rails auto-detection:
+
+#### From a Rails Application
+
+```bash
+cd your-rails-app
+ACTIVEJOB_TEMPORAL_TARGET=localhost:7233 \
+ACTIVEJOB_TEMPORAL_NAMESPACE=default \
+ACTIVEJOB_TEMPORAL_TASK_QUEUE=default \
+bundle exec temporal-worker
+```
+
+The worker auto-detects the Rails app in the current directory and loads your environment.
+
+#### From the Gem Directory (Development)
+
+```bash
+ACTIVEJOB_TEMPORAL_TARGET=localhost:7233 \
+ACTIVEJOB_TEMPORAL_NAMESPACE=default \
+ACTIVEJOB_TEMPORAL_TASK_QUEUE=default \
+bin/temporal-worker
+```
+
+When run from the gem directory (not a Rails app), it works without Rails.
+
+#### Specifying a Custom Path
+
+If you need to run the worker from a different directory, use `RAILS_ROOT`:
+
+```bash
+RAILS_ROOT=/path/to/app \
+bundle exec temporal-worker
+```
+
+The worker will load the Rails app at that path.
+
+#### Performance Tuning
+
+Control concurrency for different environments:
+
+```bash
+# High-throughput production
+ACTIVEJOB_TEMPORAL_TARGET=temporal.prod:7233 \
+ACTIVEJOB_TEMPORAL_NAMESPACE=production \
+ACTIVEJOB_TEMPORAL_TASK_QUEUE=jobs \
+ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_ACTIVITIES=500 \
+ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS=50 \
+bundle exec temporal-worker
+
+# Low-resource development
+ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_ACTIVITIES=20 \
+ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS=2 \
+bundle exec temporal-worker
+```
+
+See `docs/worker_setup.md` for detailed tuning guidance.
+
+### Build and Release
+
+```bash
+# Build gem
+gem build activejob-temporal.gemspec
+
+# Full validation (Rubocop + tests)
+bundle exec rake default
+```
+
+## Code Conventions
+
+### Structure and Style
+
+- **Module composition** over inheritance; use modules for mixins
+- **Explicit requires** at top of files
+- **Frozen string literals** on every file: `# frozen_string_literal: true`
+- **Proper namespacing**: `ActiveJob::Temporal::Workflows::AjWorkflow`
+- **Visibility markers**: Use `private` or `private_class_method` explicitly
+
+### Naming
+
+- **Classes**: PascalCase (`TemporalAdapter`, `AjWorkflow`)
+- **Methods**: snake_case (`build_workflow_id`, `from_job`)
+- **Constants**: SCREAMING_SNAKE_CASE (used sparingly)
+
+### Error Handling
+
+The gem uses a custom exception hierarchy rooted at `ActiveJob::Temporal::Error`:
+- `ConfigurationError`: Invalid or missing configuration
+- `WorkflowNotFoundError`: Job not found in Temporal
+- `TemporalConnectionError`: Network or server issues
+
+**Pattern**: Always provide human-readable error messages with context. Wrap external Temporal errors into domain-specific exceptions for cleaner error handling in client code.
+
+### Configuration Pattern
+
+Configuration uses a DSL pattern with **automatic validation**:
+
+```ruby
+ActiveJob::Temporal.configure do |config|
+  config.target = "localhost:7233"
+  config.namespace = "default"
+  # Additional settings...
+  # Validation happens automatically at the end of this block!
+end
+```
+
+Configuration is automatically validated at the end of the `configure` block. By default validation failures raise `ConfigurationError` immediately. `config.validation_level` can downgrade failures to warnings with `:warn` or skip validation with `:none`. You can also manually validate by calling `ActiveJob::Temporal.config.validate!` if you modify the config directly outside the block.
+
+Environment variables with defaults are used for sensitive values (e.g., `ENV.fetch("TEMPORAL_TARGET", default)`).
+
+## Testing Patterns
+
+### Test Organization
+
+- **Unit tests** (`spec/unit/`): Isolated component tests with mocking/stubbing
+- **Integration tests** (`spec/integration/`): End-to-end tests using real Temporal
+- **Fixtures** (`spec/fixtures/sample_jobs.rb`): Sample job classes with various retry/discard configurations
+
+### SimpleCov and Coverage
+
+Tests use SimpleCov with branch coverage enabled. Target coverage is ≥90%. Run tests to generate coverage reports.
+
+### Test Isolation
+
+Use `around` hooks and shared contexts to reset state between tests. Integration tests manage Temporal workers within test lifecycle.
+
+### Common Patterns
+
+- Mock Temporal client responses for unit tests
+- Use real workers in integration tests
+- Test both success and failure paths (retries, discards)
+- Validate error messages and exception types
+
+## Workflow Implementation Notes
+
+**Determinism**: Workflows must be deterministic—no I/O, randomness, or system time calls in the main workflow logic. Use activities for these operations.
+
+**Durable Timers**: For scheduled jobs, workflows use Temporal's durable sleep mechanism. This persists across workflow replays and cluster restarts.
+
+**RetryPolicy Mapping**: The `RetryMapper` introspects ActiveJob's `retry_on` and `discard_on` declarations and converts them to Temporal native retry policies. Understand this mapping when debugging job retries.
+
+## Git Commit Conventions
+
+Use **Conventional Commits** format: `<type>(<scope>): <description>`
+
+**Types**:
+- `feat`: New features
+- `fix`: Bug fixes
+- `docs`: Documentation changes
+- `chore`: Maintenance, configuration, tooling
+- `test`: Test additions/updates
+- `refactor`: Code structure improvements (avoid in this project—prefer feature/fix commits)
+
+**Common scopes**:
+- `config`: Configuration handling
+- `payload`: Job serialization
+- `cancel`: Cancellation logic
+- `adapter`: ActiveJob adapter
+- `workflows`: Workflow implementations
+- `activities`: Activity implementations
+- `docs`: Documentation
+- `yard`: Inline documentation
+- `tasks`: Task tracking/checklists
+- `ci`: CI/CD pipeline
+- `release`: Release processes
+
+**Example**: `feat(config): add worker performance tuning options`
+
+Keep commits small and focused. A feature might consist of several commits: implementation, tests, documentation.
+
+## Architecture Decision Records
+
+See `docs/adr/` for recorded architectural decisions and rationale behind major design choices.
+
+## Additional Resources
+
+- **Configuration Reference**: `docs/configuration_reference.md`
+- **Comparison Guide**: `docs/comparison.md` (choosing the right ActiveJob backend)
+- **Worker Setup**: `docs/worker_setup.md`
+- **Release Process**: `docs/publishing.md`, `docs/release_checklist.md`
+- **README**: Comprehensive user guide and quick start
+- **Temporal Docs**: https://docs.temporal.io/ (for workflow/activity patterns, API reference)

data/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+## Ruby Baseline
+
+Use Ruby 4.0.3 for local development and validation. The repository targets Ruby 4+ and does not require installing Ruby 3.
+
+See [Ruby Baseline](docs/ruby_baseline.md) for the source-of-truth files, CI coverage, and external tooling notes.
+
+Run validation commands through the Ruby 4 toolchain:
+
+```sh
+rvm 4.0.3 do bundle install
+rvm 4.0.3 do bundle exec rake spec:unit
+rvm 4.0.3 do bundle exec rubocop
+rvm 4.0.3 do bundle exec rake build
+```
+
+## Mutation Testing
+
+Mutation testing runs a scoped Mutant baseline against deterministic unit-level code:
+
+```sh
+rvm 4.0.3 do bundle exec rake mutation
+```
+
+The default subject list is intentionally small so the task stays fast and does not require a local Temporal server. Expand `.mutant.yml` as specs are hardened around additional code paths.
+
+Mutant 0.16 supports Ruby 4, but its parser dependency may warn about an older parser version. Treat new Ruby syntax parse failures as a Mutant tooling limitation and keep the repository runtime baseline on Ruby 4.
+
+## Dependency Updates
+
+Dependabot checks root Bundler dependencies weekly and opens up to five update pull requests at a time.
+
+Development dependency minor and patch updates are grouped into a single pull request. Review dependency pull requests like any other change: confirm CI passes, scan the changelog for breaking behavior, and keep major updates separate unless the dependency explicitly documents compatibility.
+
+## Code Quality Tracking
+
+Qlty, the successor to Code Climate Quality, reads the committed `.qlty/qlty.toml` analysis configuration.
+
+The current configuration focuses maintainability tracking on the library code and excludes generated or packaged artifacts. RuboCop findings are monitored in Qlty while the existing GitHub Actions lint job remains the blocking local validation path.
+
+Do not add a README maintainability badge until the repository has been added to Qlty and the generated project badge URL is available.
+
+## Changelog
+
+Generate release changelog updates from merged GitHub pull requests and closed issues:
+
+```sh
+CHANGELOG_GITHUB_TOKEN=... rvm 4.0.3 do bundle exec rake changelog:generate
+```
+
+The task also accepts `GITHUB_TOKEN` when `CHANGELOG_GITHUB_TOKEN` is not set. Review the generated `CHANGELOG.md` before committing release notes.
+
+Generated unreleased sections are rebuilt from GitHub issues and pull requests. Existing released sections stay in place so curated release notes are not lost.
+
+## Release Commits
+
+Release automation is not enabled yet.
+
+Use conventional commit prefixes where they describe the change:
+
+- `feat:` for user-visible features
+- `fix:` for bug fixes
+- `docs:` for documentation-only changes
+- `test:` for test-only changes
+- `ci:` for GitHub Actions or CI changes
+- `chore:` for maintenance that does not affect runtime behavior
+
+Do not rely on commit messages to publish a release until [Publishing](docs/publishing.md) says release automation is enabled.

data/README.md

@@ -18,11 +18,10 @@ Use a traditional ActiveJob backend when the work is short, simple, and does not
 ## Requirements
 
 - Ruby >= 4.0
-- Rails 8.1 through ActiveJob 8.1
+- Rails >= 7.2 through ActiveJob 8.x
 - Temporal cluster, either self-hosted or [Temporal Cloud](https://temporal.io/cloud)
 
-CI validates Ruby 4.0.0 and the latest Ruby 4.0 patch against Rails 8.1.
-Temporal Ruby SDK 1.4.x compatibility is contract-tested against 1.4.0 and the latest 1.4.x release.
+Temporal Ruby SDK 1.4.x compatibility is contract-tested against 1.4.0 and 1.4.1.
 
 ## Install
 
@@ -104,34 +103,36 @@ bundle exec temporal-worker
 
 Open Temporal UI and look for workflows named `ajwf:SendInvoiceJob:<job_id>`.
 
+`require "activejob/temporal"` loads the Rails adapter, enqueue path, schedules, lookup APIs, and shared configuration. Worker-only runtime code is loaded by `temporal-worker`; custom worker boot code should require `activejob/temporal/worker_runtime` before registering workflows or activities.
+
 ## Common Capabilities
 
 | Need | API | Detailed guide |
 | --- | --- | --- |
-| Delay a single job | `MyJob.set(wait: 5.minutes).perform_later(...)` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#scheduled-jobs) |
-| Register recurring cron work | `schedule cron: "0 2 * * *"` and `create_temporal_schedule` | [Recurring Jobs](https://github.com/schovi/activejob-temporal/blob/main/docs/recurring_jobs.md) |
-| Enqueue only when work exists | `perform_later_if(condition, *args)` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#conditional-enqueueing) |
-| Enqueue many prepared jobs | `ActiveJob::Temporal.enqueue_batch(jobs)` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#bulk-enqueueing) |
-| Run sequential jobs in one workflow | `set(chain: [NextJob])` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#job-chaining) |
-| Start child ActiveJob workflows | `set(child_workflows: [ChildJob])` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#child-workflows) |
-| Call external Temporal activities or workflows | `ActiveJob::Temporal.activity(...)`, `ActiveJob::Temporal.workflow(...)` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#external-temporal-steps) |
-| Wait for separately enqueued jobs | `set(depends_on: parent_job)` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#job-dependencies) |
-| Map ActiveJob retries to Temporal | `retry_on`, `discard_on` | [Retry Policy Guide](https://github.com/schovi/activejob-temporal/blob/main/docs/retry_policies.md) |
-| Park exhausted failures | `config.dead_letter_queue = "failed_jobs"` | [Configuration Reference](https://github.com/schovi/activejob-temporal/blob/main/docs/configuration_reference.md#dead-letter-queue) |
-| Tune activity timeouts | `temporal_options start_to_close_timeout: ...` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#per-job-timeouts) |
-| Add throughput limits | `rate_limit 100, per: :second` | [Configuration Reference](https://github.com/schovi/activejob-temporal/blob/main/docs/configuration_reference.md#rate-limit-configuration) |
-| Cancel or inspect jobs | `cancel`, `cancel_all`, `status`, `running?` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#cancellation-and-status) |
-| Pause, resume, query, or update workflow state | `signal`, `query`, `update` | [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md#signals-queries-and-updates) |
-| Add runtime middleware | `config.add_middleware MiddlewareClass` | [Middleware](https://github.com/schovi/activejob-temporal/blob/main/docs/middleware.md) |
-| Expose Prometheus metrics | `config.observability.use :prometheus` | [Metrics Guide](https://github.com/schovi/activejob-temporal/blob/main/docs/metrics.md) |
-| Encrypt job payloads | `encrypt_payload = true` | [Configuration Reference](https://github.com/schovi/activejob-temporal/blob/main/docs/configuration_reference.md#payload-encryption) |
-| Store large payloads externally | `payload_storage_adapter = MyPayloadStorage.new` | [Configuration Reference](https://github.com/schovi/activejob-temporal/blob/main/docs/configuration_reference.md#payload-size-limits) |
+| Delay a single job | `MyJob.set(wait: 5.minutes).perform_later(...)` | [Usage Patterns](docs/usage_patterns.md#scheduled-jobs) |
+| Register recurring cron work | `temporal_schedule cron: "0 2 * * *"` and `create_temporal_schedule` | [Recurring Jobs](docs/recurring_jobs.md) |
+| Enqueue only when work exists | `perform_later_if(condition, *args)` | [Usage Patterns](docs/usage_patterns.md#conditional-enqueueing) |
+| Enqueue many prepared jobs | `ActiveJob::Temporal.enqueue_batch(jobs)` | [Usage Patterns](docs/usage_patterns.md#bulk-enqueueing) |
+| Run sequential jobs in one workflow | `set(chain: [NextJob])` | [Usage Patterns](docs/usage_patterns.md#job-chaining) |
+| Start child ActiveJob workflows | `set(child_workflows: [ChildJob])` | [Usage Patterns](docs/usage_patterns.md#child-workflows) |
+| Call external Temporal activities or workflows | `ActiveJob::Temporal.activity(...)`, `ActiveJob::Temporal.workflow(...)` | [Usage Patterns](docs/usage_patterns.md#external-temporal-steps) |
+| Wait for separately enqueued jobs | `set(depends_on: parent_job)` | [Usage Patterns](docs/usage_patterns.md#job-dependencies) |
+| Map ActiveJob retries to Temporal | `retry_on`, `discard_on` | [Retry Policy Guide](docs/retry_policies.md) |
+| Park exhausted failures | `config.dead_letter_queue = "failed_jobs"` | [Configuration Reference](docs/configuration_reference.md#dead-letter-queue) |
+| Tune activity timeouts | `temporal_options start_to_close_timeout: ...` | [Usage Patterns](docs/usage_patterns.md#per-job-timeouts) |
+| Add throughput limits | `rate_limit 100, per: :second` | [Configuration Reference](docs/configuration_reference.md#rate-limit-configuration) |
+| Cancel or inspect jobs | `cancel`, `cancel_all`, `status`, `running?` | [Usage Patterns](docs/usage_patterns.md#cancellation-and-status) |
+| Pause, resume, query, or update workflow state | `signal`, `query`, `update` | [Usage Patterns](docs/usage_patterns.md#signals-queries-and-updates) |
+| Add runtime middleware | `config.add_middleware MiddlewareClass` | [Middleware](docs/middleware.md) |
+| Expose Prometheus metrics | `config.observability.use :prometheus` | [Metrics Guide](docs/metrics.md) |
+| Encrypt job payloads | `encrypt_payload = true` | [Configuration Reference](docs/configuration_reference.md#payload-encryption) |
+| Store large payloads externally | `payload_storage_adapter = MyPayloadStorage.new` | [Configuration Reference](docs/configuration_reference.md#payload-size-limits) |
 
 Baseline behavior also includes transaction-aware enqueueing through ActiveJob, GlobalID-compatible argument serialization, structured JSON logs, searchable `set(tags:)` metadata, and JSON payloads with opt-in MessagePack or Marshal envelopes.
 
 ## Configuration
 
-The full configuration surface lives in [Configuration Reference](https://github.com/schovi/activejob-temporal/blob/main/docs/configuration_reference.md). The machine-readable schema is [docs/config_schema.yaml](https://github.com/schovi/activejob-temporal/blob/main/docs/config_schema.yaml).
+The full configuration surface lives in [Configuration Reference](docs/configuration_reference.md). The machine-readable schema is [docs/config_schema.yaml](docs/config_schema.yaml).
 
 The most common settings are:
 
@@ -148,23 +149,23 @@ ActiveJob::Temporal.configure do |config|
 end
 ```
 
-Workers can also read environment variables such as `ACTIVEJOB_TEMPORAL_TARGET`, `ACTIVEJOB_TEMPORAL_NAMESPACE`, `ACTIVEJOB_TEMPORAL_TASK_QUEUE`, `ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_ACTIVITIES`, `ACTIVEJOB_TEMPORAL_METRICS_PORT`, and TLS certificate settings. See [Worker Setup](https://github.com/schovi/activejob-temporal/blob/main/docs/worker_setup.md) for the worker-focused list.
+Workers can also read environment variables such as `ACTIVEJOB_TEMPORAL_TARGET`, `ACTIVEJOB_TEMPORAL_NAMESPACE`, `ACTIVEJOB_TEMPORAL_TASK_QUEUE`, `ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_ACTIVITIES`, `ACTIVEJOB_TEMPORAL_METRICS_PORT`, and TLS certificate settings. See [Worker Setup](docs/worker_setup.md) for the worker-focused list.
 
 ## Documentation
 
-Start with [docs/README.md](https://github.com/schovi/activejob-temporal/blob/main/docs/README.md) for the complete documentation map.
+Start with [docs/README.md](docs/README.md) for the complete documentation map.
 
 High-use guides:
 
-- [Usage Patterns](https://github.com/schovi/activejob-temporal/blob/main/docs/usage_patterns.md)
-- [Configuration Reference](https://github.com/schovi/activejob-temporal/blob/main/docs/configuration_reference.md)
-- [Worker Setup](https://github.com/schovi/activejob-temporal/blob/main/docs/worker_setup.md)
-- [Troubleshooting](https://github.com/schovi/activejob-temporal/blob/main/docs/troubleshooting.md)
-- [Performance Tuning](https://github.com/schovi/activejob-temporal/blob/main/docs/performance_tuning.md)
-- [Comparison Guide](https://github.com/schovi/activejob-temporal/blob/main/docs/comparison.md)
-- [Security](https://github.com/schovi/activejob-temporal/blob/main/docs/security.md)
+- [Usage Patterns](docs/usage_patterns.md)
+- [Configuration Reference](docs/configuration_reference.md)
+- [Worker Setup](docs/worker_setup.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Performance Tuning](docs/performance_tuning.md)
+- [Comparison Guide](docs/comparison.md)
+- [Security](docs/security.md)
 
-See [examples/basic_rails_app](https://github.com/schovi/activejob-temporal/tree/main/examples/basic_rails_app) for a Docker Compose Rails app with Temporal, Temporal UI, search attribute setup, workers, seeded GlobalID records, and tests.
+See [examples/basic_rails_app](examples/basic_rails_app/) for a Docker Compose Rails app with Temporal, Temporal UI, search attribute setup, workers, seeded GlobalID records, and tests.
 
 ## Contributing
 
@@ -195,4 +196,4 @@ MIT. See [LICENSE](LICENSE).
 
 This project follows [Semantic Versioning](https://semver.org/). See [CHANGELOG](CHANGELOG.md) for release history.
 
-Current development version: 0.1.0. Release commits must be tagged before publishing to RubyGems.
+Current version: 0.1.0

data/activejob-temporal.gemspec

@@ -19,16 +19,13 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 4.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/main"
-  spec.metadata["documentation_uri"] = "#{spec.homepage}/blob/main/docs/README.md"
+  spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.start_with?("spec/", "docs/", "examples/", "tmp/", "tools/", "gemfiles/", ".codemachine/", ".github/") ||
-        f == "CLAUDE.md" ||
-        f == "CONTRIBUTING.md" ||
+      f.start_with?("spec/", "docs/", "examples/", "tmp/", "tools/", ".codemachine/", ".github/") ||
         f.match?(%r{^(\.|docker-compose\.yml|coverage/|Gemfile|Rakefile)})
     end
   end
@@ -36,23 +33,22 @@ Gem::Specification.new do |spec|
   spec.executables = ["temporal-worker"]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activejob", ">= 8.1", "< 9"
-  spec.add_dependency "activemodel", ">= 8.1", "< 9"
+  spec.add_dependency "activejob", ">= 7.2", "< 9"
+  spec.add_dependency "activemodel", ">= 7.2", "< 9"
   spec.add_dependency "concurrent-ruby", "~> 1.1"
   spec.add_dependency "globalid", ">= 0.3"
-  spec.add_dependency "listen", "~> 3.9"
-  spec.add_dependency "temporalio", ">= 1.4.0", "< 1.5"
+  spec.add_dependency "temporalio", ">= 1.4.0", "< 1.7"
 
   spec.add_development_dependency "benchmark-ips", "~> 2.14"
-  spec.add_development_dependency "bundler-audit", "~> 0.9"
   spec.add_development_dependency "github_changelog_generator", "~> 1.18"
+  spec.add_development_dependency "listen", "~> 3.9"
+  spec.add_development_dependency "minitest", ">= 5.11", "< 7"
   spec.add_development_dependency "msgpack", "~> 1.8"
-  spec.add_development_dependency "mutant-rspec", "~> 0.16"
+  spec.add_development_dependency "mutant-minitest", "~> 0.16"
   spec.add_development_dependency "prometheus-client", "~> 4.2"
   spec.add_development_dependency "rake", "~> 13.2"
-  spec.add_development_dependency "rspec", "~> 3.12"
   spec.add_development_dependency "rubocop", "~> 1.50"
   spec.add_development_dependency "simplecov", "~> 0.22"
   spec.add_development_dependency "simplecov-lcov", "~> 0.9"
-  spec.add_development_dependency "yard", "~> 0.9", ">= 0.9.42"
+  spec.add_development_dependency "yard", "~> 0.9"
 end