Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

`GET /v1/stats` and the `simlock stats --csv` ledger

Đang mở
  • Có gì không ổn?
#348 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
65/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
api, backend, cli, documentation

Hướng nghiên cứu

Start with the shared window rules and duration parser, then read src/core/usage/, src/contract/operations.ts, and the relevant handler in src/http/app.ts. Implement the ledger and CSV behavior in src/cli/index.ts, following the listed test cases; update docs/HTTP-API.md and docs/CLI.md. Done means the route matches CLI figures, CSV has one row per request, and the authorization and history-window cases behave as specified.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

task:draft

Part of #329.

Scope

After this PR, GET /v1/stats answers the same figures as simlock stats --json for the same window, and simlock stats --csv writes one row per lease request in the window, a file a spreadsheet opens.

Technical spec

Modules touched
  • src/http/app.ts — GET /v1/stats?since=<duration> or ?from=<ISO>&to=<ISO>, with &ledger=1 to include the ledger; to defaults to now; both forms together, or neither, follow the CLI's rules (neither means the last 24 hours). The handler parses the query with the shared duration parser, dispatches usage.get, and returns its output as JSON. HISTORY_NOT_KEPT takes its status from the contract's error table, as every error does; a bad window is 400.
  • src/contract/operations.ts — usage.get input gains includeLedger: boolean, default false; the output carries requests[] only when it is true, so a console or a plain simlock stats call never receives the ledger.
  • src/core/usage/ — computeUsage output gains requests[] when asked, the ledger: { requestId, requester, label?, platform, model, workerId?, source?, requestedAt, grantedAt?, endedAt?, waitMs?, heldMs?, turnaroundMs?, outcome: "granted" | "rejected" | "open", reason?, endReason? }, one entry per lease.requested in the window.
  • src/cli/index.ts — --csv on simlock stats asks for the ledger and writes it as RFC 4180 CSV to stdout, one header row, a column per ledger field in that order, timestamps as ISO 8601, empty cell for an absent value. --csv with --json is a usage error.
  • docs/HTTP-API.md (route, query, errors, gateway behaviour), docs/CLI.md (--csv), docs/CLIENT.md if the ledger shows in the client type.
Contract and event changes
  • usage.get input gains includeLedger (default false); output gains requests[] when it is set. Additive.
  • New route GET /v1/stats. Operator token; an agent token gets 403 as every operator route does.
Rules in play
  • safety.md rule 10: since, from, to are wire input, parsed and bounded before dispatch.
  • architecture.md rule 10: the window rules are the CLI's and the route's through one shared function, not two copies.
Tests
  • computeUsage lists one ledger entry per request with the timestamps and durations of its grant and end, and open for a request still waiting at the window's end
  • the CSV writer quotes a field containing a comma, a quote or a newline, and writes an empty cell for an absent value
  • simlock stats --csv prints a header row and one row per request, and rejects --csv --json
  • GET /v1/stats?since=1h returns the same body as usage.get for that window, without requests[]; &ledger=1 adds it
  • GET /v1/stats?from=&to= with from later than to returns 400 naming the parameter
  • GET /v1/stats with no window returns the last 24 hours
  • GET /v1/stats with a window that ends before the oldest held event returns HISTORY_NOT_KEPT with the status the error table gives it
  • GET /v1/stats with an agent token returns 403
  • (e2e) after a scripted run, curl GET /v1/stats?since=1h and simlock stats --since 1h --json print equal figures
  • (e2e) simlock stats --csv --since 1h has as many data rows as lease.requested events in the window

Done when

  • After a scripted run against the fake driver, GET /v1/stats?since=1h with an operator token returns the same figures as simlock stats --since 1h --json.
  • simlock stats --csv --since 1h > run.csv writes a file with one header row and one row per lease request, which a spreadsheet opens with the columns separated.
  • An agent token gets 403 on the route; a window older than the kept history gets 422 with the oldest kept time in the body.
  • docs/HTTP-API.md describes the route under Operator routes, and docs/CLI.md describes --csv.

Out of scope

  • The console view (next task).
  • A Prometheus or OpenMetrics endpoint.

Depends on

  • #347

Approval

  • Approved for delivery

Written by an agent.

Ngôn ngữ chính
TypeScript
Star
15
Fork
1
Merge trung bình
8 giờ 38 phút
Pull request đã merge (30 ngày)
135

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của callstackincubator/simlock

Tất cả issue của callstackincubator/simlock

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.