restate

package module
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2024 License: MIT Imports: 13 Imported by: 32

README

Go Reference Go

Restate Go SDK

Restate is a system for easily building resilient applications using distributed durable async/await. This repository contains the Restate SDK for writing services in Golang. This SDK has not yet seen a stable release and APIs are subject to change. Feedback is welcome via issues and in Discord.

Features implemented

  • Log replay (resume of execution on failure)
  • State (set/get/clear/clear-all/keys)
  • Remote service call over restate runtime
  • Delayed execution of remote services
  • Sleep
  • Run
  • Awakeable
  • Shared object handlers
  • Workflows

Basic usage

Please check example for a fully working example based on the [TypeScript ticket reservation example] (https://github.com/restatedev/examples/tree/main/patterns-use-cases/ticket-reservation/ticket-reservation-typescript)

How to use the example

Download and run restate v1.x

restate-server

In another terminal run the example

cd restate-sdk-go/example
go run .

In a third terminal register:

restate deployments register --force -y http://localhost:9080

And do the following steps

  • Add tickets to basket
curl -v localhost:8080/UserSession/azmy/AddTicket \
    -H 'content-type: application/json' \
    -d '"ticket-1"'

# true
curl -v localhost:8080/UserSession/azmy/AddTicket \
    -H 'content-type: application/json' \
    -d '"ticket-2"'
# true

Trying adding the same tickets again should return false since they are already reserved. If you didn't check out the tickets in 15min (if you are impatient change the delay in code to make it shorter)

  • Check out
curl localhost:8080/UserSession/azmy/Checkout
# true

Versions

This library follows Semantic Versioning.

The compatibility with Restate is described in the following table:

Restate Server\sdk-go 0.9
1.0 ✅

Contributing

We’re excited if you join the Restate community and start contributing! Whether it is feature requests, bug reports, ideas & feedback or PRs, we appreciate any and all contributions. We know that your time is precious and, therefore, deeply value any effort to contribute!

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrKeyNotFound is returned when there is no state value for a key
	ErrKeyNotFound = errors.ErrKeyNotFound
)
View Source 
var WithBinary = WithPayloadCodec(encoding.BinaryCodec)

WithBinary is an option to specify the use of encoding.BinaryCodec for (de)serialisation

View Source 
var WithJSON = WithPayloadCodec(encoding.JSONCodec)

WithJSON is an option to specify the use of encoding.JsonCodec for (de)serialisation

View Source 
var WithProto = WithPayloadCodec(encoding.ProtoCodec)

WithProto is an option to specify the use of encoding.ProtoCodec for (de)serialisation

View Source 
var WithProtoJSON = WithPayloadCodec(encoding.ProtoJSONCodec)

WithProtoJSON is an option to specify the use of encoding.ProtoJSONCodec for (de)serialisation

Functions

func GetAs 

func GetAs[T any](ctx ObjectSharedContext, key string, options ...options.GetOption) (output T, err error)

GetAs get the value for a key, returning a typed response instead of accepting a pointer. If there is no associated value with key, ErrKeyNotFound is returned

func IsTerminalError 

func IsTerminalError(err error) bool

IsTerminalError checks if err is terminal - ie, that returning it in a handler or Run function will finish the invocation with the error as a result.

func NewObject added in v0.10.0 

func NewObject(name string, opts ...options.ServiceDefinitionOption) *object

NewObject creates a new named Virtual Object

func NewObjectHandler 

func NewObjectHandler[I any, O any](fn ObjectHandlerFn[I, O], opts ...options.HandlerOption) *objectHandler[I, O]

NewObjectHandler converts a function of signature ObjectHandlerFn into an exclusive-mode handler on a Virtual Object. The handler will have access to a full ObjectContext which may mutate state.

func NewObjectSharedHandler 

func NewObjectSharedHandler[I any, O any](fn ObjectSharedHandlerFn[I, O], opts ...options.HandlerOption) *objectHandler[I, O]

NewObjectSharedHandler converts a function of signature ObjectSharedHandlerFn into a shared-mode handler on a Virtual Object. The handler will only have access to a ObjectSharedContext which can only read a snapshot of state.

func NewService added in v0.10.0 

func NewService(name string, opts ...options.ServiceDefinitionOption) *service

NewService creates a new named Service

func NewServiceHandler 

func NewServiceHandler[I any, O any](fn ServiceHandlerFn[I, O], opts ...options.HandlerOption) *serviceHandler[I, O]

NewServiceHandler converts a function of signature ServiceHandlerFn into a handler on a Restate service.

func RunAs 

func RunAs[T any](ctx Context, fn func(ctx RunContext) (T, error), options ...options.RunOption) (output T, err error)

RunAs executes a Run function on a Context, returning a typed response instead of accepting a pointer

func TerminalError 

