Deprecated: moved into github.com/kitsunium/sdk/internal (ADR 0171), which no consumer imports; update with: go get github.com/kitsunium/sdk/pkg/v1/<family>@latest for each family you import && go mod tidy
README
¶
internal/core/transform
transform declares the byte-transform port of the SDK: the Compressor
contract and the process-wide registry mapping an Algorithm to a registered
Compressor. It is the fifth core sibling (ADR 0014) and mirrors
internal/core/codec exactly — the registry resolves an Algorithm to a
Compressor the way codec resolves a Format to a Codec.
Port
type Algorithm string // "gzip", "flate" — frozen per scheme, like codec.Format
type Compressor interface {
Algorithm() Algorithm
Compress(dst, src []byte) (out []byte, err error)
Decompress(dst, src []byte) (out []byte, err error)
}
func Register(c Compressor) Compressor
func Lookup(a Algorithm) (Compressor, bool)
func Available() []Algorithm
Concrete schemes live under internal/service/transform/ (stdlib gzip/flate)
and self-register via a package-level var at import — no init().
Why a parallel registry, not a codec Format
Adding gzip as a codec Format would break the frozen any→[]byte codec
contract and the append-only Format set. The compression verbs
(MarshalCompressed / UnmarshalCompressed) and the self-describing
compressed-frame format live at pkg/v1/codec; this package declares only the
port + registry. See ADR 0014 D1.
Error codes (range 0.2.5.*)
| Code | Var | Trigger |
|---|---|---|
0.2.5.1 |
UnknownCompressor |
Lookup/Decompress of an unregistered algorithm |
0.2.5.2 |
CompressionFailed |
the compressor returned an error |
0.2.5.3 |
DecompressionFailed |
the decompressor returned an error |
0.2.5.4 |
CompressedFrameInvalid |
malformed frame OR decompression-bomb guard tripped (emitter: pkg/v1/codec frame layer) |
Documentation
¶
Overview ¶
Package transform — range 0.2.5.* (ADR 0014 core/transform block).
Package transform — declares the sentinels returned by the Compressor facade. Each var's name equals its errs.Define Reason in SCREAMING_SNAKE form. CodeUnknownCompressor is also surfaced via panic at boot on a duplicate registration (see registry.go), not only as an *Error sentinel.
Package transform — holds the process-wide Compressor registry. Service-level scheme packages register themselves via package-level var initialisers when imported (no init()), mirroring core/codec and core/crypto.
Package transform declares the byte-transform port of the SDK: the Compressor contract and the typed Algorithm string under which a compressor registers. It is the fifth core sibling beside codec, writer, crypto, and logger (ADR 0014 D1) and mirrors codec exactly — the registry resolves an Algorithm to a Compressor the way codec resolves a Format to a Codec.
No algorithm bodies and no vendor types live here; concrete compressors live under internal/service/transform/ (stdlib gzip/flate today) and self-register via a package-level var initialiser when imported — no init().
Index ¶
Constants ¶
const CodeCompressedFrameInvalid errs.Code = 0x00_02_05_04 // 0.2.5.4
CodeCompressedFrameInvalid identifies a malformed compressed frame OR a tripped decompression-bomb guard (max output size / max expansion ratio). It is owned by the pkg/v1/codec frame layer (a later commit); declared here so the 0.2.5.* block is allocated in one place per ADR 0014.
const CodeCompressionFailed errs.Code = 0x00_02_05_02 // 0.2.5.2
CodeCompressionFailed identifies a Compress call whose underlying compressor returned an error — typically a writer fault while flushing the stream.
const CodeDecompressionFailed errs.Code = 0x00_02_05_03 // 0.2.5.3
CodeDecompressionFailed identifies a Decompress call whose underlying decompressor returned an error — malformed input or a truncated stream.
const CodeDuplicateRegistration errs.Code = 0x00_02_05_05 // 0.2.5.5
CodeDuplicateRegistration identifies a boot-time collision on the Compressor registry: a nil scheme, or a distinct scheme claiming an already-registered Algorithm. It is surfaced via panic at boot (see registry.go). Its reason is DUPLICATE_REGISTRATION so the bracket header "[<code> <REASON>]" stays a valid (code,reason) pairing per ADR 0005 §Semantics — mirroring the codec registry's CodeDuplicateRegistration (0.2.2.1).
const CodeUnknownCompressor errs.Code = 0x00_02_05_01 // 0.2.5.1
CodeUnknownCompressor identifies a Lookup/Decompress call naming an Algorithm that no imported package has registered. It is also surfaced via panic at boot on a duplicate registration (see registry.go), not only as a sentinel.
Variables ¶
var ( // UnknownCompressor is returned when no Compressor is registered under the // requested Algorithm — typically a missing blank-import of the scheme. UnknownCompressor = errs.Define(CodeUnknownCompressor, "UNKNOWN_COMPRESSOR", "No compressor is registered under that algorithm", "core/transform.Lookup: algorithm absent from registry; blank-import the scheme's package to register it") // CompressionFailed wraps a failure from a compressor's underlying writer // (e.g. compress/gzip or compress/flate) while encoding the payload. CompressionFailed = errs.Define(CodeCompressionFailed, "COMPRESSION_FAILED", "Compression failed", "core/transform.Compress: the underlying compressor returned an error", errs.WithExitCode(exitDataErr)) // DecompressionFailed wraps a failure from a decompressor's underlying // reader while decoding the payload — malformed or truncated input. DecompressionFailed = errs.Define(CodeDecompressionFailed, "DECOMPRESSION_FAILED", "Decompression failed", "core/transform.Decompress: the underlying decompressor returned an error", errs.WithExitCode(exitDataErr)) // CompressedFrameInvalid is returned for a malformed compressed frame or a // tripped decompression-bomb guard. The pkg/v1/codec frame layer (a later // commit) is its emitter; defined here so the 0.2.5.* block lands in one place. CompressedFrameInvalid = errs.Define(CodeCompressedFrameInvalid, "COMPRESSED_FRAME_INVALID", "Compressed frame is malformed or exceeds the safety bound", "core/transform: compressed-frame header is malformed or the decompression-bomb guard tripped", errs.WithExitCode(exitDataErr)) // DuplicateRegistration is the boot-time panic sentinel for the Compressor // registry: a nil scheme or a distinct scheme claiming a taken Algorithm. Its // reason matches the bracket-header word so code 0.2.5.5 resolves to // DUPLICATE_REGISTRATION — never the unrelated UNKNOWN_COMPRESSOR (0.2.5.1). DuplicateRegistration = errs.Define(CodeDuplicateRegistration, "DUPLICATE_REGISTRATION", "A compressor is already registered under that algorithm", "core/transform.Register: a distinct scheme already claims this algorithm, or a nil scheme was supplied") )
Functions ¶
This section is empty.
Types ¶
type Algorithm ¶
type Algorithm string
Algorithm is the typed key under which a Compressor registers (e.g. "gzip", "flate"). The zero value Algorithm("") is reserved invalid, mirroring codec.Format and crypto.Algorithm.
func Available ¶
func Available() []Algorithm
Available returns the sorted list of registered Algorithms.
type Compressor ¶
type Compressor interface {
Algorithm() Algorithm
Compress(dst, src []byte) (out []byte, err error)
Decompress(dst, src []byte) (out []byte, err error)
}
Compressor is the contract every byte-transform scheme satisfies. Instances MUST be safe for concurrent use; scheme-specific options are supplied via the scheme's constructor, not via the Compressor interface. Compress and Decompress follow the append-to-dst convention of the stdlib (dst may be nil) so callers can reuse buffers on the hot path.
IFACE-PLUGIN: the registry stores plug-in scheme instances behind this interface — concrete scheme types stay unexported per package.
func Lookup ¶
func Lookup(name Algorithm) (c Compressor, ok bool)
Lookup returns the Compressor registered under name.
IFACE-PLUGIN: the registry stores plug-in scheme instances behind the Compressor interface — concrete types are intentionally unexported per scheme.
func Register ¶
func Register(c Compressor) Compressor
Register inserts c into the registry under c.Algorithm() and returns it so callers can bind the singleton to a typed package-level variable like `var GzipCompressor = transform.Register(gzipCompressor{})`. Panics on a nil scheme or when a distinct scheme already claims the same Algorithm.
IFACE-PLUGIN: the registry hands plug-in Compressor instances back to callers so each scheme keeps its concrete type unexported; the stable contract is the Compressor interface itself.
Source Files