feat: Surface Flow task report on Task API by kunzhao-nv · Pull Request #2288 · NVIDIA/infra-controller

kunzhao-nv · 2026-06-07T18:44:29Z

Description

Adds the structured execution report (already produced by Flow) to the rack Task endpoints.
Single-task GET /rack/task/{id} and POST /rack/task/{id}/cancel always include the report. The two list endpoints (/rack/{id}/task, /tray/{id}/task) take a new withReport=true opt-in.
IncludeReport is plumbed all the way down to flow.ListTasksRequest, so Flow drops the multi-KB blob server-side when the caller hasn't asked for it; the savings cover the full Temporal workflow / activity payload chain, not just the wire response.

Type of Change

Add - New feature or capability
Change - Changes in existing functionality
Fix - Bug fixes
Remove - Removed features or deprecated functionality
Internal - Internal changes (refactoring, tests, docs, etc.)

Related Issues (Optional)

Breaking Changes

This PR contains breaking changes

Testing

Unit tests added/updated
Integration tests added/updated
Manual testing performed
No testing required (docs, internal refactor, etc.)

Additional Notes

coderabbitai · 2026-06-07T18:44:37Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 93e3f9ce-1f25-493c-9810-b4e0adde0fdc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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

github-actions · 2026-06-07T18:45:41Z

🌿 Preview your docs: https://nvidia-preview-pull-request-2288.docs.buildwithfern.com/infra-controller

github-actions · 2026-06-07T18:46:45Z

🔐 TruffleHog Secret Scan

✅ No secrets or credentials found!

Your code has been scanned for 700+ types of secrets and credentials. All clear! 🎉

🔗 View scan details

_{🕐 Last updated: 2026-06-07 18:46:44 UTC | Commit: fe67fc1}

Task.report bodies can be several KB. Always returning them on ListTasks would persist the blob in every caller-side Temporal activity / workflow payload along the call path, even when the caller never reads it. Opt callers in via with_report, defaulting to off for list endpoints; single-task RPCs always return it. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Pulls in the new ListTasksRequest.with_report field along with prior upstream drift (Task.report, override_assignment_check on the rack power / firmware / bring-up requests, and refreshed doc comments) that earlier PRs landed without running flow-proto + flow-protogen. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Surfaces the structured execution report Flow already produces on Task. Single-task GET and Cancel always include it; the rack/tray list endpoints accept withReport=true and forward the flag down to Flow's ListTasksRequest so the multi-KB payload is not paid for on the default list path. The report is exposed as an opaque JSON document with a typed version anchor; clients must branch on version before reading anything else, so Flow's internal schema can evolve without breaking REST consumers. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

github-actions · 2026-06-07T19:01:32Z

🔍 Container Scan Summary

Service	Total	Critical	High	Medium	Low	Other
nico-flow	116	13	50	41	4	8
nico-nsm	133	11	45	66	11	0
nico-psm	118	13	52	41	4	8
nico-rest-api	182	16	84	67	7	8
nico-rest-cert-manager	95	5	47	32	3	8
nico-rest-db	116	13	50	41	4	8
nico-rest-site-agent	115	13	50	41	3	8
nico-rest-site-manager	102	6	48	37	3	8
nico-rest-workflow	118	13	52	41	4	8
TOTAL	1095	103	478	407	43	64

Per-CVE detail lives in the per-service grype-* artifacts (JSON + SARIF). Severity counts only — no CVE IDs published here.

Covers 82626a9 (the task report + withReport spec change). Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Both list-task handlers built the same APIRackTaskOption slice from APIGetTasksRequest. Move the translation into model.BuildAPIRackTaskOptions so new opt-in fields wire up in one place. Addresses review feedback on PR NVIDIA#2288. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

thossain-nv · 2026-06-08T19:52:57Z

          type: string
          format: date-time
          description: Timestamp when the task was last updated.
+        report:


We need to establish some kind of contract with the user. If this schema is tied to version 1 of the report then we should provide a version 1 schema for the user.

