Documentation
¶
Overview ¶
Package humanize renders byte counts as human-readable strings and sums a directory tree's apparent (logical) size, for boid's workspace-home size reporting (docs/plans/home-workspace-volume.md Phase 4 PR5: `boid workspace show`, `boid gc`'s workspace_homes listing, and the confirmation prompt on `boid workspace remove`).
FormatBytes is what those three still use. ApparentSize is not — PR7 of docs/plans/workspace-home-volume-persistence.md moved sizing onto the engine, since a workspace home is a docker volume the daemon cannot walk. See ApparentSize's own doc comment for its current status, and for how the engine's numbers differ from the ones it produces.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApparentSize ¶
Status as of PR7 of docs/plans/workspace-home-volume-persistence.md ¶
ApparentSize has NO production caller any more. The workspace home became a docker named volume in PR6, and PR7 rewired sizing onto the engine's GET /system/df, which is the only endpoint that reports a volume's size at all — the daemon cannot walk a volume's contents from outside a container, so there is nothing here for it to point at.
It is kept rather than deleted because PR8's migration CLI (`boid workspace import-home`) reads the LEGACY <runtimesRoot>/homes/<slug> directories an upgraded installation still has, and sizing one of those is exactly this function's job. If PR8 lands without using it, delete it then.
Worth knowing when comparing old and new numbers: df's size is real `du` semantics, so it differs from this function on two of the trade-offs listed below — it counts a hardlinked file once per inode, not once per name, and it counts a symlink's target-string length. Sparse files stay logical in both.
ApparentSize returns the total *apparent* (logical) size, in bytes, of every regular file found by recursively walking root — directory entries themselves do not contribute to the total, only file content sizes do. Symlinks are not followed (filepath.Walk uses Lstat internally), so a symlink's own directory-entry size is counted but nothing on the far side of it is descended into — this avoids both symlink loops and a home directory's size silently including content that lives outside it.
This is a plain sum of FileInfo.Size() and is *not* a `du`-equivalent block-based measurement: it deliberately matches `du --apparent-size`, not plain `du` (codex PR #791 review, Should-fix #3). Two known, accepted trade-offs follow from that choice: a sparse file's logical size is counted even though it occupies far fewer disk blocks (e.g. a seek-and-truncate-created multi-GB file with no actual data written), and a hardlinked file is counted once per name found rather than once per inode (relevant for package caches, which hardlink aggressively). A true `du`-equivalent measurement would need Linux's syscall.Stat_t.Blocks (for the block-based total) plus an Ino-keyed dedup set (for hardlinks) — an OS-specific implementation deliberately left out of scope here; apparent size is judged good enough for boid's "is this workspace home suspiciously large" visibility use case, and the plain-Walk approach stays portable and simple. Revisit only if apparent size proves misleading in practice.
Any error encountered while walking — root itself missing, a permission error partway through a subdirectory, or anything else Walk's callback receives — aborts the walk immediately and is returned verbatim; callers must treat a non-nil error as "size unknown" (docs/plans/ home-workspace-volume.md PR5: "エラー時はエラーにせず「?」表示にして continue") rather than trusting the also-returned partial total.
func FormatBytes ¶
FormatBytes renders n as a human-readable SI byte size: a plain integer count below 1000 ("500 B", "0 B"), or "%.2f <unit>" (two decimal places) scaled to the largest unit that keeps the leading digit non-zero (KB, MB, GB, TB, PB — boid workspace homes are not expected to reach EB). Negative values (should not occur — callers only ever pass a summed directory size) are treated as 0 B rather than producing a nonsensical "-1 B".
Types ¶
This section is empty.