restlicodec

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Mar 2, 2022 License: BSD-2-Clause Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const WildCard = "*"

Variables

This section is empty.

Functions

func ReadArray added in v1.0.0 

func ReadArray[V any](reader Reader, unmarshaler GenericUnmarshaler[V]) (result []V, err error)

func ReadMap added in v1.0.0 

func ReadMap[V any](reader Reader, unmarshaler GenericUnmarshaler[V]) (result map[string]V, err error)

func Ror2PathEscape added in v0.26.2 

func Ror2PathEscape(s string) string

Ror2PathEscape path-escapes the given string using Rest.li's rather opinionated path escaper. The list of unescaped characters was generated directly from the Java code by enumerating all UTF-8 characters and escaping them. Turns out the only differences are that '!' and '*' aren't escaped (while url.PathEscape does) and ':' isn't escaped by url.PathEscape but the Rest.li escaper escapes it.

func Ror2QueryEscape added in v0.26.5 

func Ror2QueryEscape(s string) string

Ror2QueryEscape query-escapes the given string using Rest.li's query escaper (same as Ror2PathEscape). Using the same technique of generating all the UTF8 characters, a handful of characters were found to be escaped differently than how a normal query encoder would do it.

func WriteArray added in v1.0.0 

func WriteArray[T any](writer Writer, array []T, marshaler GenericMarshaler[T]) (err error)

func WriteMap added in v1.0.0 

func WriteMap[T any](writer Writer, entries map[string]T, marshaler GenericMarshaler[T]) (err error)

func WriteObjectArray added in v1.0.0 

func WriteObjectArray[T Marshaler](writer Writer, array []T) error

func WriteObjectMap added in v1.0.0 

func WriteObjectMap[T Marshaler](writer Writer, entries map[string]T) error

func WritePrimitiveArray added in v1.0.0 

func WritePrimitiveArray[T Primitive](writer Writer, array []T, marshaler PrimitiveMarshaler[T]) error

func WritePrimitiveMap added in v1.0.0 

func WritePrimitiveMap[T Primitive](writer Writer, entries map[string]T, marshaler PrimitiveMarshaler[T]) error

Types

type ArrayReader added in v0.19.0 

type ArrayReader func(reader Reader) (err error)

type ArrayWriter added in v0.19.0 

type ArrayWriter func(itemWriter func() Writer) (err error)

type Closer 

type Closer interface {
	// Finalize returns the created object as a string and releases the pooled underlying buffer. Subsequent calls will
	// return the empty string
	Finalize() string
	// ReadCloser returns an io.ReadCloser that will read the pooled underlying buffer, releasing each byte back into
	// the pool as they are read. Close will release any remaining unread bytes to the pool.
	ReadCloser() io.ReadCloser
	// Size returns the size of the data that was written out. Note that calling Size after Finalize or ReadCloser will
	// return 0
	Size() int
}

Closer provides methods for the underlying Writer to release its buffer and return the constructed objects to the caller. Note that once either Finalize or ReadCloser is called, subsequent calls to either will return the empty string or the empty reader respectively.

type ComparablePrimitive added in v1.0.0 

type ComparablePrimitive interface {
	int32 | int64 | float32 | float64 | bool | string
}

type DeserializationError added in v0.23.2 

type DeserializationError struct {
	Scope string
	Err   error
}

func (*DeserializationError) Error added in v0.23.2 

func (d *DeserializationError) Error() string

type GenericMarshaler added in v1.0.0 

type GenericMarshaler[T any] func(t T, writer Writer) error

type GenericUnmarshaler added in v1.0.0 

type GenericUnmarshaler[T any] func(reader Reader) (T, error)

type MapReader added in v0.19.0 

type MapReader func(reader Reader, field string) (err error)

type MapWriter added in v0.19.0 

type MapWriter func(keyWriter func(key string) Writer) (err error)

type Marshaler 

type Marshaler interface {
	MarshalRestLi(Writer) error
}

Marshaler is the interface that should be implemented by objects that can be serialized to JSON and ROR2

type MarshalerFunc added in v0.26.6 

type MarshalerFunc func(Writer) error

The MarshalerFunc type is an adapter to allow the use of ordinary functions as marshalers, useful for inlining marshalers instead of defining new types