The same model serves tray-scoped task endpoints in addition to rack ones; "RackTask" was misleading. Rename in lockstep with the OpenAPI schema Task. Handler / route / telemetry-label names keep "Rack" where they describe a specific endpoint scope rather than the response model. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Aligns the public query param with the REST naming convention. The Flow proto field stays with_report to match the existing with_rack / with_components flags on adjacent RPCs. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Replace the opaque report blob with a typed APITaskReportV1 schema that mirrors flow/internal/task/report. Clients get a stable v1 contract (status enum, stage / step nesting, RFC3339 timestamps); malformed or non-v1 payloads decode to nil so the response never carries an off-contract shape. Wire keys are camelCase (componentType, startedAt, ...) to match the rest of the REST API surface; conversion from Flow's snake_case emission happens inside parseTaskReportV1. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Covers 0f7cb00 (APITask rename), 9001abb (includeReport query param), and a583f98 (typed TaskReportV1 schema). Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

thossain-nv

Thanks for the changes @kunzhao-nv, left a few more notes.

thossain-nv · 2026-06-09T00:33:52Z

+// APITaskReportV1. Without this option, Report is left nil and is
+// omitted from the JSON response. A malformed or non-v1 payload also
+// yields nil so the response never carries an off-contract shape.
+func WithReport() APITaskOption {


This package is model so WithReport needs to be more specific e.g. APITaskOptionWithReport

Prefer to keep WithReport here:

Call-site already disambiguates: model.NewAPITask(t, model.WithReport()) — the second-arg type (APITaskOption) tells which "Report" this is.

Go convention is bare pkg.WithX(): grpc.WithInsecure(), aws.WithRegion(), redis.WithMaxRetries(). The type comes from the constructor that consumes the option, not from the option name.

Repo precedent matches:

HTTPMiddlewareOption → WithTelemetry / WithRequestMetrics / WithHandlerTimeout

SharedInformerOption → WithNamespace / WithCustomResyncConfig / WithTweakListOptions

cert-manager/pkg/core/context.go (multi-concern, like model) → WithLogger / WithAppName / WithSignalHandler / WithClock

The difference here is that model is a large general package. The example you provided all have specific package scope e.g. Core.

By defining WithReport we're claiming WithReport function name for all models. Another model Instance won't be able to define func WithReport() APIInstanceOption because Go doesn't allow function overloading.

If you want to keep WithX convention, then I'd use WithTaskReport

Thanks. Addressed in 7e2d079

thossain-nv · 2026-06-09T00:35:13Z

+// (snake_case JSON keys). Used solely as an unmarshal target so the
+// REST-facing APITaskReportV1 can keep camelCase keys per the rest of
+// the API surface. Kept private; clients consume APITaskReportV1.
+type flowTaskReportV1 struct {


Do we not have proto objects for report?

No it is string type in flow proto.

Three follow-ups from thossain-nv on PR NVIDIA#2288: - Inline BuildAPITaskOptions as APIGetTasksRequest.TaskOptions, since the function only ever consumed a single request and was already conceptually a getter on it. - Move parseTaskReportV1 into APITaskReportV1.UnmarshalJSON so the custom Flow snake_case decoder is reachable via the standard encoding/json entry point. The marshal path stays camelCase via struct tags; the doc comment flags the resulting asymmetry. - Rename WithReport to WithTaskReport so future model option constructors for other API types (machine, rack, ...) can coexist in this shared package without colliding on a generic "Report" name. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Three follow-ups from PR NVIDIA#2288 review: - Inline BuildAPITaskOptions as APIGetTasksRequest.TaskOptions, since the function only ever consumed a single request and was already conceptually a getter on it. - Move parseTaskReportV1 into APITaskReportV1.UnmarshalJSON so the custom Flow snake_case decoder is reachable via the standard encoding/json entry point. The marshal path stays camelCase via struct tags; the doc comment flags the resulting asymmetry. - Rename WithReport to WithTaskReport so future model option constructors for other API types (machine, rack, ...) can coexist in this shared package without colliding on a generic "Report" name. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Two follow-ups from PR NVIDIA#2288 review: - Inline BuildAPITaskOptions as APIGetTasksRequest.TaskOptions, since the function only ever consumed a single request and was already conceptually a getter on it. - Move parseTaskReportV1 into APITaskReportV1.UnmarshalJSON so the custom Flow snake_case decoder is reachable via the standard encoding/json entry point. The marshal path stays camelCase via struct tags; the doc comment flags the resulting asymmetry. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

thossain-nv

Adding +1, consider the suggestion on option chaining.

Three follow-ups from PR NVIDIA#2288 review: - Inline BuildAPITaskOptions as APIGetTasksRequest.TaskOptions, since the function only ever consumed a single request and was already conceptually a getter on it. - Move parseTaskReportV1 into APITaskReportV1.UnmarshalJSON so the custom Flow snake_case decoder is reachable via the standard encoding/json entry point. The marshal path stays camelCase via struct tags; the doc comment flags the resulting asymmetry. - Rename WithReport to WithTaskReport so the bare "WithReport" name stays available for option constructors on other model types. Go has no function overloading, so claiming WithReport in this shared package would permanently preclude e.g. an APIInstance WithReport() down the line. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

- Inline BuildAPITaskOptions as APIGetTasksRequest.TaskOptions; it only ever consumed a single request. - Move parseTaskReportV1 into APITaskReportV1.UnmarshalJSON so the Flow snake_case decoder is reachable via encoding/json. Marshal stays camelCase via struct tags. - Rename WithReport to WithTaskReport so the shared model package keeps the bare WithReport name available for option constructors on other types. Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

Resolve task conflicts with NVIDIA#2288 (Task report API): - APITask gains both RuleID (ours) and Report (theirs) plus the APITaskOption / WithTaskReport plumbing - spec.yaml interleaves Task example (ruleId + report) and keeps both schema sets (OperationRule chain + TaskReportV1 chain) - regenerate docs/index.html and sdk/standard/ Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

kunzhao-nv requested a review from a team as a code owner June 7, 2026 18:44

kunzhao-nv added 3 commits June 7, 2026 11:55

chore(rest-api): regenerate openapi docs + sdk

3aa6e8b

Covers 82626a9 (the task report + withReport spec change). Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

kunzhao-nv force-pushed the feat/rest-api-task-report branch from fe67fc1 to 3aa6e8b Compare June 7, 2026 19:01

kunzhao-nv requested review from jw-nvidia and thossain-nv June 7, 2026 19:04

jw-nvidia reviewed Jun 8, 2026

View reviewed changes

Comment thread rest-api/api/pkg/api/handler/task.go Outdated

jw-nvidia approved these changes Jun 8, 2026

View reviewed changes

thossain-nv reviewed Jun 8, 2026

View reviewed changes

kunzhao-nv added 4 commits June 8, 2026 13:36

chore(rest-api): regenerate openapi docs + sdk

35dab00

Covers 0f7cb00 (APITask rename), 9001abb (includeReport query param), and a583f98 (typed TaskReportV1 schema). Signed-off-by: Kun Zhao <kunzhao@nvidia.com>

thossain-nv reviewed Jun 9, 2026

View reviewed changes

kunzhao-nv force-pushed the feat/rest-api-task-report branch from 8bfe293 to b02af2e Compare June 9, 2026 04:09

kunzhao-nv force-pushed the feat/rest-api-task-report branch from b02af2e to 5988d28 Compare June 9, 2026 04:12

thossain-nv approved these changes Jun 9, 2026

View reviewed changes

kunzhao-nv force-pushed the feat/rest-api-task-report branch from 5988d28 to c4223e7 Compare June 9, 2026 21:38

kunzhao-nv force-pushed the feat/rest-api-task-report branch from c4223e7 to 7e2d079 Compare June 9, 2026 21:43

jw-nvidia approved these changes Jun 9, 2026

View reviewed changes

Merge branch 'main' into feat/rest-api-task-report

4319353

kunzhao-nv enabled auto-merge (squash) June 9, 2026 21:49

kunzhao-nv merged commit a4a8507 into NVIDIA:main Jun 9, 2026
89 checks passed

Conversation

kunzhao-nv commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of Change

Related Issues (Optional)

Breaking Changes

Testing

Additional Notes

Uh oh!

coderabbitai Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

github-actions Bot commented Jun 7, 2026

Uh oh!

github-actions Bot commented Jun 7, 2026

🔐 TruffleHog Secret Scan

Uh oh!

github-actions Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Container Scan Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thossain-nv Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

thossain-nv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

thossain-nv Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

kunzhao-nv Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

thossain-nv Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

kunzhao-nv Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

thossain-nv Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

kunzhao-nv Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

thossain-nv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kunzhao-nv commented Jun 7, 2026 •

edited

Loading

coderabbitai Bot commented Jun 7, 2026 •

edited

Loading

github-actions Bot commented Jun 7, 2026 •

edited

Loading