Skip to content

Define consistent size-unit parsing, rounding, and presentation #564

Open

Description

@hbrodin

Problem

coop represents and presents storage and memory sizes across CLI arguments,
configuration, backend state, status output, logs, errors, and JSON. The current
behavior is mostly documented as binary units, but parsing, rounding, and
presentation are not governed by one explicit policy.

PR #563 exposed the usability side of this: exact byte comparison is necessary
to reject an image that is even one block larger than an absolute GiB target,
but an accurate error currently reports both values only as raw bytes even
though the user entered a GiB value. Conversely, reporting only whole GiB would
make a 1 GiB + 4 KiB image and a 1 GiB request look equal.

Related implementation details include:

  • --disk, --template-size, and resize --size use GiB quantities.
  • resize --size accepts bare integers and G/g, with G meaning GiB.
  • Firecracker decisions sometimes require exact image byte lengths.
  • current_disk_gib rounds file sizes down for relative resize and replay.
  • Lima base-image sizing rounds file sizes up.
  • Human status output uses both MiB and GiB depending on the surface/backend.
  • JSON generally prefers raw byte or raw MiB values, but this should be checked
    as a stable API contract.

Goal

Define and apply a consistent size-unit policy that is technically accurate and
easy for users to understand. Preserve exact values for safety decisions while
showing useful human-readable context.

Suggested scope

  • Inventory storage and memory size inputs and outputs across CLI help, config,
    status/list/images output, JSON, logs, errors, docs, and both backends.

  • Decide which suffixes are accepted and what they mean: bare values, G,
    GB, GiB, M, MB, and MiB. Reject ambiguous forms or document them
    explicitly.

  • Define rounding rules for each operation: safety comparison, absolute resize,
    relative resize, template/base-image derivation, status, and display.

  • Centralize checked byte/MiB/GiB conversion and human formatting where useful.

  • Keep exact-byte comparisons for shrink prevention and other safety decisions.

  • For diagnostics involving a non-aligned image, show both the user's unit and
    the exact byte value, for example:

    Shrinking is not supported (current image: 1073745920 bytes; requested: 1 GiB / 1073741824 bytes)
    
  • Make Firecracker and Lima messages consistent where their semantics match,
    while retaining intentional backend differences.

  • Add unit and integration assertions for accepted/rejected suffixes, boundary
    values, non-GiB-aligned files, rounding, overflow, and rendered diagnostics.

  • Update user documentation with a short unit convention and examples.

Acceptance criteria

  • The repository documents one explicit convention for decimal versus binary
    units and ambiguous suffixes.
  • Parsing and rendering follow that convention across CLI/config surfaces.
  • No control-flow decision that needs exactness is made from a rounded display
    value.
  • Relative resize and reprovision behavior for non-aligned image lengths is
    explicitly specified and tested.
  • Human diagnostics are understandable without sacrificing the exact values
    needed to explain boundary cases.
  • Machine-readable fields retain stable, documented units or are migrated with
    an explicit compatibility plan.

Follow-up to #540 and #563; this should not block the correctness fix in #563.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions