codec

package
v0.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 21, 2026 License: MIT Imports: 7 Imported by: 0

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/data/codec facade; concrete implementations live in internal/service/data/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/data/codec block).

Package codec — declares the registry's boot-time sentinel. Its var name equals its errs.Define Reason in SCREAMING_SNAKE form.

Package codec — declares the typed Format string and its helpers. The zero Format ("") is invalid — consumers obtain a Format via the pkg/v1/data/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

View Source 
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.

View Source 
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.

View Source 
const CodeEmptyInput errs.Code = 0x00_02_02_02 // 0.2.2.2

CodeEmptyInput identifies Unmarshal being called with a zero-byte slice.

View Source 
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.

View Source 
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

View Source 
var DuplicateRegistration = errs.Static(CodeDuplicateRegistration, "DUPLICATE_REGISTRATION",
	"A codec is already registered under that name, MIME type or extension",
	"core/data/codec.Register: a distinct codec already holds this Format name, MIME type or extension",
	0,
	0)

DuplicateRegistration is the conflict Register refuses at boot: a distinct codec already holds the Format name, MIME type or extension a second one claims. It is never returned — Register panics with conflictText of it, so the panic carries the dotted-quad header AND the key that collided.

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 

func Lookup(f Format) (c Codec, ok bool)

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 

func LookupExt(ext string) (c Codec, ok bool)

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 

func LookupMIME(raw string) (c Codec, ok bool)

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 

func Register(c Codec) Codec

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.

"Nil" here means UNUSABLE, not only an untyped nil: a typed nil pointer and a plug-in whose type is not comparable both satisfy the port and neither can serve one call (see internal/kernel/plugin).

type Decoder 

type Decoder interface {
	Decode(v any) (err error)
	More() (ok bool)
}

Decoder reads one or more values from the wrapped reader.

type Encoder 

type Encoder interface {
	Encode(v any) (err error)
	Close() (err error)
}

Encoder writes one or more values to the wrapped writer.

type Format 

type Format string

Format is the typed string identifier of a codec.

func Available 

func Available() []Format

Available returns the sorted list of registered Formats, or nil before any Register.

func (Format) Known 

func (f Format) Known() bool

Known reports whether f has been registered in the codec registry.

func (Format) String 

func (f Format) String() string

String implements fmt.Stringer and returns the raw identifier.

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

View all Source files

Directories

Path Synopsis
Package asn1 declares the error codes and the sentinels of the ASN.1 DER codec, internal/service/data/codec/asn1 — range 0.3.9.* (ADR 0005 service/data/codec/asn1 block).
 Package asn1 declares the error codes and the sentinels of the ASN.1 DER codec, internal/service/data/codec/asn1 — range 0.3.9.* (ADR 0005 service/data/codec/asn1 block).
Package baseenc declares the error codes and the sentinels of the base-N codec family (base64, base64url, base32, base16, hex, ascii85, base45, base58, base62), internal/service/data/codec/baseenc — range 0.3.24.* (ADR 0006 service/data/codec/baseenc block).
 Package baseenc declares the error codes and the sentinels of the base-N codec family (base64, base64url, base32, base16, hex, ascii85, base45, base58, base62), internal/service/data/codec/baseenc — range 0.3.24.* (ADR 0006 service/data/codec/baseenc block).
Package bson declares the error codes and the sentinels of the BSON codec, internal/service/data/codec/bson — range 0.3.36.* (ADR 0021 service/data/codec/bson block).
 Package bson declares the error codes and the sentinels of the BSON codec, internal/service/data/codec/bson — range 0.3.36.* (ADR 0021 service/data/codec/bson block).
Package cbor declares the error codes and the sentinels of the CBOR codec, internal/service/data/codec/cbor — range 0.3.6.* (ADR 0005 service/data/codec/cbor block).
 Package cbor declares the error codes and the sentinels of the CBOR codec, internal/service/data/codec/cbor — range 0.3.6.* (ADR 0005 service/data/codec/cbor block).
Package csv declares the error codes and the sentinels of the CSV codec, internal/service/data/codec/csv — range 0.3.8.* (ADR 0005 service/data/codec/csv block).
 Package csv declares the error codes and the sentinels of the CSV codec, internal/service/data/codec/csv — range 0.3.8.* (ADR 0005 service/data/codec/csv block).
Package flatbuffers declares the error codes and the sentinels of the FlatBuffers passthrough codec, internal/service/data/codec/flatbuffers — range 0.3.23.* (ADR 0006 service/data/codec/flatbuffers block).
 Package flatbuffers declares the error codes and the sentinels of the FlatBuffers passthrough codec, internal/service/data/codec/flatbuffers — range 0.3.23.* (ADR 0006 service/data/codec/flatbuffers block).
