bson

bson

import "github.com/kitsunium/sdk/pkg/v1/data/codec/bson"

Package bson is BSON, MongoDB's binary document format, implemented with the standard library alone. Importing it registers the BSON codec with the SDK's codec registry — and no other codec (ADR 0134) — and names the Go types the BSON values Go has no type of its own for decode into:

import "github.com/kitsunium/sdk/pkg/v1/data/codec/bson"

data, err := bson.Marshal(bson.D{{Key: "name", Value: "kitsune"}, {Key: "tails", Value: 9}})
var doc map[string]any
err = bson.Unmarshal(data, &doc) // doc["tails"] is an int32

Everything that dispatches through the registry by format name reads and writes BSON as well: the codec package's Marshal and Unmarshal under Format, config.FSSource, i18n.LoadFS. Importing it beside github.com/kitsunium/sdk/pkg/v1/data/codec is harmless: the format is registered once.

Mapping

The top level is a document: a struct, a map, a D; anything else is refused. Struct fields take the tag bson:"name,omitempty,minsize,truncate,inline" and default to the field name in lower case. int, int8, int16, int32, uint8 and uint16 are written as int32 (int as int64 when it does not fit), int64, uint, uint32 and uint64 as int64, floats as double, []byte as a generic binary, time.Time as a UTC datetime in milliseconds, a nil slice, map or pointer as null, and map keys in sorted order, so the same value always encodes to the same bytes. A type can write and read itself through MarshalBSON() ([]byte, error) and UnmarshalBSON([]byte) error.

Decoding into an interface gives float64, int32, int64, string, bool, nil, A for an array, DateTime, Binary, ObjectID, Decimal128 and the other value types below — and, for a document, a D when decoding into *any, a map[string]any when decoding into a map[string]any. Numbers decode into any numeric field they fit, a double into an integer only when whole unless the field is tagged truncate.

Safety

Unmarshal checks the whole input before it writes anything: one document, at most 10 MiB, every declared length within the bytes there are, every string UTF-8, nested at most 100 levels. A malformed document is refused whole. Marshal refuses what BSON cannot hold — a string that is not UTF-8, a uint64 past the int64 range, a cyclic value — instead of writing something a reader would refuse.

Errors

Failures carry the range 0.3.36.*; match them with errs.HasCode:

CodeMarshalFailed     0.3.36.1  a value with no BSON form, or a top level that is not a document
CodeUnmarshalFailed   0.3.36.2  malformed input, or a value the target cannot hold
CodeSizeExceeded      0.3.36.3  an input past 10 MiB
CodeDepthExceeded     0.3.36.4  nesting past 100 levels, either way
CodeValueInvalid      0.3.36.5  ObjectIDFromHex, ParseDecimal128 and the JSON forms refusing their input

No error message quotes a key or a value from the input.

Index

• Constants
• Variables
• func Append(dst []byte, v any) ([]byte, error)
• func Marshal(v any) ([]byte, error)
• func Unmarshal(data []byte, v any) error
• type A
• type Binary
• type CodeWithScope
• type D
• type DBPointer
• type DateTime
  • func NewDateTimeFromTime(t time.Time) DateTime
• type Decimal128
  • func NewDecimal128(high, low uint64) Decimal128
  • func ParseDecimal128(s string) (Decimal128, error)
• type E
• type JavaScript
• type M
• type MaxKey
• type MinKey
• type Null
• type ObjectID
  • func ObjectIDFromHex(s string) (ObjectID, error)
• type Regex
• type Symbol
• type Timestamp
• type Undefined

Constants

The binary subtypes.

const (
    // BinaryGeneric is the default subtype, the one a []byte is written as.
    BinaryGeneric byte = svcbson.BinaryGeneric
    // BinaryFunction marks a function.
    BinaryFunction byte = svcbson.BinaryFunction
    // BinaryOld is the deprecated generic subtype, with an inner length.
    BinaryOld byte = svcbson.BinaryOld
    // BinaryUUIDOld is the deprecated, byte-order-ambiguous UUID subtype.
    BinaryUUIDOld byte = svcbson.BinaryUUIDOld
    // BinaryUUID is an RFC 9562 UUID.
    BinaryUUID byte = svcbson.BinaryUUID
    // BinaryMD5 is an MD5 digest.
    BinaryMD5 byte = svcbson.BinaryMD5
    // BinaryEncrypted is a client-side encrypted value.
    BinaryEncrypted byte = svcbson.BinaryEncrypted
    // BinaryColumn is a compressed time-series column.
    BinaryColumn byte = svcbson.BinaryColumn
    // BinarySensitive marks data a server must not log.
    BinarySensitive byte = svcbson.BinarySensitive
    // BinaryVector is a packed numeric vector.
    BinaryVector byte = svcbson.BinaryVector
    // BinaryUserDefined is the first subtype reserved for applications.
    BinaryUserDefined byte = svcbson.BinaryUserDefined
)

