api/types/system: deprecate `DiskUsage.*` fields and add type specific fields by austinvazquez · Pull Request #51235 · moby/moby

austinvazquez · 2025-10-20T20:45:14Z

- What I did

Part of client: create option-structs for all client-methods #50965
depends on / stacked on client: refactor Events, Info, RegistryLogin #51320

This change deprecates the api/types/system.DiskUsage top level fields and adds new type specific fields. Additionally this change adds to the client new wrapper structs for options/results.

- How I did it

- How to verify it

- Human readable description for the release notes

api/types/system: deprecated top level `DiskUsage` fields for type specific fields.

- A picture of a cute animal (not mandatory but encouraged)

Copilot

Pull Request Overview

This PR refactors the client API to wrap system-related method responses in dedicated result types, improving API consistency and extensibility. The changes introduce wrapper types (SystemInfoResult, PingResult, EventsResult, DiskUsageResult, RegistryLoginResult) that encapsulate the original response data, along with a new RegistryLoginOptions type for better parameter handling.

Key changes:

Introduced wrapper result types for Info(), Ping(), Events(), DiskUsage(), and RegistryLogin() methods
Changed Events() return signature from multiple return values to a single EventsResult struct
Created RegistryLoginOptions to replace direct use of registry.AuthConfig as method parameter
Updated all call sites across integration tests and internal utilities to unwrap the new result types

Reviewed Changes