func TerminalError(err error, code ...errors.Code) error

TerminalError returns a terminal error with optional code. Code is optional but only one code is allowed. By default, restate will retry the invocation or Run function forever unless a terminal error is returned

func WithCodec 

func WithCodec(codec encoding.Codec) withCodec

WithCodec is an option that can be provided to many different functions that perform (de)serialisation in order to specify a custom codec with which to (de)serialise instead of the default of JSON.

See also WithProto, WithBinary, WithJSON.

func WithErrorCode 

func WithErrorCode(err error, code Code) error

WithErrorCode returns an error with specific Code attached.

func WithHeaders added in v0.10.0 

func WithHeaders(headers map[string]string) withHeaders

WithHeaders is an option to specify outgoing headers when making a call

func WithPayloadCodec 

func WithPayloadCodec(codec encoding.PayloadCodec) withPayloadCodec

WithPayloadCodec is an option that can be provided to handler/service options in order to specify a custom encoding.PayloadCodec with which to (de)serialise and set content-types instead of the default of JSON.

See also WithProto, WithBinary, WithJSON.

Types

type After 

type After interface {
	// Done blocks waiting on the remaining duration of the sleep.
	// It is *not* safe to call this in a goroutine - use Context.Select if you want to wait on multiple
	// results at once. Can return a terminal error in the case where the invocation was cancelled mid-sleep,
	// hence Done() should always be called, even after using Context.Select.
	Done() error
	Selectable
}

After is a handle on a Sleep operation which allows you to do other work concurrently with the sleep.

type Awakeable 

type Awakeable interface {
	// Id returns the awakeable ID, which can be stored or sent to a another service
	Id() string
	// Result blocks on receiving the result of the awakeable, storing the value it was
	// resolved with in output or otherwise returning the error it was rejected with.
	// It is *not* safe to call this in a goroutine - use Context.Select if you
	// want to wait on multiple results at once.
	// Note: use the AwakeableAs helper function to avoid having to pass a output pointer
	Result(output any) error
	Selectable
}

Awakeable is the Go representation of a Restate awakeable; a 'promise' to a future value or error, that can be resolved or rejected by other services.

type CallClient 

type CallClient interface {
	// RequestFuture makes a call and returns a handle on a future response
	RequestFuture(input any) (ResponseFuture, error)
	// Request makes a call and blocks on getting the response which is stored in output
	Request(input any, output any) error
	// Send makes a one-way call which is executed in the background
	Send(input any, delay time.Duration) error
}

CallClient represents all the different ways you can invoke a particular service/key/method tuple.

type CallOption added in v0.10.0 

type CallOption = options.CallOption

re-export for use in generated code

type Code added in v0.9.1 

type Code = errors.Code

Code is a numeric status code for an error, typically a HTTP status code.

func ErrorCode 

func ErrorCode(err error) Code

ErrorCode returns Code associated with error, defaulting to 500

type Context 

type Context interface {
	RunContext

	// Rand returns a random source which will give deterministic results for a given invocation
	// The source wraps the stdlib rand.Rand but with some extra helper methods
	// This source is not safe for use inside .Run()
	Rand() *rand.Rand

	// Sleep for the duration d. Can return a terminal error in the case where the invocation was cancelled mid-sleep.
	Sleep(d time.Duration) error
	// After is an alternative to Context.Sleep which allows you to complete other tasks concurrently
	// with the sleep. This is particularly useful when combined with Context.Select to race between
	// the sleep and other Selectable operations.
	After(d time.Duration) After

	// Service gets a Service accessor by service and method name
	// Note: use the CallAs helper function to deserialise return values
	Service(service, method string, opts ...options.CallOption) CallClient

	// Object gets a Object accessor by name, key and method name
	// Note: use the CallAs helper function to receive serialised values
	Object(object, key, method string, opts ...options.CallOption) CallClient

	// Run runs the function (fn), storing final results (including terminal errors)
	// durably in the journal, or otherwise for transient errors stopping execution
	// so Restate can retry the invocation. Replays will produce the same value, so
	// all non-deterministic operations (eg, generating a unique ID) *must* happen
	// inside Run blocks.
	// Note: use the RunAs helper function to get typed output values instead of providing an output pointer
	Run(fn func(ctx RunContext) (any, error), output any, opts ...options.RunOption) error

	// Awakeable returns a Restate awakeable; a 'promise' to a future
	// value or error, that can be resolved or rejected by other services.
	// Note: use the AwakeableAs helper function to avoid having to pass a output pointer to Awakeable.Result()
	Awakeable(options ...options.AwakeableOption) Awakeable
	// ResolveAwakeable allows an awakeable (not necessarily from this service) to be
	// resolved with a particular value.
	ResolveAwakeable(id string, value any, options ...options.ResolveAwakeableOption) error
	// ResolveAwakeable allows an awakeable (not necessarily from this service) to be
	// rejected with a particular error.
	RejectAwakeable(id string, reason error)

	// Select returns an iterator over blocking Restate operations (sleep, call, awakeable)
	// which allows you to safely run them in parallel. The Selector will store the order
	// that things complete in durably inside Restate, so that on replay the same order
	// can be used. This avoids non-determinism. It is *not* safe to use goroutines or channels
	// outside of Context.Run functions, as they do not behave deterministically.
	Select(futs ...Selectable) Selector
}

