Skip to content

feat(api): Validate for the options of Logs, Events, Publish and Down - #14515

Open
ndeloof wants to merge 2 commits into
docker:mainfrom
ndeloof:api-validate-options
Open

ndeloof wants to merge 2 commits into
docker:mainfrom
ndeloof:api-validate-options

Conversation

@ndeloof

@ndeloof ndeloof commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

What this PR does, in one sentence

Gives the options of Logs, Events, Publish and Down a Validate method, called first by each operation, so that values and combinations that cannot work fail early with a typed error.

Context

Some options of pkg/api accept values that cannot work, and fail late or not at all: a LogOptions.Index with no service indexes an empty slice and panics, with several services it silently looks in the first one only; a nil EventsOptions.Consumer panics when the first event arrives; an unknown PublishOptions.OCIVersion is only noticed once the layers have been pushed; and an unknown image prune mode in Down is reported with a message nothing can match. CreateOptions and UpOptions already validate up front.

What the PR brings

  • Validate for LogOptions, EventsOptions, PublishOptions and DownOptions, called first by Logs, Events, Publish and Down.
  • A new ErrInvalidOption sentinel, with InvalidOptionError carrying the option, the value and the accepted values (or a reason when a required option is left unset), and an IsErrInvalidOption helper. The Logs combination matches the existing ErrIncompatibleOptions.

The CLI already refuses these cases, so it is unaffected. Two visible effects for programs using the library: Logs with an Index and several services now fails instead of silently using the first one, and the message for an unknown image prune mode in Down becomes the typed error. No exported symbol is removed or changes type.

This is the part of #14419 that does not depend on the rest of that PR, extracted so it can be reviewed on its own.

🤖 Generated with Claude Code

…nations

Logs, Events, Publish and Down each accept options that cannot work, and
fail late or not at all:

- LogOptions.Index selects a replica of one service. With no service the
  lookup indexes an empty slice and panics, with several the others are
  silently ignored. The CLI refuses it, the library did not.
- EventsOptions.Consumer is called for every event, and a nil one panics when
  the first arrives.
- PublishOptions.OCIVersion is only checked once the layers are pushed.
- DownOptions.Images was validated inline in down(), with a message nothing
  could match.

Give each a Validate, and call it first from the operation. Invalid values
match the new ErrInvalidOption (InvalidOptionError, which also covers a
required option left unset through its Reason), and the Logs combination
matches the existing ErrIncompatibleOptions. The message for an unknown image
prune mode changes accordingly; nothing else that worked is rejected.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
@ndeloof
ndeloof requested review from a team as code owners November 16, 2026 15:34

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Assessment: 🟢 APPROVE

The PR cleanly introduces Validate() methods for LogOptions, EventsOptions, PublishOptions, and DownOptions, wired in before any side effects in the corresponding operations. The InvalidOptionError type correctly implements the errors.Is/errors.As chain via Unwrap(). No correctness bugs were found in the added code.

Lower-confidence findings (not posted inline)

  • [low] pkg/api/validate.go:98 — DownOptions.Validate() omits ImagePruneNone ("") from the allowed-values list in the error message (confidence: unverified/low)
    • The error is only returned for truly invalid values (those that don't pass Valid()), so ImagePruneNone is never erroneously rejected — but the error message won't tell callers that "" is an accepted no-op value. Consider adding it to the Allowed slice or using a human-readable label like "none".
  • [low] pkg/api/validate.go:50 — InvalidOptionError.Error() produces a malformed message ("x" is not one of ) when Allowed is nil/empty and Reason is unset (confidence: unverified/low)
    • No current call site hits this path, but the struct is exported and third-party callers could construct it this way. A guard on len(e.Allowed) == 0 with a fallback format would make the type more robust.

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Assessment: 🟢 APPROVE

The PR is well-structured and the core logic is correct. ErrInvalidOption and InvalidOptionError are properly defined (with Unwrap() ensuring errors.Is works), the Validate() methods guard the right conditions, and the early-return wiring in Logs, Events, Publish, and Down is correct. No high- or medium-severity issues were found.

Lower-confidence findings (not posted inline)

  • [low] pkg/api/validate.go:95 — DownOptions.Validate() allowed-list omits the valid empty-string value ImagePruneNone from the error message (confidence: unverified, low)
    • The Allowed field in the returned InvalidOptionError lists only ["local", "all"]; the valid zero-value "" (ImagePruneNone) is not mentioned. The validation logic itself is correct — Valid() accepts the zero value — but a caller who receives the error has no way to discover from the message that "" is also accepted.
  • [low] pkg/api/validate.go:60 — LogOptions.Validate() error message conflates "no service" and "multiple services" into one message (confidence: unverified, low)
    • Both len(o.Services) == 0 and len(o.Services) > 1 are caught by the single len(o.Services) != 1 guard, producing the message "Index selects a replica of one service, but N services are selected" for both. For N=0 this reads oddly since the problem is a missing service rather than conflicting selections.
  • [low] pkg/compose/validate_options_test.go:33 — TestOperationsRejectInvalidOptions does not cover Down validation (confidence: unverified, low)
    • The test exercises Logs, Events, and Publish but omits Down. Down has its own test in down_test.go, but if the early Validate() call were removed from down.go, this integration test would not catch the regression.

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Assessment: 🟡 NEEDS ATTENTION

Comment thread pkg/api/validate.go Resolved
DownOptions.Validate omitted the empty ImagePruneNone value from the
allowed list, so the error did not tell callers that "" is accepted.
Quote the allowed values so an empty one stays readable, fall back to a
generic message when no closed set is given, and word the Logs Index
error properly when no service is selected.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
@ndeloof
ndeloof requested a review from docker-agent November 16, 2026 15:46

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This review covers only the commits pushed since 0dfeacad47e8.

Assessment: 🟢 APPROVE

The incremental changes are correct and clean. The previously flagged issue — DownOptions.Validate() omitting ImagePruneNone from the Allowed list — has been properly fixed in this batch. All new code introduced by these commits is well-reasoned:

  • The len(e.Allowed) == 0 guard in InvalidOptionError.Error() avoids a confusing empty-list message and returns a sensible fallback.
  • Wrapping each allowed value with strconv.Quote() before joining them makes the empty string ("") clearly readable in error messages, consistent with the project's convention.
  • servicesSelected(n) correctly handles both edge cases (n == 0 → "no service is selected"; n > 1 → "%d services are selected"); n == 1 is never passed because the guard len(o.Services) != 1 gates the call.
  • Test expectations are updated to match the new quoted format and the new ImagePruneNone entry exactly.
  • The new strconv import is inserted in correct alphabetical order, compliant with gci rules.

@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.14286% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
pkg/api/errors.go 0.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

This branch has not been deployed

No deployments
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