Skip to content

Let consumers capture or redirect loading warnings with a Logger - #954

Merged
ndeloof merged 3 commits into
compose-spec:mainfrom
ndeloof:logging-hook
Oct 22, 2026
Merged

ndeloof merged 3 commits into
compose-spec:mainfrom
ndeloof:logging-hook

Conversation

@ndeloof

@ndeloof ndeloof commented Oct 22, 2026

Copy link
Copy Markdown
Collaborator

What this PR does, in one sentence

Lets a consumer of compose-go capture or redirect the warnings emitted while loading a project, through a single optional Logger that defaults to today's behavior.

Context

compose-go reports obsolete version attributes, YAML 1.1 booleans, unset variables, ambiguous default file discovery and similar issues through the global logrus logger. A library embedding compose-go (Docker Compose is one example) can neither collect these warnings to surface them its own way, nor keep them out of its output, nor route them to the logger it already uses, except by mutating global logrus state.

What the PR brings

A one-method contract, logging.Logger:

type Logger interface {
    Warnf(format string, args ...any)
}

and one way to provide it at each level: loader.Options.Logger, cli.WithLogger(l) (which also hands it to the loader), and template.WithLogger(l) for callers using the template package directly. The warnings of the main loading path reach it: obsolete version, YAML 1.1 booleans (during interpolation and when decoding the model), unset variables (including inside default values and error messages, and in files loaded through include and extends), a misplaced local resource loader, multiple default config or override files, an inaccessible default .env, and a project name taken from a symlinked directory.

Guardrails:

  • Additive and inert by default. Nothing changes when no logger is set: same messages, same level, still emitted through the logrus global logger. No existing signature or exported type changes (gorelease reports only additions: logging package, Options.Logger, cli.WithLogger, template.WithLogger). No new exported mutable variable.
  • Why this contract. A local Warnf interface is satisfied as-is by *logrus.Logger (so Docker Compose can pass its logger unchanged) and by zap's sugared logger, and a log/slog adapter is a three-line method. *slog.Logger was not retained as the contract because it would force logrus-based consumers to write a handler bridge to keep their current output, and the messages are plain sentences with no useful structure to carry. A bare callback was not retained because an interface is the idiomatic, self-documenting shape for a logger and lets consumers pass their logger directly.
  • Minimal plumbing. The logger travels in the existing option structs (loader.Options, cli.ProjectOptions, template.Config); the interpolation and type-cast functions built by loader.ToOptions are bound to the options, so interpolation.Options is untouched. Options set through cli.WithLogger apply in order, so it must precede options that may warn, such as WithDefaultConfigPath (documented).

Known limits, deliberately not forced into this PR because routing them needs a wider refactoring or new exported API:

  • the external.name is deprecated warning (transform, whose canonicalizers are a registry of fixed-signature functions);
  • paths.ExpandUser ("cannot expand '~'");
  • warnings raised while parsing .env / env_file files (dotenv has no options object, its parsing functions are exported with fixed signatures);
  • boolean spellings in x-* extension values and include entries decoded through the exported loader.Transform.

These keep going through logrus. Also, the obsolete version warning remains emitted once per file for the whole process, as before, whichever logger the first load used.

loader/loader.go is touched in small, localized spots (the Options struct, ToOptions, clone, two warning calls), to limit conflicts with the pending refactoring of the same file in #948.

🤖 Generated with Claude Code

@ndeloof
ndeloof requested a review from glours as a code owner October 22, 2026 15:35
Add a logging.Logger contract and a template.WithLogger option. Without
the option, the warning is still written through the standard logrus
logger, unchanged. Default values and error messages carried by a
substitution, as well as the text following a braced expression, report
to the same logger as the outer substitution.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
Options.Logger, when set, receives the warnings raised by the loader:
obsolete version attribute, YAML 1.1 booleans, unset variables during
interpolation and misconfigured resource loaders. It is inherited by
the files loaded through include and extends. When nil, warnings keep
going through the standard logrus logger, with the same messages.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
WithLogger sends to a logging.Logger the warnings raised by the file
discovery options (several default config or override files, an
inaccessible default .env file, a project name taken from a symlink),
and hands the logger to the loader. Without it, those warnings keep
going through the standard logrus logger, unchanged.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
@ndeloof
ndeloof merged commit 85a97c0 into compose-spec:main Oct 22, 2026
12 checks passed
@ndeloof
ndeloof deleted the logging-hook branch October 22, 2026 15:40
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