Copilot reviewed 34 out of 42 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
client/system_info.go	Introduces `SystemInfoResult` wrapper and updates `Info()` return type
client/ping.go	Introduces `PingResult` wrapper and updates `Ping()` return type
client/system_events.go	Introduces `EventsResult` wrapper and changes `Events()` from returning two channels to a single result struct
client/system_disk_usage.go	Introduces `DiskUsageResult` wrapper, moves `DiskUsageOptions` from separate file, updates `DiskUsage()` return type
client/system_disk_usage_opts.go	Deleted (options moved to system_disk_usage.go)
client/login.go	Introduces `RegistryLoginOptions` and `RegistryLoginResult`, updates `RegistryLogin()` signature
client/client_interfaces.go	Updates `SystemAPIClient` interface to reflect new method signatures
client/client.go	Updates calls to `Ping()` to unwrap `PingResult`
integration/system/*.go	Updates test code to unwrap new result types from `Info()`, `Ping()`, `Events()`, and `DiskUsage()`
integration/container/*.go	Updates test code to unwrap new result types
integration/plugin/authz/*.go	Updates test code to unwrap new result types
integration/networking/*.go	Updates test code to unwrap new result types
integration/build/*.go	Updates test code to unwrap new result types
integration-cli/*.go	Updates legacy test code to unwrap new result types
internal/testutil//.go	Updates utility functions to unwrap new result types
client/system_info_test.go	Updates unit tests to unwrap `SystemInfoResult`
client/system_events_test.go	Updates unit tests to use `EventsResult` struct fields
client/ping_test.go	Updates unit tests to unwrap `PingResult`

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

thaJeztah · 2025-10-21T16:42:35Z

client/system_disk_usage.go

+// DiskUsageOptions holds parameters for system disk usage query.
+type DiskUsageOptions struct {
+	// Types specifies what object types to include in the response. If empty,
+	// all object types are returned.
+	Types []system.DiskUsageObject
+}


Wondering if we should start aligning this one with the backend.DiskUsage type; the "fun" thing there is that the daemon was rewritten to produce that new type, but it was never wired up, so the API continued producing the old format;

[DNM] DiskUsage is not wired up? #51181

But as we'll now separating the client's output struct from the underlying API response, possibly we could already align it with that, then in future change the API response.

moby/daemon/server/backend/disk_usage.go

Lines 22 to 57 in e30e80d

// DiskUsage contains the information returned by the backend for the

// GET "/system/df" endpoint.

type DiskUsage struct {

Images *ImageDiskUsage

Containers *ContainerDiskUsage

Volumes *VolumeDiskUsage

BuildCache *BuildCacheDiskUsage

}

// BuildCacheDiskUsage contains disk usage for the build cache.

type BuildCacheDiskUsage struct {

TotalSize int64

Reclaimable int64

Items []*build.CacheRecord

}

// ContainerDiskUsage contains disk usage for containers.

type ContainerDiskUsage struct {

TotalSize int64

Reclaimable int64

Items []*container.Summary

}

// ImageDiskUsage contains disk usage for images.

type ImageDiskUsage struct {

TotalSize int64

Reclaimable int64

Items []*image.Summary

}

// VolumeDiskUsage contains disk usage for volumes.

type VolumeDiskUsage struct {

TotalSize int64

Reclaimable int64

Items []*volume.Volume

}

Currently we have code in the CLI doing that conversion, but that could potentially be moved to the client if the shape of the result allows it.
https://github.com/docker/cli/blob/644dc16b169c1cf1bab56af34eedfe3c1378fb58/cli/command/formatter/disk_usage.go#L295-L312

client/ping.go

thaJeztah · 2025-10-22T08:06:17Z

Did a quick rebase, only to fix the merge conflicts; I'll have a look at the Ping (and swarm.Status) structs now.

thaJeztah · 2025-10-22T10:31:48Z

GItHub Unicorns 🦄

Step 9/13 : ADD [https://github.com/moby/busybox/releases/download/${BUSYBOX_VERSION}/busybox-w32-${BUSYBOX_VERSION}.exe](https://github.com/moby/busybox/releases/download/$%7BBUSYBOX_VERSION%7D/busybox-w32-$%7BBUSYBOX_VERSION%7D.exe) /bin/busybox.exe
ADD failed: failed to GET https://github.com/moby/busybox/releases/download/FRP-5007-g82accfc19/busybox-w32-FRP-5007-g82accfc19.exe with status 503 Service Unavailable: <!DOCTYPE html>
<!--

Hello future GitHubber! I bet you're here to remove those nasty inline styles,
DRY up these templates and make 'em nice and re-usable, right?

Please, don't. https://github.com/styleguide/templates/2.0

-->
<html>
  <head>
    <title>Unicorn! &middot; GitHub</title>
    <style type="text/css" media="screen">
      body {
        background-color: #f1f1f1;
        margin: 0;
        font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
      }

vvoland · 2025-10-22T12:14:43Z

Whoops, needs a rebase

thaJeztah · 2025-10-22T13:33:38Z

@austinvazquez could you have a peek at #51235 (comment) as well, to see if it's something viable?

Copilot

Pull Request Overview

Copilot reviewed 30 out of 36 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

austinvazquez · 2025-10-28T02:46:13Z

@thaJeztah , @vvoland if you folks could ptal here. The latest revision implements the disk usage result with both older and newer shapes of disk usage.

client/system_disk_usage.go

austinvazquez · 2025-10-30T16:57:57Z

Added the verbose query and new API responses excluding the extra Items fields. Let's see what breaks before continuing.

Copilot

Pull Request Overview

Copilot reviewed 19 out of 27 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

daemon/disk_usage.go

daemon/server/router/system/system_routes.go

api/docs/CHANGELOG.md

client/system_disk_usage.go

Copilot

Pull Request Overview

Copilot reviewed 19 out of 27 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

api/types/system/disk_usage.go

austinvazquez · 2025-10-30T20:44:22Z

Actually a pretty good start. Looking into the docker-py failures now.

thaJeztah · 2025-10-31T00:36:42Z

daemon/server/router/system/system_routes.go

-	du := backend.DiskUsage{}
-	if getBuildCache {
-		du.BuildCache = &backend.BuildCacheDiskUsage{


For API < v1.52 we can keep the old conversion code and return the old API struct; move the old API struct in the backend, and use it as response type for API <v1.52.

This change adds type specific fields to `GET /system/df` endpoint with high level information of disk usage. This change also introduces `verbose` query to the endpoint so that detailed information is by default excluded unless queried to reduce memory consumption. The previous top level `DiskUsage` fields (`Images`, `Containers`, `Volumes` and `BuildCache`) are now deprecated and kept for backwards compatibility. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Austin Vazquez <austin.vazquez@docker.com>

austinvazquez · 2025-11-04T04:24:16Z

@vvoland , @thaJeztah, I pushed another revision this time maintaining backwards compatibility for legacy fields on new API versions that do not specify verbose query.

vvoland

LGTM

thaJeztah · 2025-11-05T12:59:56Z

api/docs/CHANGELOG.md

+* `GET /system/df` returns `ImagesUsage`, `ContainersUsage`, `VolumesUsage`, and
+  `BuildCacheUsage` fields with brief system disk usage data for each system object type.
+  The endpoint supports the `?verbose=1` query to return verbose system disk usage information.
+* Deprecated: `GET /system/df` response fields `LayersSize`, `Images`, `Containers`,


Removed is indeed probably more correct, but I think we're currently still returning them with this PR.

I'll have a look in a follow-up to see if we can make a clean cut (< v1.52, >= v1.52); for the docker-py tests, we need to check, because using "yolo-latest" (un-versioned API) has been deprecated for some years, and generally should not be used.

thaJeztah

LGTM

github-actions bot added area/logging area/networking Networking area/dependencies module/client labels Oct 20, 2025

austinvazquez mentioned this pull request Oct 20, 2025

client: create option-structs for all client-methods #50965

Closed

austinvazquez self-assigned this Oct 20, 2025

austinvazquez marked this pull request as ready for review October 20, 2025 22:45

austinvazquez requested a review from Copilot October 20, 2025 22:52

Copilot AI reviewed Oct 20, 2025

View reviewed changes

thaJeztah reviewed Oct 21, 2025

View reviewed changes

client/ping.go Outdated Show resolved Hide resolved

thaJeztah added the release-blocker PRs we want to block a release on label Oct 21, 2025

thaJeztah added this to the 29.0.0 milestone Oct 21, 2025

thaJeztah force-pushed the refactor-client-system branch from 151c2c7 to e637803 Compare October 22, 2025 08:04

github-actions bot added area/swarm module/api labels Oct 22, 2025

thaJeztah force-pushed the refactor-client-system branch 2 times, most recently from 83747d8 to da3bcf5 Compare October 22, 2025 08:49

thaJeztah mentioned this pull request Oct 22, 2025

api/types: move Ping and swarm.Status to client #51258

Merged

vvoland approved these changes Oct 22, 2025

View reviewed changes

austinvazquez force-pushed the refactor-client-system branch 2 times, most recently from a6223dd to e059055 Compare October 24, 2025 21:35

austinvazquez requested a review from Copilot October 24, 2025 21:37

Copilot AI reviewed Oct 24, 2025

View reviewed changes

austinvazquez force-pushed the refactor-client-system branch from e059055 to 27304bf Compare October 25, 2025 00:26

thaJeztah force-pushed the refactor-client-system branch from 0e5072e to ab9cb23 Compare October 29, 2025 08:42

austinvazquez force-pushed the refactor-client-system branch from ab9cb23 to d5a844a Compare October 29, 2025 13:34

vvoland reviewed Oct 29, 2025

View reviewed changes

client/system_disk_usage.go Outdated Show resolved Hide resolved

austinvazquez force-pushed the refactor-client-system branch from d5a844a to 15c8a54 Compare October 30, 2025 16:55

austinvazquez requested a review from tianon as a code owner October 30, 2025 16:55

austinvazquez marked this pull request as draft October 30, 2025 16:56

austinvazquez requested a review from Copilot October 30, 2025 17:01

Copilot AI reviewed Oct 30, 2025

View reviewed changes

austinvazquez force-pushed the refactor-client-system branch 2 times, most recently from a03621e to 285334b Compare October 30, 2025 18:57

austinvazquez requested a review from Copilot October 30, 2025 19:01

Copilot AI reviewed Oct 30, 2025

View reviewed changes

api/types/system/disk_usage.go Outdated Show resolved Hide resolved

thaJeztah reviewed Oct 31, 2025

View reviewed changes

austinvazquez force-pushed the refactor-client-system branch from 285334b to eff24b0 Compare October 31, 2025 00:41

austinvazquez marked this pull request as ready for review October 31, 2025 01:00

vvoland self-requested a review October 31, 2025 16:42

austinvazquez force-pushed the refactor-client-system branch from eff24b0 to a69abdd Compare November 3, 2025 22:34

vvoland approved these changes Nov 4, 2025

View reviewed changes

thompson-shaun requested a review from dmcgowan November 4, 2025 20:10

dmcgowan approved these changes Nov 4, 2025

View reviewed changes

thaJeztah reviewed Nov 5, 2025

View reviewed changes

thaJeztah approved these changes Nov 5, 2025

View reviewed changes

thaJeztah merged commit b075a39 into moby:master Nov 5, 2025
283 of 288 checks passed

austinvazquez deleted the refactor-client-system branch November 5, 2025 14:04

thaJeztah mentioned this pull request Nov 7, 2025

daemon: disk-usage: fix incorrect key for singleflight #51443

Merged

lmdc45 mentioned this pull request Nov 13, 2025

ambassador links variable env issue after latest docker update dokku/dokku#8096

Closed

	// DiskUsage contains the information returned by the backend for the
	// GET "/system/df" endpoint.
	type DiskUsage struct {
	Images *ImageDiskUsage
	Containers *ContainerDiskUsage
	Volumes *VolumeDiskUsage
	BuildCache *BuildCacheDiskUsage
	}

	// BuildCacheDiskUsage contains disk usage for the build cache.
	type BuildCacheDiskUsage struct {
	TotalSize int64
	Reclaimable int64
	Items []*build.CacheRecord
	}

	// ContainerDiskUsage contains disk usage for containers.
	type ContainerDiskUsage struct {
	TotalSize int64
	Reclaimable int64
	Items []*container.Summary
	}

	// ImageDiskUsage contains disk usage for images.
	type ImageDiskUsage struct {
	TotalSize int64
	Reclaimable int64
	Items []*image.Summary
	}

	// VolumeDiskUsage contains disk usage for volumes.
	type VolumeDiskUsage struct {
	TotalSize int64
	Reclaimable int64
	Items []*volume.Volume
	}

Conversation

austinvazquez commented Oct 20, 2025 • edited by thaJeztah Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

thaJeztah Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thaJeztah commented Oct 22, 2025

Uh oh!

thaJeztah commented Oct 22, 2025

Uh oh!

vvoland commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thaJeztah commented Oct 22, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

austinvazquez commented Oct 28, 2025

Uh oh!

Uh oh!

austinvazquez commented Oct 30, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

austinvazquez commented Oct 30, 2025

Uh oh!

thaJeztah Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

austinvazquez commented Nov 4, 2025

Uh oh!

vvoland left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

austinvazquez commented Oct 20, 2025 •

edited by thaJeztah

Loading

vvoland commented Oct 22, 2025 •

edited

Loading