func (MarshalerFunc) MarshalRestLi added in v0.26.6 

func (m MarshalerFunc) MarshalRestLi(writer Writer) error

type MissingRequiredFieldsError added in v0.23.2 

type MissingRequiredFieldsError struct {
	Fields []string
}

func (*MissingRequiredFieldsError) Error added in v0.23.2 

func (m *MissingRequiredFieldsError) Error() string

type NoopWriter added in v0.20.0 

type NoopWriter struct{}

func (NoopWriter) IsKeyExcluded added in v0.20.0 

func (n NoopWriter) IsKeyExcluded(string) bool

func (NoopWriter) SetScope added in v0.22.0 

func (n NoopWriter) SetScope(...string) Writer

func (NoopWriter) WriteArray added in v0.20.0 

func (n NoopWriter) WriteArray(ArrayWriter) error

func (NoopWriter) WriteBool added in v0.20.0 

func (n NoopWriter) WriteBool(bool)

func (NoopWriter) WriteBytes added in v0.20.0 

func (n NoopWriter) WriteBytes([]byte)

func (NoopWriter) WriteFloat32 added in v0.20.0 

func (n NoopWriter) WriteFloat32(float32)

func (NoopWriter) WriteFloat64 added in v0.20.0 

func (n NoopWriter) WriteFloat64(float64)

func (NoopWriter) WriteInt32 added in v0.20.0 

func (n NoopWriter) WriteInt32(int32)

func (NoopWriter) WriteInt64 added in v0.20.0 

func (n NoopWriter) WriteInt64(int64)

func (NoopWriter) WriteMap added in v0.20.0 

func (n NoopWriter) WriteMap(MapWriter) error

func (NoopWriter) WriteRawBytes added in v0.22.0 

func (n NoopWriter) WriteRawBytes([]byte)

func (NoopWriter) WriteString added in v0.20.0 

func (n NoopWriter) WriteString(string)

type PathSpec added in v0.20.0 

type PathSpec map[string]PathSpec
var NoExcludedFields PathSpec

func NewPathSpec added in v0.20.0 

func NewPathSpec(directives ...string) (p PathSpec)

func (PathSpec) Matches added in v0.20.0 

func (p PathSpec) Matches(path []string) bool

type Primitive added in v1.0.0 

type Primitive interface {
	ComparablePrimitive | []byte
}

type PrimitiveMarshaler added in v1.0.0 

type PrimitiveMarshaler[T Primitive] func(writer Writer, t T)

type PrimitiveReader 

type PrimitiveReader interface {
	ReadInt() (int, error)
	ReadInt32() (int32, error)
	ReadInt64() (int64, error)
	ReadFloat32() (float32, error)
	ReadFloat64() (float64, error)
	ReadBool() (bool, error)
	ReadString() (string, error)
	ReadBytes() ([]byte, error)
}

PrimitiveReader describes the set of functions that read the supported rest.li primitives from the input. Note that if the reader's next input is not a primitive (i.e. it is an object/map or an array), each of these methods will return errors. The encoding spec can be found here: https://linkedin.github.io/rest.li/how_data_is_serialized_for_transport

type PrimitiveWriter 

type PrimitiveWriter interface {
	WriteInt32(v int32)
	WriteInt64(v int64)
	WriteFloat32(v float32)
	WriteFloat64(v float64)
	WriteBool(v bool)
	WriteString(v string)
	WriteBytes(v []byte)
}

PrimitiveWriter provides the set of functions needed to write the supported rest.li primitives to the backing buffer, according to the rest.li serialization spec: https://linkedin.github.io/rest.li/how_data_is_serialized_for_transport.

type Reader 