Context is the base set of operations that all Restate handlers may perform.

type Handler 

type Handler interface {
	InputPayload() *encoding.InputPayload
	OutputPayload() *encoding.OutputPayload
	HandlerType() *internal.ServiceHandlerType
	// contains filtered or unexported methods
}

Handler is implemented by all Restate handlers

type KeyValueReader 

type KeyValueReader interface {
	// Get gets value associated with key and stores it in value
	// If key does not exist, this function returns ErrKeyNotFound
	// Note: Use GetAs generic helper function to avoid passing in a value pointer
	Get(key string, value any, options ...options.GetOption) error
	// Keys returns a list of all associated key
	Keys() []string
	// Key retrieves the key for this virtual object invocation. This is a no-op and is
	// always safe to call.
	Key() string
}

KeyValueReader is the set of read-only methods which can be used in all Virtual Object handlers.

type KeyValueWriter 

type KeyValueWriter interface {
	// Set sets a value against a key, using the provided codec (defaults to JSON)
	Set(key string, value any, options ...options.SetOption) error
	// Clear deletes a key
	Clear(key string)
	// ClearAll drops all stored state associated with key
	ClearAll()
}

KeyValueWriter is the set of mutating methods which can be used in exclusive-mode Virtual Object handlers.

type ObjectContext 

type ObjectContext interface {
	Context
	KeyValueReader
	KeyValueWriter
}

ObjectContext is an extension of Context which can be used in exclusive-mode Virtual Object handlers, giving mutable access to state.

type ObjectHandler 

type ObjectHandler interface {
	Call(ctx ObjectContext, request []byte) (output []byte, err error)
	Handler
}

ObjectHandler is the required set of methods for a Virtual Object handler.

type ObjectHandlerFn 

type ObjectHandlerFn[I any, O any] func(ctx ObjectContext, input I) (O, error)

ObjectHandlerFn is the signature for a Virtual Object exclusive-mode handler function

type ObjectSharedContext 

type ObjectSharedContext interface {
	Context
	KeyValueReader
}

ObjectContext is an extension of Context which can be used in shared-mode Virtual Object handlers, giving read-only access to a snapshot of state.

type ObjectSharedHandlerFn 

type ObjectSharedHandlerFn[I any, O any] func(ctx ObjectSharedContext, input I) (O, error)

ObjectHandlerFn is the signature for a Virtual Object shared-mode handler function

type Request added in v0.9.1 

type Request struct {
	// The unique id that identifies the current function invocation. This id is guaranteed to be
	// unique across invocations, but constant across reties and suspensions.
	ID []byte
	// Request headers - the following headers capture the original invocation headers, as provided to
	// the ingress.
	Headers map[string]string
	// Attempt headers - the following headers are sent by the restate runtime.
	// These headers are attempt specific, generated by the restate runtime uniquely for each attempt.
	// These headers might contain information such as the W3C trace context, and attempt specific information.
	AttemptHeaders map[string][]string
	// Raw unparsed request body
	Body []byte
}

type ResponseFuture 

type ResponseFuture interface {
	// Response blocks on the response to the call and stores it in output, or returns the associated error
	// It is *not* safe to call this in a goroutine - use Context.Select if you
	// want to wait on multiple results at once.
	Response(output any) error
	Selectable
}

ResponseFuture is a handle on a potentially not-yet completed outbound call.

type RunContext 

type RunContext interface {
	context.Context

	// Log obtains a handle on a slog.Logger which already has some useful fields (invocationID and method)
	// By default, this logger will not output messages if the invocation is currently replaying
	// The log handler can be set with `.WithLogger()` on the server object
	Log() *slog.Logger

	// Request gives extra information about the request that started this invocation
	Request() *Request
}

RunContext methods are the only methods of Context that are safe to call from inside a .Run() Calling any other method inside a Run() will panic.

type Selectable 

type Selectable = futures.Selectable

Selectable is implemented by types that may be passed to Context.Select

type Selector 

type Selector interface {
	// Remaining returns whether there are still operations that haven't been returned by Select().
	// There will always be exactly the same number of results as there were operations
	// given to Context.Select
	Remaining() bool
	// Select blocks on the next completed operation or returns nil if there are none left
	Select() Selectable
}

Selector is an iterator over a list of blocking Restate operations that are running in the background.