The error codes, range 0.3.36.*.

const (
    // CodeMarshalFailed identifies a value Marshal or Append cannot encode.
    CodeMarshalFailed errs.Code = corebson.CodeBSONMarshalFailed
    // CodeUnmarshalFailed identifies input Unmarshal refuses.
    CodeUnmarshalFailed errs.Code = corebson.CodeBSONUnmarshalFailed
    // CodeSizeExceeded identifies an Unmarshal input past 10 MiB.
    CodeSizeExceeded errs.Code = corebson.CodeBSONSizeExceeded
    // CodeDepthExceeded identifies nesting past 100 levels.
    CodeDepthExceeded errs.Code = corebson.CodeBSONDepthExceeded
    // CodeValueInvalid identifies a value type's constructor or parser
    // refusing its input.
    CodeValueInvalid errs.Code = corebson.CodeBSONValueInvalid
)

Format is the name BSON is registered under. It is an untyped constant, so it goes wherever a format name is taken — the codec package's Marshal, config.FSSource's string, i18n.LoadFS's codec.Format — without a conversion.

const Format = "bson"

Variables

The sentinels, for errors.Is, and the nil ObjectID.

var (
    // MarshalFailed marks a value Marshal or Append cannot encode.
    MarshalFailed = corebson.MarshalFailed
    // UnmarshalFailed marks input Unmarshal refuses.
    UnmarshalFailed = corebson.UnmarshalFailed
    // SizeExceeded marks an Unmarshal input past 10 MiB.
    SizeExceeded = corebson.SizeExceeded
    // DepthExceeded marks nesting past 100 levels.
    DepthExceeded = corebson.DepthExceeded
    // ValueInvalid marks a value type's constructor or parser refusing its input.
    ValueInvalid = corebson.ValueInvalid
    // NilObjectID is the zero ObjectID.
    NilObjectID ObjectID
)

func Append

func Append(dst []byte, v any) ([]byte, error)

Append encodes v and appends the document to dst; a dst with room allocates nothing. On failure dst is returned with its original length.

func Marshal

func Marshal(v any) ([]byte, error)

Marshal encodes v, which must encode as a document, into a slice the caller owns.

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal decodes one BSON document into v, a non-nil pointer or map. The input is checked whole before v is written.

type A

A is an array.

type A = svcbson.A

type Binary

Binary is bytes and the subtype naming what they are.

type Binary = svcbson.Binary

type CodeWithScope

CodeWithScope is the deprecated JavaScript with its scope document.

type CodeWithScope = svcbson.CodeWithScope

type D

D is a document whose element order matters.

type D = svcbson.D

type DBPointer

DBPointer is the deprecated namespace-and-ObjectID pointer.

type DBPointer = svcbson.DBPointer

type DateTime

DateTime is milliseconds since the Unix epoch, UTC.

type DateTime = svcbson.DateTime

func NewDateTimeFromTime

func NewDateTimeFromTime(t time.Time) DateTime

NewDateTimeFromTime returns the DateTime t falls in, truncated to the millisecond.

type Decimal128

Decimal128 is an IEEE 754-2008 128-bit decimal, converted exactly or not at all.

type Decimal128 = svcbson.Decimal128

func NewDecimal128

func NewDecimal128(high, low uint64) Decimal128

NewDecimal128 returns the decimal whose BID encoding is high (the first eight bytes) and low (the last eight).

func ParseDecimal128

func ParseDecimal128(s string) (Decimal128, error)

ParseDecimal128 parses a decimal's string form — "1.23", "-4E+5", "NaN", "Infinity" — refusing one a decimal128 cannot hold exactly.

type E

E is one element of a D.

type E = svcbson.E

type JavaScript

JavaScript is JavaScript code.

type JavaScript = svcbson.JavaScript

type M

M is a document whose element order does not; its keys are written sorted.

type M = svcbson.M

type MaxKey

MaxKey sorts higher than every other value.

type MaxKey = svcbson.MaxKey

type MinKey

MinKey sorts lower than every other value.

type MinKey = svcbson.MinKey

type Null

Null is an explicit null, for a D.

type Null = svcbson.Null

type ObjectID

ObjectID is the twelve-byte identifier; its text and JSON forms are 24 hexadecimal digits.

type ObjectID = svcbson.ObjectID

func ObjectIDFromHex

func ObjectIDFromHex(s string) (ObjectID, error)

ObjectIDFromHex parses the 24-digit hexadecimal form of an ObjectID, in either case.

type Regex

Regex is a pattern and its options.

type Regex = svcbson.Regex

type Symbol

Symbol is the deprecated symbol.

type Symbol = svcbson.Symbol

type Timestamp

Timestamp is the replication timestamp: seconds and an increment.

type Timestamp = svcbson.Timestamp

type Undefined

Undefined is the deprecated undefined value.

type Undefined = svcbson.Undefined

Generated by gomarkdoc