Skip to content

Scale media collection concurrency with available resources#11

Merged
fabmnt merged 2 commits into
mainfrom
perf/resource-aware-collection-concurrency
Jul 18, 2026
Merged

Scale media collection concurrency with available resources#11
fabmnt merged 2 commits into
mainfrom
perf/resource-aware-collection-concurrency

Conversation

@fabmnt

@fabmnt fabmnt commented Jul 18, 2026

Copy link
Copy Markdown
Owner

Summary

  • add a project-local railway-cli agent skill with current, safety-focused Railway workflows
  • replace the worker's hard-coded single-collection concurrency with bounded CPU/memory-based sizing
  • process up to four collections concurrently on the current 8 vCPU / 8 GiB Railway backend
  • add a validated COLLECTION_CONCURRENCY override (1-8) for explicit tuning
  • document why retention remains safe: maintenance is serialized independently from collection processing

Why

The worker used concurrency: 1 because collection completion triggers storage retention. The collection path itself is already safe to parallelize:

  • each collection has an atomic database claim and lease
  • each processing attempt writes to a UUID-scoped directory
  • post-collection maintenance shares one in-process promise, so quota enforcement does not overlap
  • maintenance task versioning preserves a retention request queued while maintenance is already running

Railway CLI inspection of the production backend service showed:

  • 8 vCPU limit
  • 8 GiB memory limit
  • 0.54 vCPU peak over the last 24 hours
  • 1.18 GiB memory peak over the last 24 hours
  • one healthy replica and about 89 MB used on its 5 GB volume

Automatic sizing budgets two CPU threads and 1.5 GiB per collection, reserves 1.5 GiB for the co-located API/worker overhead, and caps concurrency at four. This resolves to four on the current Railway allocation and remains conservative on smaller containers.

Validation

  • pnpm lint
  • pnpm typecheck
  • pnpm build
  • Prettier check for changed supported files
  • git diff --check

docker compose config --quiet could not run because Docker is not installed in the current WSL environment; the Compose YAML passed Prettier validation.

Summary by CodeRabbit

  • New Features

    • Collection processing can now run concurrently, with automatic sizing based on CPU availability and constrained memory.
    • Added an optional COLLECTION_CONCURRENCY override, capped at 8.
    • Updated worker concurrency to use the computed concurrency (or the override when set).
  • Documentation

    • Updated deployment and local development guidance to reflect resource-aware concurrency behavior and independent retention/quota decisions.
    • Added Railway CLI usage documentation and configuration guidance for COLLECTION_CONCURRENCY (including the commented example).

Copilot AI review requested due to automatic review settings July 18, 2026 03:12
@railway-app
railway-app Bot temporarily deployed to impartial-energy / media-scraper-pr-11 July 18, 2026 03:13 Destroyed
@coderabbitai

coderabbitai Bot commented Jul 18, 2026

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 83d1d792-c41c-4b54-9f6e-f76e404c9634

📥 Commits

Reviewing files that changed from the base of the PR and between 3cf7b0b and 7e3eaa8.

📒 Files selected for processing (1)
  • .pi/skills/railway-cli/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • .pi/skills/railway-cli/SKILL.md

📝 Walkthrough

Walkthrough

Changes

Collection concurrency

Layer / File(s) Summary
Concurrency configuration and environment wiring
packages/config/src/index.ts, docker-compose.yml
Adds bounded optional validation for COLLECTION_CONCURRENCY and passes it to the worker container.
Runtime concurrency selection
apps/worker/src/index.ts
Computes CPU/memory-based concurrency, supports overrides, logs the source, and configures BullMQ.
Configuration guidance
.env.example, README.md
Documents automatic sizing, explicit overrides, and concurrent collection behavior.

Railway CLI workflow documentation

