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
Documentation
¶
Overview ¶
Package codec — declares the optional Appender extension that hot-path encoders (NDJSON, JSON, text) implement so callers can write into a caller-supplied buffer without paying for an intermediate allocation.
Codecs that satisfy Codec but do NOT implement Appender remain valid; the logger and other consumers detect support with a runtime type assertion and fall back to Marshal + copy when the optional interface is absent.
Package codec declares the domain contracts every format codec in the SDK implements. Consumers interact with codecs through the pkg/v1/codec facade; concrete implementations live in internal/service/codec/<format>/.
This package is interface-only: no runtime state, no registrations, no format-specific knowledge. Codecs register themselves via the registry in registry.go when their service subpackage is imported.
Package codec — range 0.2.2.* (ADR 0005 core/codec block).
Package codec — declares the typed Format string and its helpers. The zero Format ("") is invalid — consumers obtain a Format via the pkg/v1/codec constants or via the FromMIME / FromExtension helpers.
Package codec — holds the process-wide Codec registry. Service-level codec packages register themselves via package-level var initialisers when the package is imported.
Index ¶
Constants ¶
const CodeCodecNil errs.Code = 0x00_02_02_05 // 0.2.2.5
CodeCodecNil identifies a Register call made with a nil Codec — a nil-argument programmer error distinct from a duplicate registration. Surfaced via panic at boot (see registry.go), mirroring writer.CodeWriterNil.
const CodeDuplicateRegistration errs.Code = 0x00_02_02_01 // 0.2.2.1
CodeDuplicateRegistration identifies an init-time collision on the codec registry; two codecs tried to claim the same Name.
const CodeEmptyInput errs.Code = 0x00_02_02_02 // 0.2.2.2
CodeEmptyInput identifies Unmarshal being called with a zero-byte slice.
const CodeTargetInvalid errs.Code = 0x00_02_02_03 // 0.2.2.3
CodeTargetInvalid identifies Unmarshal being called with a target that is not a non-nil pointer to a storable value.
const CodeValueInvalid errs.Code = 0x00_02_02_04 // 0.2.2.4
CodeValueInvalid identifies Marshal being called on a value the codec cannot serialise (channel, function, unsupported map key).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Appender ¶
type Appender interface {
Codec
// Append encodes v and appends the bytes onto dst. The returned slice
// MUST contain the prior contents of dst followed by the encoded form.
Append(dst []byte, v any) (out []byte, err error)
}
Appender is the optional extension implemented by codecs that can encode directly into a caller-supplied byte slice instead of allocating their own. Hot paths (logger record formatting, NDJSON streams, batch sinks) consume this interface to avoid the buffer-copy cost imposed by Marshal.
Implementations MUST:
- Append the encoded representation of v onto dst (typically via the standard append(dst, …) idiom).
- Return the (possibly re-allocated) buffer back to the caller.
- Be safe for concurrent use by multiple goroutines.
The returned buffer's length grows by the number of bytes written; the underlying array MAY be a fresh allocation when dst's capacity is too small. Callers retain ownership of dst and SHOULD reuse it across calls.
type Codec ¶
type Codec interface {
Name() string
MIMETypes() []string
Extensions() []string
Marshal(v any) (data []byte, err error)
Unmarshal(data []byte, v any) (err error)
}
Codec is the minimum contract every format codec satisfies. Instances MUST be safe for concurrent use; format-specific options are supplied via the codec's constructor, not via the Codec interface.
func Lookup ¶
Lookup returns the codec registered under f.
IFACE-PLUGIN: the registry stores plug-in codec instances behind the Codec interface — concrete types are intentionally unexported per-format.
func LookupExt ¶
LookupExt returns the codec whose extension list contains ext.
IFACE-PLUGIN: the registry stores plug-in codec instances behind the Codec interface — concrete types are intentionally unexported per-format.
func LookupMIME ¶
LookupMIME returns the codec whose MIME list matches. MIME parameters (e.g. "; charset=utf-8") are stripped before the index lookup so that "application/json; charset=utf-8" resolves like "application/json".
IFACE-PLUGIN: the registry stores plug-in codec instances behind the Codec interface — concrete types are intentionally unexported per-format.
func Register ¶
Register inserts c into the registry and returns it so callers can bind the singleton to a typed package-level variable like `var Codec codec.Codec = codec.Register(&jsonCodec{})`. Panics on nil argument or duplicate Name / MIME / extension.
IFACE-PLUGIN: the registry hands plug-in codec instances back to callers so each domain can keep its concrete codec type unexported; the only stable contract is the Codec interface itself.
type Format ¶
type Format string
Format is the typed string identifier of a codec.
type StreamingCodec ¶
type StreamingCodec interface {
Codec
NewEncoder(w io.Writer) Encoder
NewDecoder(r io.Reader) Decoder
}
StreamingCodec is the optional extension for formats that support incremental encode/decode over io.Writer / io.Reader. Codecs that CAN stream SHOULD implement it; consumers detect support with a type assertion.
Source Files
Directories