type Reader interface {
	fmt.Stringer
	PrimitiveReader
	// ReadMap tells the Reader that it should expect a map/object as its next input. If it is not (e.g. it is an array
	// or a primitive) it will return an error.
	// Note that not using the inner Reader passed to the MapReader may result in undefined behavior.
	ReadMap(mapReader MapReader) error
	// ReadRecord tells the Reader that it should expect an object as its next input and calls recordReader for each
	// field of the object. If the next input is not an object, it will return an error.
	// Note that not using the inner Reader passed to the MapReader may result in undefined behavior.
	ReadRecord(requiredFields RequiredFields, recordReader MapReader) error
	// ReadArray tells the reader that it should expect an array as its next input. If it is not, it will return an
	// error
	// Note that not using the inner Reader passed to the ArrayReader may result in undefined behavior.
	ReadArray(arrayReader ArrayReader) error
	// ReadInterface reads an interface{} analogous to the 'encoding/json' package. It is a best-effort attempt to
	// deserialize the underlying data into map[string]interface{}, []interface{} or raw primitive types accordingly.
	// Note that for ROR2, because all primitives are encoded as strings, it is impossible to tell what the field's type
	// is intended to be without its schema. Therefore all primitive values are interpreted as strings
	ReadInterface() (interface{}, error)
	// ReadRawBytes returns the next primitive/array/map as a raw, unvalidated byte slice.
	ReadRawBytes() ([]byte, error)

	// Skip skips the next primitive/array/map completely.
	Skip() error
}

func NewJsonReader 

func NewJsonReader(data []byte) Reader

func NewRor2Reader 

func NewRor2Reader(data string) (Reader, error)

NewRor2Reader returns a new Reader that reads objects serialized using the rest.li protocol 2.0 object and array representation (ROR2), whose spec is defined here: https://linkedin.github.io/rest.li/spec/protocol#restli-protocol-20-object-and-listarray-representation Because the "reduced" URL encoding used for rest.li headers is a subset of the standard URL encoding, this Reader can be used for both the "full" URL encoding and the "reduced" URL encoding (though query parameters should be read with the reader returned by NewRor2QueryReader as there exist encoding differences, namely " " being encoding as `%20` and `+` respectively) An error will be returned if an upfront validation of the given string reveals it is not a valid ROR2 string. Note that if this function does not return an error, it does _not_ mean subsequent calls to the Read* functions will not return an error

type RequiredFields added in v1.0.0 

type RequiredFields []string

type RestLiQueryParamsReader added in v0.20.0 

type RestLiQueryParamsReader interface {
	ReadParams(paramsReader MapReader) error
}

func NewRestLiQueryParamsReader added in v0.20.0 

func NewRestLiQueryParamsReader(rawQuery string) RestLiQueryParamsReader

type RestLiQueryParamsWriter 

type RestLiQueryParamsWriter interface {
	WriteCloser
	WriteParams(paramsWriter MapWriter) error
}

func NewRestLiQueryParamsWriter 

func NewRestLiQueryParamsWriter() RestLiQueryParamsWriter

type Ror2PathWriter 

type Ror2PathWriter interface {
	Closer
	Writer
	RawPathSegment(segment string)
}

Ror2PathWriter is an ROR2 Writer that is intended to construct URLs for entities that are ROR2 encoded.

func NewRor2PathWriter 

func NewRor2PathWriter() Ror2PathWriter

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalRestLi(Reader) error
}

Unmarshaler is the interface that should be implemented by objects that can be deserialized from JSON and ROR2

type UnmarshalerFunc added in v0.26.1 

type UnmarshalerFunc func(Reader) error

The UnmarshalerFunc type is an adapter to allow the use of ordinary functions as unmarshalers, useful for inlining marshalers instead of defining new types

func (UnmarshalerFunc) UnmarshalRestLi added in v0.26.1 

func (u UnmarshalerFunc) UnmarshalRestLi(reader Reader) error

type WriteCloser 

type WriteCloser interface {
	Writer
	Closer
}

WriteCloser groups the Writer and Closer functions.

func NewCompactJsonWriter 

func NewCompactJsonWriter() WriteCloser

NewCompactJsonWriter returns a WriteCloser that serializes objects using JSON. This representation has no extraneous whitespace and is intended for wire transport.

func NewCompactJsonWriterWithExcludedFields added in v0.20.0 

func NewCompactJsonWriterWithExcludedFields(excludedFields PathSpec) WriteCloser

NewCompactJsonWriterWithExcludedFields returns a WriteCloser that serializes objects using JSON, excluding any fields matched by the given PathSpec. This representation has no extraneous whitespace and is intended for wire transport.

func NewPrettyJsonWriter 

func NewPrettyJsonWriter() WriteCloser