Layer / File(s) Summary
Railway CLI operating guidance
.pi/skills/railway-cli/SKILL.md
Adds scoped authentication, inspection, deployment, variable, infrastructure, tuning, and completion-reporting procedures.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WorkerConfig
  participant WorkerEntrypoint
  participant BullMQWorker
  WorkerConfig->>WorkerEntrypoint: provide COLLECTION_CONCURRENCY
  WorkerEntrypoint->>WorkerEntrypoint: derive CPU and memory-based concurrency
  WorkerEntrypoint->>BullMQWorker: configure collectionConcurrency
Loading

Possibly related PRs

Poem

I’m a rabbit tuning workers with care,
Counting CPU and memory in the air.
Eight carrots high is the cap we know,
Or set your own pace when you need it to go.
Collections now hop side by side—
While Railway notes keep each step supplied.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: dynamically scaling collection concurrency based on available resources.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch perf/resource-aware-collection-concurrency

Comment @coderabbitai help to get the list of available commands.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR increases the worker’s throughput by replacing a hard-coded single-collection BullMQ concurrency with a bounded, resource-aware default, while keeping storage retention serialized to avoid quota-decision overlap.

Changes:

  • Adds COLLECTION_CONCURRENCY to worker config with validation (optional; max 8).
  • Implements automatic worker concurrency sizing using container CPU/memory (capped at 4) and logs the chosen source.
  • Updates local/dev documentation and Compose/env examples to describe and expose the new override.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file
File Description
README.md Documents concurrent collection processing and clarifies retention serialization + sizing rationale.
packages/config/src/index.ts Adds validated COLLECTION_CONCURRENCY support to the worker environment schema.
docker-compose.yml Wires COLLECTION_CONCURRENCY into the worker service environment.
apps/worker/src/index.ts Computes and applies dynamic BullMQ worker concurrency based on CPU/memory (with override).
.pi/skills/railway-cli/SKILL.md Adds a project-local Railway CLI skill documenting safe operational workflows.
.env.example Documents the COLLECTION_CONCURRENCY override behavior for local setups.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.pi/skills/railway-cli/SKILL.md:
- Line 75: Update the inspection workflow command list to remove the raw JSON
variable listing from railway variable inspection, or replace it with a
key-only/redacted variant that cannot expose secret values. Preserve the
remaining generic inspection commands unchanged.
- Around line 90-96: Update the detached deployment workflow to capture the
deploymentId returned by railway up --detach --json and poll that specific
deployment directly, rather than selecting the newest result from railway
deployment list. Preserve the existing SUCCESS, FAILED, CRASHED, and other-state
reporting behavior for the tracked deployment.
- Around line 110-120: Update the provisioning guidance in the Services and
infrastructure section so railway add --service and railway add --database
require explicit user confirmation immediately before execution. Preserve the
existing instruction to inspect services first, and make clear that confirmation
is required to prevent unintended billed resources.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1ec087ca-3632-4377-8bba-b831ff74838e

📥 Commits

Reviewing files that changed from the base of the PR and between 790ee89 and 3cf7b0b.

📒 Files selected for processing (6)
  • .env.example
  • .pi/skills/railway-cli/SKILL.md
  • README.md
  • apps/worker/src/index.ts
  • docker-compose.yml
  • packages/config/src/index.ts

Comment thread .pi/skills/railway-cli/SKILL.md Outdated
Comment thread .pi/skills/railway-cli/SKILL.md Outdated
Comment thread .pi/skills/railway-cli/SKILL.md Outdated
@railway-app
railway-app Bot temporarily deployed to impartial-energy / media-scraper-pr-11 July 18, 2026 03:20 Destroyed
@railway-app

railway-app Bot commented Jul 18, 2026

Copy link
Copy Markdown

🚅 Deployed to the media-scraper-pr-11 environment in impartial-energy

Service Status Web Updated (UTC)
backend ✅ Success (View Logs) Web Jul 18, 2026 at 3:20 am
web ✅ Success (View Logs) Web Jul 18, 2026 at 3:20 am

@fabmnt
fabmnt merged commit d6878d4 into main Jul 18, 2026
3 checks passed
@fabmnt
fabmnt deleted the perf/resource-aware-collection-concurrency branch July 18, 2026 03:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants