encoding

type Codec ¶

type Codec interface {
	Marshal(v any) ([]byte, error)
	Unmarshal(data []byte, v any) error
}

Codec is a mechanism for serialising and deserialising a wide range of types. Care should be taken to ensure that only valid types are passed to a codec, eg proto.Message for ProtoCodec. Codecs *must* marshal deterministically, such that a round trip of []byte -> any -> []byte leaves the bytes unchanged.

A codec may additionally describe the payloads it produces for service discovery by implementing the optional CodecMetadata (content-type + JSON schema), CodecInputMetadata and CodecOutputMetadata interfaces.

var (
	// BinaryCodec marshals []byte and unmarshals into *[]byte
	// In handlers, it uses a content type of application/octet-stream
	BinaryCodec Codec = binaryCodec{}
	// ProtoCodec marshals proto.Message and unmarshals into proto.Message or pointers to types that implement proto.Message
	// In handlers, it uses a content-type of application/proto
	ProtoCodec Codec = protoCodec{}
	// ProtoJSONCodec marshals proto.Message and unmarshals into proto.Message or pointers to types that implement proto.Message
	// It uses the protojson package to marshal and unmarshal
	// In handlers, it uses a content-type of application/json
	ProtoJSONCodec Codec = protoJSONCodec{}
	// JSONCodec marshals any json.Marshallable type and unmarshals into any json.Unmarshallable type
	// In handlers, it uses a content-type of application/json
	JSONCodec Codec = jsonCodec{
				// contains filtered or unexported fields
	}
)

func JSONCodecWithCustomSchemaGenerator(genJsonSchema func(v any) interface{}) Codec

type CodecInputMetadata ¶ added in v0.25.0

type CodecInputMetadata interface {
	InputRequired() bool
}

CodecInputMetadata is an optional interface a Codec may implement to declare, for service discovery, whether a request body is required. When not implemented, input is required.

type CodecMetadata ¶ added in v0.25.0

type CodecMetadata interface {
	// ContentType returns the MIME type of the serialised bytes, or "" for none.
	ContentType() string
	// JsonSchema returns a JSON schema for the type of v, or nil for none.
	JsonSchema(v any) any
}

CodecMetadata is an optional interface a Codec may implement to describe its payloads for service discovery. When not implemented, no content-type or schema is advertised.

type CodecOutputMetadata ¶ added in v0.25.0

type CodecOutputMetadata interface {
	SetContentTypeIfEmpty() bool
}

CodecOutputMetadata is an optional interface a Codec may implement to declare, for service discovery, that the output content-type should be set even when the output body is empty. When not implemented, it is not set for empty bodies.

type InputPayload ¶

type InputPayload struct {
	Required    bool        `json:"required"`
	ContentType *string     `json:"contentType,omitempty"`
	JsonSchema  interface{} `json:"jsonSchema,omitempty"`
}

InputPayload is provided to Restate upon handler discovery, to teach the ingress how to validate incoming request bodies.

func InputPayloadFor(codec Codec, i any) *InputPayload

type NonDeterministicSerializer ¶ added in v0.24.0

type NonDeterministicSerializer interface {
	IsNonDeterministic() bool
}

NonDeterministicSerializer is an interface that codecs can implement to indicate they may produce non-deterministic output for the same input.

type OutputPayload ¶

type OutputPayload struct {
	ContentType           *string     `json:"contentType,omitempty"`
	SetContentTypeIfEmpty bool        `json:"setContentTypeIfEmpty"`
	JsonSchema            interface{} `json:"jsonSchema,omitempty"`
}

OutputPayload is provided to Restate upon handler discovery, to teach the ingress how to annotate outgoing response bodies.

func OutputPayloadFor(codec Codec, o any) *OutputPayload

type RestateMarshaler ¶

type RestateMarshaler interface {
	RestateMarshal(codec Codec) ([]byte, error)
	OutputPayload(codec Codec) *OutputPayload
}

RestateMarshaler can be implemented by types that want to control their own marshaling Marshaling *must* be deterministic

type RestateUnmarshaler ¶

type RestateUnmarshaler interface {
	RestateUnmarshal(codec Codec, data []byte) error
	InputPayload(codec Codec) *InputPayload
}

RestateUnmarshaler can be implemented by types that want to control their own unmarshaling

type Void ¶

type Void struct{}

Void is a placeholder to signify 'no value' where a type is otherwise needed It implements RestateMarshaler and RestateUnmarshaler to ensure that no marshaling or unmarshaling ever happens on this type.

func (v Void) InputPayload(codec Codec) *InputPayload

func (v Void) OutputPayload(codec Codec) *OutputPayload

func (v Void) RestateMarshal(codec Codec) ([]byte, error)

func (v Void) RestateUnmarshal(codec Codec, data []byte) error