restate

package module
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 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"'

# {"response":true}
curl -v localhost:8080/UserSession/azmy/AddTicket \
    -H 'content-type: application/json' \
    -d '"ticket-2"'
# {"response":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
#{"response":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 = errors.ErrKeyNotFound
)
View Source 
var WithBinary = WithPayloadCodec(encoding.BinaryCodec)
View Source 
var WithJSON = WithPayloadCodec(encoding.JSONCodec)
View Source 
var WithProto = WithPayloadCodec(encoding.ProtoCodec)

Functions

func ErrorCode 

func ErrorCode(err error) errors.Code

ErrorCode returns code associated with error or UNKNOWN

func GetAs 

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

GetAs helper function to get a key, returning a typed response instead of accepting a pointer. If there is no associated value with key, an error ErrKeyNotFound is returned

func IsTerminalError 

func IsTerminalError(err error) bool

IsTerminalError checks if err is terminal

func NewObjectHandler 

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

func NewObjectSharedHandler 

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

func NewServiceHandler 

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

NewServiceHandler create a new handler for a service, defaulting to JSON encoding

func RunAs 

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

RunAs helper function runs a Run function, 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 forever unless a terminal error is returned

func WithCodec 

func WithCodec(codec encoding.Codec) withCodec

func WithErrorCode 

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

WithErrorCode returns an error with specific

func WithPayloadCodec 

func WithPayloadCodec(codec encoding.PayloadCodec) withPayloadCodec

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.
	Done()
	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
	SendClient
}

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
	Sleep(d time.Duration)
	// 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(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
}

type Handler 

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

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
}

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()
}

type ObjectContext 

type ObjectContext interface {
	Context
	KeyValueReader
	KeyValueWriter
}

type ObjectHandler 

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

	Handler
	// contains filtered or unexported methods
}

type ObjectHandlerFn 

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

ObjectHandlerFn signature for object (keyed) handler function

type ObjectHandlerOption 

type ObjectHandlerOption interface {
	// contains filtered or unexported methods
}

type ObjectRouter 

type ObjectRouter struct {
	// contains filtered or unexported fields
}

ObjectRouter

func NewObjectRouter 

func NewObjectRouter(name string, options ...ObjectRouterOption) *ObjectRouter

func Object 

func Object(object any, options ...ObjectRouterOption) *ObjectRouter

Object converts a struct with methods into a Virtual Object where each correctly-typed and exported method of the struct will become a handler on the Object. The Object 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 `ObjectHandlerFn[I, O]` or `ObjectSharedHandlerFn[I, O]`. Input types I 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 O 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.

func (*ObjectRouter) Handler 

func (r *ObjectRouter) Handler(name string, handler ObjectHandler) *ObjectRouter

func (*ObjectRouter) Handlers 

func (r *ObjectRouter) Handlers() map[string]Handler

func (*ObjectRouter) Name 

func (r *ObjectRouter) Name() string

func (*ObjectRouter) Type 

func (r *ObjectRouter) Type() internal.ServiceType

type ObjectRouterOption 

type ObjectRouterOption interface {
	// contains filtered or unexported methods
}

type ObjectSharedContext 

type ObjectSharedContext interface {
	Context
	KeyValueReader
}

type ObjectSharedHandlerFn 

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

ObjectHandlerFn signature for object (keyed) handler function that can run concurrently with other handlers against a snapshot of state

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
}

type Router 

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

Router interface

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
}

RunContext methods are the only methods safe to call from inside a .Run()

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
	Select() Selectable
}

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

type SendClient 

type SendClient interface {
	// Send makes a one-way call which is executed in the background
	Send(input any, delay time.Duration) error
}

type ServiceHandler 

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

	Handler
	// contains filtered or unexported methods
}

type ServiceHandlerFn 

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

ServiceHandlerFn signature of service (unkeyed) handler function

type ServiceHandlerOption 

type ServiceHandlerOption interface {
	// contains filtered or unexported methods
}

type ServiceRouter 

type ServiceRouter struct {
	// contains filtered or unexported fields
}

ServiceRouter implements Router

func NewServiceRouter 

func NewServiceRouter(name string, options ...ServiceRouterOption) *ServiceRouter

NewServiceRouter creates a new ServiceRouter

func Service 

func Service(service any, options ...ServiceRouterOption) *ServiceRouter

Service converts a struct with methods into a Restate Service where each correctly-typed and exported method of the struct will become a handler on the Service. 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]`. Input types I 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 O 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.

func (*ServiceRouter) Handler 

func (r *ServiceRouter) Handler(name string, handler ServiceHandler) *ServiceRouter

Handler registers a new handler by name

func (*ServiceRouter) Handlers 

func (r *ServiceRouter) Handlers() map[string]Handler

func (*ServiceRouter) Name 

func (r *ServiceRouter) Name() string

func (*ServiceRouter) Type 

func (r *ServiceRouter) Type() internal.ServiceType

type ServiceRouterOption 

type ServiceRouterOption interface {
	// contains filtered or unexported methods
}

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[O any] interface {
	// RequestFuture makes a call and returns a handle on a future response
	RequestFuture(input any) (TypedResponseFuture[O], error)
	// Request makes a call and blocks on getting the response
	Request(input any) (O, error)
	SendClient
}

TypedCallClient is an extension of CallClient which returns typed responses instead of accepting a pointer

func CallAs 

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

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

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 default to a encoding.VoidCodec which will reject input at the ingress 2. Output types for handlers - the response payload codec will default to a encoding.VoidCodec which 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.

Source Files

View all Source files

Directories

Path Synopsis
examples
otel module
generated
dev/restate
Stub package to fix imports of generate code
 Stub package to fix imports of generate code
proto/discovery
proto/go
proto/protocol
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.

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.