mirror of
https://github.com/go-gitea/gitea.git
synced 2024-08-30 16:17:28 +02:00
149 lines
5.3 KiB
Markdown
149 lines
5.3 KiB
Markdown
|
# Codec
|
||
|
|
||
|
High Performance, Feature-Rich Idiomatic Go codec/encoding library for
|
||
|
binc, msgpack, cbor, json.
|
||
|
|
||
|
Supported Serialization formats are:
|
||
|
|
||
|
- msgpack: https://github.com/msgpack/msgpack
|
||
|
- binc: http://github.com/ugorji/binc
|
||
|
- cbor: http://cbor.io http://tools.ietf.org/html/rfc7049
|
||
|
- json: http://json.org http://tools.ietf.org/html/rfc7159
|
||
|
- simple:
|
||
|
|
||
|
To install:
|
||
|
|
||
|
go get github.com/ugorji/go/codec
|
||
|
|
||
|
This package understands the `unsafe` tag, to allow using unsafe semantics:
|
||
|
|
||
|
- When decoding into a struct, you need to read the field name as a string
|
||
|
so you can find the struct field it is mapped to.
|
||
|
Using `unsafe` will bypass the allocation and copying overhead of `[]byte->string` conversion.
|
||
|
|
||
|
To use it, you must pass the `unsafe` tag during install:
|
||
|
|
||
|
```
|
||
|
go install -tags=unsafe github.com/ugorji/go/codec
|
||
|
```
|
||
|
|
||
|
Online documentation: http://godoc.org/github.com/ugorji/go/codec
|
||
|
Detailed Usage/How-to Primer: http://ugorji.net/blog/go-codec-primer
|
||
|
|
||
|
The idiomatic Go support is as seen in other encoding packages in
|
||
|
the standard library (ie json, xml, gob, etc).
|
||
|
|
||
|
Rich Feature Set includes:
|
||
|
|
||
|
- Simple but extremely powerful and feature-rich API
|
||
|
- Very High Performance.
|
||
|
Our extensive benchmarks show us outperforming Gob, Json, Bson, etc by 2-4X.
|
||
|
- Multiple conversions:
|
||
|
Package coerces types where appropriate
|
||
|
e.g. decode an int in the stream into a float, etc.
|
||
|
- Corner Cases:
|
||
|
Overflows, nil maps/slices, nil values in streams are handled correctly
|
||
|
- Standard field renaming via tags
|
||
|
- Support for omitting empty fields during an encoding
|
||
|
- Encoding from any value and decoding into pointer to any value
|
||
|
(struct, slice, map, primitives, pointers, interface{}, etc)
|
||
|
- Extensions to support efficient encoding/decoding of any named types
|
||
|
- Support encoding.(Binary|Text)(M|Unm)arshaler interfaces
|
||
|
- Decoding without a schema (into a interface{}).
|
||
|
Includes Options to configure what specific map or slice type to use
|
||
|
when decoding an encoded list or map into a nil interface{}
|
||
|
- Encode a struct as an array, and decode struct from an array in the data stream
|
||
|
- Comprehensive support for anonymous fields
|
||
|
- Fast (no-reflection) encoding/decoding of common maps and slices
|
||
|
- Code-generation for faster performance.
|
||
|
- Support binary (e.g. messagepack, cbor) and text (e.g. json) formats
|
||
|
- Support indefinite-length formats to enable true streaming
|
||
|
(for formats which support it e.g. json, cbor)
|
||
|
- Support canonical encoding, where a value is ALWAYS encoded as same sequence of bytes.
|
||
|
This mostly applies to maps, where iteration order is non-deterministic.
|
||
|
- NIL in data stream decoded as zero value
|
||
|
- Never silently skip data when decoding.
|
||
|
User decides whether to return an error or silently skip data when keys or indexes
|
||
|
in the data stream do not map to fields in the struct.
|
||
|
- Encode/Decode from/to chan types (for iterative streaming support)
|
||
|
- Drop-in replacement for encoding/json. `json:` key in struct tag supported.
|
||
|
- Provides a RPC Server and Client Codec for net/rpc communication protocol.
|
||
|
- Handle unique idiosynchracies of codecs e.g.
|
||
|
- For messagepack, configure how ambiguities in handling raw bytes are resolved
|
||
|
- For messagepack, provide rpc server/client codec to support
|
||
|
msgpack-rpc protocol defined at:
|
||
|
https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
|
||
|
|
||
|
## Extension Support
|
||
|
|
||
|
Users can register a function to handle the encoding or decoding of
|
||
|
their custom types.
|
||
|
|
||
|
There are no restrictions on what the custom type can be. Some examples:
|
||
|
|
||
|
type BisSet []int
|
||
|
type BitSet64 uint64
|
||
|
type UUID string
|
||
|
type MyStructWithUnexportedFields struct { a int; b bool; c []int; }
|
||
|
type GifImage struct { ... }
|
||
|
|
||
|
As an illustration, MyStructWithUnexportedFields would normally be
|
||
|
encoded as an empty map because it has no exported fields, while UUID
|
||
|
would be encoded as a string. However, with extension support, you can
|
||
|
encode any of these however you like.
|
||
|
|
||
|
## RPC
|
||
|
|
||
|
RPC Client and Server Codecs are implemented, so the codecs can be used
|
||
|
with the standard net/rpc package.
|
||
|
|
||
|
## Usage
|
||
|
|
||
|
Typical usage model:
|
||
|
|
||
|
// create and configure Handle
|
||
|
var (
|
||
|
bh codec.BincHandle
|
||
|
mh codec.MsgpackHandle
|
||
|
ch codec.CborHandle
|
||
|
)
|
||
|
|
||
|
mh.MapType = reflect.TypeOf(map[string]interface{}(nil))
|
||
|
|
||
|
// configure extensions
|
||
|
// e.g. for msgpack, define functions and enable Time support for tag 1
|
||
|
// mh.SetExt(reflect.TypeOf(time.Time{}), 1, myExt)
|
||
|
|
||
|
// create and use decoder/encoder
|
||
|
var (
|
||
|
r io.Reader
|
||
|
w io.Writer
|
||
|
b []byte
|
||
|
h = &bh // or mh to use msgpack
|
||
|
)
|
||
|
|
||
|
dec = codec.NewDecoder(r, h)
|
||
|
dec = codec.NewDecoderBytes(b, h)
|
||
|
err = dec.Decode(&v)
|
||
|
|
||
|
enc = codec.NewEncoder(w, h)
|
||
|
enc = codec.NewEncoderBytes(&b, h)
|
||
|
err = enc.Encode(v)
|
||
|
|
||
|
//RPC Server
|
||
|
go func() {
|
||
|
for {
|
||
|
conn, err := listener.Accept()
|
||
|
rpcCodec := codec.GoRpc.ServerCodec(conn, h)
|
||
|
//OR rpcCodec := codec.MsgpackSpecRpc.ServerCodec(conn, h)
|
||
|
rpc.ServeCodec(rpcCodec)
|
||
|
}
|
||
|
}()
|
||
|
|
||
|
//RPC Communication (client side)
|
||
|
conn, err = net.Dial("tcp", "localhost:5555")
|
||
|
rpcCodec := codec.GoRpc.ClientCodec(conn, h)
|
||
|
//OR rpcCodec := codec.MsgpackSpecRpc.ClientCodec(conn, h)
|
||
|
client := rpc.NewClientWithCodec(rpcCodec)
|
||
|
|