jenkinsci / jenkinsci/lockable-resources-plugin

Add resource status + statistics APIs

Open
#1,043 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Java
Stars
99
Forks
205
Avg merge
2d 13h
Merged PRs (30d)
8

Description

### Summary
Introduce stable APIs for resource status and basic utilization statistics.

### Motivation
Operators and UIs need answers like:
- is resource X free?
- who locked it and for how long?
- average lock duration / queue wait time

Today this requires scraping UI tables and does not have a stable schema.

### Proposed API (Java)
- `getStatus(String resourceName)` -> state (FREE/LOCKED/RESERVED/QUEUED), owner/build, timestamps
- `getStats(String resourceName)` -> lockCount, totalLockTime, avgLockTime, avgQueueTime

### Proposed API surface (HTTP)
Expose read-only JSON (GET-only) under the existing root action namespace (exact endpoint to be decided), returning a documented schema.

### Implementation notes (v1)
Start with in-memory counters updated on lock/unlock/queue transitions. Persistence can be a follow-up.

### Acceptance criteria
- Status and stats change correctly across a lock/unlock cycle
- GET-only endpoint with appropriate permission checks
- Minimal overhead on hot paths

### Tests
- JenkinsRule tests proving status/stats correctness
- Endpoint test verifying verb/permissions

Contributor guide

Open the contributing guide

Research direction

Start by tracing the existing lock, unlock, and queue-transition paths and the root action namespace used for HTTP endpoints. Review the proposed status and statistics fields, then use JenkinsRule tests to verify a lock/unlock cycle and an endpoint test for GET-only behavior and permissions. Done means stable documented JSON responses with correct counters and minimal hot-path overhead.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.