file-io

Overview ¶

Package main demonstrates ports.File: the declarative typed file descriptor for reading, writing, and updating files with full codec validation.

Scenario: an IoT sensor data pipeline that:

• Loads a TOML service config on startup using a static ports.File
• Applies a single env var override via config.FromEnvVar
• Writes and reads per-sensor JSON measurement files using a template path
• Validates path variables (date format) with a ports.FilePathParam codec
• Handles all typed file errors with errors.As
• Wires a stats.FileObserver for per-operation metrics + slog for structured errors
• Writes and reads raw binary (PNG) files using format.Binary + validate.PNG

Key patterns shown:

• ports.NewFile — declare once, use anywhere (mirrors rest.Route / events.Channel)
• ports.File.BuildPath — pre-flight path validation without any I/O
• ports.File.MatchPath + ports.NewFilePathParam + codex.DecodeVars — the inverse of BuildPath: extracting filename-encoded metadata (date, sensor) into a typed struct, merged alongside the body
• ports.File.Update — atomic read-modify-write in one call
• ports.FileOptions — wiring observer + custom file permission
• ports.FilePathParamError, ports.MissingFilePathVarError, ports.FileReadError — navigate via errors.As
• format.Binary — raw binary file I/O with magic-byte validation

Run with: go run ./examples/file-io