NewPrettyJsonWriter returns a WriteCloser that serializes objects using JSON. This representation delimits fields and array items using newlines and provides indentation for nested objects. It generates a lot of unnecessary bytes and is intended primarily for debugging or human-readability purposes.

func NewPrettyJsonWriterWithExcludedFields added in v0.20.0 

func NewPrettyJsonWriterWithExcludedFields(excludedFields PathSpec) WriteCloser

NewPrettyJsonWriterWithExcludedFields returns a WriteCloser that serializes objects using JSON, excluding any fields matched by the given PathSpec. This representation delimits fields and array items using newlines and provides indentation for nested objects. It generates a lot of unnecessary bytes and is intended primarily for debugging or human-readability purposes.

func NewRor2HeaderWriter 

func NewRor2HeaderWriter() WriteCloser

NewRor2HeaderWriter returns a new WriteCloser that serializes objects using the rest.li protocol 2.0 object and array representation (ROR2), whose spec is defined here: https://linkedin.github.io/rest.li/spec/protocol#restli-protocol-20-object-and-listarray-representation This specific WriteCloser uses the "reduced" URL encoding instead of the full URL encoding, i.e. it only escapes the following characters using url.QueryEscape: 

% , ( ) ' :

func NewRor2HeaderWriterWithExcludedFields added in v0.20.0 

func NewRor2HeaderWriterWithExcludedFields(excludedFields PathSpec) WriteCloser

NewRor2HeaderWriterWithExcludedFields returns a new WriteCloser that serializes objects using the rest.li protocol 2.0 object and array representation (ROR2), whose spec is defined here: https://linkedin.github.io/rest.li/spec/protocol#restli-protocol-20-object-and-listarray-representation This specific WriteCloser uses the "reduced" URL encoding instead of the full URL encoding, i.e. it only escapes the following characters using url.QueryEscape: 

% , ( ) ' :

Any fields matched by the given PathSpec are excluded from serialization

type Writer 

type Writer interface {
	PrimitiveWriter
	// WriteRawBytes appends the given bytes to the underlying buffer, without validating the input. Use at your own
	// risk!
	WriteRawBytes([]byte)
	// WriteMap writes the map keys/object fields written by the given lambda between object delimiters. The lambda
	// takes a function that is used to write the key/field name into the object and returns a nested Writer. This
	// Writer should be used to write inner fields. Take the following JSON object:
	//   {
	//     "foo": "bar",
	//     "baz": 42
	//   }
	// This would be written as follows using a Writer:
	//		err := writer.WriteMap(func(keyWriter func(string) restlicodec.Writer) error {
	//			keyWriter("foo").WriteString("bar")
	//			keyWriter("baz").WriteInt32(42)
	//			return nil
	//		}
	// Note that not using the inner Writer returned by the keyWriter may result in undefined behavior.
	WriteMap(mapWriter MapWriter) error
	// WriteArray writes the array items written by the given lambda between array delimiters. The lambda
	// takes a function that is used to signal that a new item is starting and returns a nested Writer. This
	// Writer should be used to write inner fields. Take the following JSON object:
	//   [
	//     "foo",
	//     "bar"
	//   ]
	// This would be written as follows using a Writer:
	//		err := writer.WriteArray(func(itemWriter func() restlicodec.Writer) error {
	//			itemWriter().WriteString("foo")
	//			itemWriter().WriteString("bar")
	//			return nil
	//		}
	// Note that not using the inner Writer returned by the itemWriter may result in undefined behavior.
	WriteArray(arrayWriter ArrayWriter) error
	// IsKeyExcluded checks whether or not the given key or field name at the current scope should be included in
	// serialization. Exclusion behavior is already built into the writer but this is intended for Marhsalers that use
	// custom serialization logic on top of the Writer
	IsKeyExcluded(key string) bool
	// SetScope returns a copy of the current writer with the given scope. For internal use only by Marshalers that use
	// custom serialization logic on top of the Writer. Designed to work around the backing PathSpec for field
	// exclusion.
	SetScope(...string) Writer
}

Writer is the interface implemented by all serialization mechanisms supported by rest.li. See the New*Writer functions provided in package for all the supported serialization mechanisms.

Source Files

View all Source files

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.