Package form declares the error codes and the sentinels of the application/x-www-form-urlencoded codec, internal/service/data/codec/form — range 0.3.40.* (ADR 0005 service/data/codec/form block).
 Package form declares the error codes and the sentinels of the application/x-www-form-urlencoded codec, internal/service/data/codec/form — range 0.3.40.* (ADR 0005 service/data/codec/form block).
Package json declares the error codes and the sentinels of the JSON codec, internal/service/data/codec/json — range 0.3.2.* (ADR 0005 service/data/codec/json block).
 Package json declares the error codes and the sentinels of the JSON codec, internal/service/data/codec/json — range 0.3.2.* (ADR 0005 service/data/codec/json block).
Package jsonpatch declares the error codes and the sentinels of the JSON-difference package (RFC 6902 operations, not a codec), internal/service/data/codec/jsonpatch — range 0.3.90.* (ADR 0143 service/data/codec/jsonpatch block).
 Package jsonpatch declares the error codes and the sentinels of the JSON-difference package (RFC 6902 operations, not a codec), internal/service/data/codec/jsonpatch — range 0.3.90.* (ADR 0143 service/data/codec/jsonpatch block).
Package msgpack declares the error codes and the sentinels of the MessagePack codec, internal/service/data/codec/msgpack — range 0.3.7.* (ADR 0005 service/data/codec/msgpack block).
 Package msgpack declares the error codes and the sentinels of the MessagePack codec, internal/service/data/codec/msgpack — range 0.3.7.* (ADR 0005 service/data/codec/msgpack block).
Package multipart declares the error codes and the sentinels of the multipart/form-data codec, internal/service/data/codec/multipart — range 0.3.41.* (ADR 0005 service/data/codec/multipart block).
 Package multipart declares the error codes and the sentinels of the multipart/form-data codec, internal/service/data/codec/multipart — range 0.3.41.* (ADR 0005 service/data/codec/multipart block).
Package ndjson declares the error codes and the sentinels of the NDJSON codec, internal/service/data/codec/ndjson — range 0.3.11.* (ADR 0005 service/data/codec/ndjson block).
 Package ndjson declares the error codes and the sentinels of the NDJSON codec, internal/service/data/codec/ndjson — range 0.3.11.* (ADR 0005 service/data/codec/ndjson block).
Package pem declares the error codes and the sentinels of the PEM codec, internal/service/data/codec/pem — range 0.3.10.* (ADR 0005 service/data/codec/pem block).
 Package pem declares the error codes and the sentinels of the PEM codec, internal/service/data/codec/pem — range 0.3.10.* (ADR 0005 service/data/codec/pem block).
Package scratch provides shared, size-bounded recycling primitives for the service codecs.
 Package scratch provides shared, size-bounded recycling primitives for the service codecs.
Package strictjson declares the error codes and the sentinels of the strict JSON decoder (not a codec), internal/service/data/codec/strictjson — range 0.3.72.* (ADR 0102 service/data/codec/strictjson block).
 Package strictjson declares the error codes and the sentinels of the strict JSON decoder (not a codec), internal/service/data/codec/strictjson — range 0.3.72.* (ADR 0102 service/data/codec/strictjson block).
Package tlv declares the error codes and the sentinels of the TLV codec, internal/service/data/codec/tlv — range 0.3.22.* (ADR 0006 service/data/codec/tlv block).
 Package tlv declares the error codes and the sentinels of the TLV codec, internal/service/data/codec/tlv — range 0.3.22.* (ADR 0006 service/data/codec/tlv block).
Package toml declares the error codes and the sentinels of the TOML codec, internal/service/data/codec/toml — range 0.3.5.* (ADR 0005 service/data/codec/toml block).
 Package toml declares the error codes and the sentinels of the TOML codec, internal/service/data/codec/toml — range 0.3.5.* (ADR 0005 service/data/codec/toml block).
Package xml declares the error codes and the sentinels of the XML codec, internal/service/data/codec/xml — range 0.3.3.* (ADR 0005 service/data/codec/xml block).
 Package xml declares the error codes and the sentinels of the XML codec, internal/service/data/codec/xml — range 0.3.3.* (ADR 0005 service/data/codec/xml block).
Package yaml declares the error codes and the sentinels of the YAML codec, internal/service/data/codec/yaml — range 0.3.4.* (ADR 0005 service/data/codec/yaml block).
 Package yaml declares the error codes and the sentinels of the YAML codec, internal/service/data/codec/yaml — range 0.3.4.* (ADR 0005 service/data/codec/yaml block).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.