Skip to content

feat: add jobsctl recent jobs query#84

Merged
michaelmwu merged 5 commits intomainfrom
michaelmwu/jobsctl-recent-queries
Mar 2, 2026
Merged

feat: add jobsctl recent jobs query#84
michaelmwu merged 5 commits intomainfrom
michaelmwu/jobsctl-recent-queries

Conversation

@michaelmwu
Copy link
Copy Markdown
Member

@michaelmwu michaelmwu commented Mar 2, 2026

Description

Adds a new jobsctl recent command to query recent jobs with --minutes (default 60) and --limit (default 100).
Adds GET /jobs?minutes=<n>&limit=<n> on the worker backend with shared-secret auth, bounded inputs, and descending-order job metadata responses.
Introduces jobs listing support in five08.queue as list_jobs(...) and wires it to the API handler.
Updates docs and unit tests across worker CLI, backend API, and shared queue behavior so the feature is discoverable and covered.

Related Issue

None.

How Has This Been Tested?

Ran ./scripts/test.sh and ./scripts/lint.sh; both passed in this workspace.

Summary by CodeRabbit

Release Notes

  • New Features

    • Added recent CLI subcommand to query recent jobs with customizable time window (--minutes) and result limit (--limit).
    • Added GET /jobs API endpoint to fetch jobs created within a specified time window.
  • Documentation

    • Updated documentation with usage examples for the new recent jobs command and endpoint.
  • Tests

    • Added unit tests for the new CLI command and API endpoint.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 2, 2026

Warning

Rate limit exceeded

@michaelmwu has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 21 minutes and 5 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 5cfb90f and 6cd23c1.

📒 Files selected for processing (7)
  • README.md
  • apps/worker/README.md
  • apps/worker/src/five08/backend/api.py
  • apps/worker/src/five08/jobcli.py
  • packages/shared/src/five08/queue.py
  • tests/unit/test_backend_api.py
  • tests/unit/test_jobcli.py
📝 Walkthrough

Walkthrough

A new "recent jobs" feature is introduced, adding a GET /jobs API endpoint to retrieve jobs created within a specified time window, along with a "recent" CLI subcommand to query and display those jobs, backed by a database function and comprehensive test coverage.

Changes

Cohort / File(s) Summary
Documentation
README.md, apps/worker/README.md
Added documentation for new "recent jobs" CLI command and GET /jobs endpoint, including usage examples and sample API responses.
Backend API
apps/worker/src/five08/backend/api.py
Introduced /jobs GET endpoint handler that accepts minutes and limit parameters, queries recent jobs from the database, and returns JSON response with authorization checks.
CLI Tool
apps/worker/src/five08/jobcli.py
Added "recent" subcommand with --minutes and --limit options, validation helper for positive integers, and handler to query and display recent jobs; updated response/request signatures to support non-dict payloads.
Shared Library
packages/shared/src/five08/queue.py
Implemented list_jobs() function to query PostgreSQL for jobs created after a cutoff timestamp with configurable limit, returning mapped JobRecord objects.
Unit Tests
tests/unit/test_backend_api.py, tests/unit/test_jobcli.py
Added test coverage for jobs endpoint handler (verifying status and payload) and CLI recent command (validating HTTP parameters and request structure).

Sequence Diagram

sequenceDiagram
    actor User
    participant CLI as jobcli (CLI Tool)
    participant API as Backend API
    participant DB as PostgreSQL
    
    User->>CLI: jobsctl recent --minutes 90 --limit 25
    CLI->>CLI: Validate --minutes & --limit via _positive_int()
    CLI->>API: GET /jobs?minutes=90&limit=25<br/>(with X-API-Secret header)
    API->>API: Authorize request
    API->>DB: list_jobs(created_after=cutoff, limit=25)
    DB->>DB: Query jobs WHERE created_at >= cutoff<br/>ORDER BY created_at DESC LIMIT 25
    DB-->>API: JobRecord list
    API-->>CLI: JSON response with job records
    CLI->>CLI: Pretty-print JSON payload
    CLI-->>User: Display recent jobs (exit 0)
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A hop through time, we now can see—
Recent jobs retrieved with glee!
With minutes counted, limits set,
The /jobs endpoint's no regret!
Query, fetch, and display with flair,
Recent work tracked through the air! 🌙

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 72.73% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title 'feat: add jobsctl recent jobs query' directly and accurately summarizes the main change—adding a new CLI command to query recent jobs. The title is concise and clearly communicates the primary feature addition.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch michaelmwu/jobsctl-recent-queries

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

🧹 Nitpick comments (2)
apps/worker/README.md (1)

133-163: Minor: Grammar nit flagged by static analysis.

Line 138: "look back window" should use a hyphen as "look-back window" for compound adjective.

📝 Optional grammar fix
-  - `minutes` (integer, default: `60`, minimum: `1`): look back window size.
+  - `minutes` (integer, default: `60`, minimum: `1`): look-back window size.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@apps/worker/README.md` around lines 133 - 163, In the GET
/jobs?minutes=<minutes>&limit=<limit> API docs paragraph, change the phrase
"look back window size." to the hyphenated compound adjective "look-back window
size." so the description of the `minutes` query param reads "look-back window
size."; locate the text under the "GET /jobs?minutes=<minutes>&limit=<limit>"
heading in the README and update the sentence describing the `minutes` parameter
accordingly.
apps/worker/src/five08/backend/api.py (1)

664-694: Consider adding an upper bound on the minutes parameter.

The minutes parameter only has a lower bound (ge=1), allowing queries for arbitrarily old data (e.g., minutes=525600 for a year). While the limit=1000 caps row count, an unbounded time window could still impact query performance on large tables if the created_at index scan is expensive.

♻️ Optional: Add upper bound to minutes parameter
 async def jobs_handler(
     request: Request,
-    minutes: int = Query(default=60, ge=1),
+    minutes: int = Query(default=60, ge=1, le=10080),  # max 7 days
     limit: int = Query(default=100, ge=1, le=1000),
 ) -> JSONResponse:
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@apps/worker/src/five08/backend/api.py` around lines 664 - 694, The
jobs_handler currently allows an unbounded minutes parameter which can cause
expensive queries; add an upper bound to the minutes Query (e.g., change
minutes: int = Query(default=60, ge=1, le=MAX_MINUTES)) or validate minutes at
the start of jobs_handler and return a 400 if it exceeds a configured max;
introduce a named constant (e.g., MAX_MINUTES or settings.MAX_JOB_LOOKBACK) and
reference it in the Query or validation so callers and reviewers can see the
limit and it can be adjusted centrally.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@apps/worker/README.md`:
- Around line 133-163: In the GET /jobs?minutes=<minutes>&limit=<limit> API docs
paragraph, change the phrase "look back window size." to the hyphenated compound
adjective "look-back window size." so the description of the `minutes` query
param reads "look-back window size."; locate the text under the "GET
/jobs?minutes=<minutes>&limit=<limit>" heading in the README and update the
sentence describing the `minutes` parameter accordingly.

In `@apps/worker/src/five08/backend/api.py`:
- Around line 664-694: The jobs_handler currently allows an unbounded minutes
parameter which can cause expensive queries; add an upper bound to the minutes
Query (e.g., change minutes: int = Query(default=60, ge=1, le=MAX_MINUTES)) or
validate minutes at the start of jobs_handler and return a 400 if it exceeds a
configured max; introduce a named constant (e.g., MAX_MINUTES or
settings.MAX_JOB_LOOKBACK) and reference it in the Query or validation so
callers and reviewers can see the limit and it can be adjusted centrally.

ℹ️ Review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e2c0f57 and 5cfb90f.

📒 Files selected for processing (7)
  • README.md
  • apps/worker/README.md
  • apps/worker/src/five08/backend/api.py
  • apps/worker/src/five08/jobcli.py
  • packages/shared/src/five08/queue.py
  • tests/unit/test_backend_api.py
  • tests/unit/test_jobcli.py

* feat: require id_type for mark-id-verified

* docs: move slash command docs to linked command reference

* docs: add consolidated Discord bot documentation file

* docs: remove obsolete kimai slash commands

* Handle optional id_type for mark-id-verified compatibility
* add rerun endpoint and jobsctl CLI

* Fix rerun payload validation and stabilize jobsctl tests
* fix: confirm ID verification overwrite before update

* fix: require overwrite confirmation for single field conflicts
@michaelmwu michaelmwu force-pushed the michaelmwu/jobsctl-recent-queries branch from 5cfb90f to 6fa3ff8 Compare March 2, 2026 15:29
Resolve merge conflict in README.md: keep expanded env var reference
from this branch and retain DEVELOPMENT.md link added on main.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@michaelmwu michaelmwu merged commit 98af4e1 into main Mar 2, 2026
5 checks passed
@michaelmwu michaelmwu deleted the michaelmwu/jobsctl-recent-queries branch March 2, 2026 15:50
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.

1 participant