type ServiceDefinition added in v0.10.0 

type ServiceDefinition interface {
	Name() string
	Type() internal.ServiceType
	// Set of handlers associated with this service definition
	Handlers() map[string]Handler
}

ServiceDefinition is the set of methods implemented by both services and virtual objects

func Reflect added in v0.10.0 

func Reflect(rcvr any, opts ...options.ServiceDefinitionOption) ServiceDefinition

Reflect converts a struct with methods into a service definition where each correctly-typed and exported method of the struct will become a handler in the definition. The service name defaults to the name of the struct, but this can be overidden by providing a `ServiceName() string` method. The handler name is the name of the method. Handler methods should be of the type `ServiceHandlerFn[I,O]`, `ObjectHandlerFn[I, O]` or `ObjectSharedHandlerFn[I, O]`. This function will panic if a mixture of object and service method signatures or opts are provided.

Input types will be deserialised with the provided codec (defaults to JSON) except when they are restate.Void, in which case no input bytes or content type may be sent. Output types will be serialised with the provided codec (defaults to JSON) except when they are restate.Void, in which case no data will be sent and no content type set.

type ServiceDefinitionOption added in v0.10.0 

type ServiceDefinitionOption = options.ServiceDefinitionOption

type ServiceHandler 

type ServiceHandler interface {
	Call(ctx Context, request []byte) (output []byte, err error)
	Handler
}

ServiceHandler is the required set of methods for a Service handler.

type ServiceHandlerFn 

type ServiceHandlerFn[I any, O any] func(ctx Context, input I) (O, error)

ServiceHandlerFn is the signature for a Service handler function

type TypedAwakeable 

type TypedAwakeable[T any] interface {
	// Id returns the awakeable ID, which can be stored or sent to a another service
	Id() string
	// Result blocks on receiving the result of the awakeable, storing the value it was
	// resolved with in output or otherwise returning the error it was rejected with.
	// It is *not* safe to call this in a goroutine - use Context.Select if you
	// want to wait on multiple results at once.
	Result() (T, error)
	Selectable
}

TypedAwakeable is an extension of Awakeable which returns typed responses instead of accepting a pointer

func AwakeableAs 

func AwakeableAs[T any](ctx Context, options ...options.AwakeableOption) TypedAwakeable[T]

AwakeableAs helper function to treat Awakeable results as a particular type.

type TypedCallClient 

type TypedCallClient[I any, O any] interface {
	// RequestFuture makes a call and returns a handle on a future response
	RequestFuture(input I) (TypedResponseFuture[O], error)
	// Request makes a call and blocks on getting the response
	Request(input I) (O, error)
	// Send makes a one-way call which is executed in the background
	Send(input I, delay time.Duration) error
}

TypedCallClient is an extension of CallClient which deals in typed values

func CallAs 

func CallAs[O any](client CallClient) TypedCallClient[any, O]

CallAs helper function to get typed responses from a CallClient instead of passing in a pointer

func NewTypedCallClient added in v0.10.0 

func NewTypedCallClient[I any, O any](client CallClient) TypedCallClient[I, O]

NewTypedCallClient is primarily intended to be called from generated code, to provide type safety of input types. In other contexts it's generally less cumbersome to use CallAs, as the output type can be inferred.

type TypedResponseFuture 

type TypedResponseFuture[O any] interface {
	// Response blocks on the response to the call and returns it or the associated error
	// It is *not* safe to call this in a goroutine - use Context.Select if you
	// want to wait on multiple results at once.
	Response() (O, error)
	Selectable
}

TypedResponseFuture is an extension of ResponseFuture which returns typed responses instead of accepting a pointer

type Void 

type Void = encoding.Void

Void is a placeholder to signify 'no value' where a type is otherwise needed. It can be used in several contexts:

  1. Input types for handlers - the request payload codec will reject input at the ingress
  2. Output types for handlers - the response payload codec will send no bytes and set no content-type
  3. Input for a outgoing Request or Send - no bytes will be sent
  4. The output type for an outgoing Request - the response body will be ignored. A pointer is also accepted.
  5. The output type for an awakeable - the result body will be ignored. A pointer is also accepted.

Source Files

View all Source files

Directories

Path Synopsis
examples
codegen command
codegen/proto
ticketreservation command
otel module
generated
dev/restate/sdk
dev/restate/sdk/go
dev/restate/service
errors
futures
identity
log
options
rand
state
wire
wire implements the grpc wire protocol that is used later on by the state machine to communicate with restate runtime.
 wire implements the grpc wire protocol that is used later on by the state machine to communicate with restate runtime.
protoc-gen-go-restate is a plugin for the Google protocol buffer compiler to generate Restate servers and clients.
 protoc-gen-go-restate is a plugin for the Google protocol buffer compiler to generate Restate servers and clients.

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.