stateful

Documentation

Overview

Package stateful contains stateful middleware, typically in the context of distributed transaction.

Context Passing

It is curial for all parties in the distributed transaction to share an transaction id. This package provides utility to pass this id across services.

HTTPToContext() http.RequestFunc
ContextToHTTP() http.RequestFunc
GRPCToContext() grpc.ServerRequestFunc
ContextToGRPC() grpc.ClientRequestFunc

Idempotency

Certain operations will be retried by the client more than once. A middleware is provided for the server to shield against repeated request in the same transaction.

func MakeIdempotence(s Oncer) endpoint.Middleware

Lock

Certain resource in transaction cannot be concurrently accessed. A middleware is provided to lock such resources.

func MakeLock(l Locker) endpoint.Middleware

Allow Null Compensation and Prevent Resource Suspension

Transaction participants may receive the compensation order before performing normal operations due to network exceptions. In this case, null compensation is required.

If the forward operation arrives later than the compensating operation due to network exceptions, the forward operation must be discarded. Otherwise, resource suspension occurs.

func MakeAttempt(s Sequencer) endpoint.Middleware
func MakeCancel(s Sequencer) endpoint.Middleware

Index

• Variables
• func ContextToGRPC() grpc.ClientRequestFunc
• func ContextToHTTP() http.RequestFunc
• func GRPCToContext() grpc.ServerRequestFunc
• func HTTPToContext() http.RequestFunc
• func MakeAttempt(s Sequencer) endpoint.Middleware
• func MakeCancel(s Sequencer) endpoint.Middleware
• func MakeIdempotence(s Oncer) endpoint.Middleware
• func MakeLock(l Locker) endpoint.Middleware
• type Locker
• type Oncer
• type RedisStore
  • func (r RedisStore) Lock(ctx context.Context, key string) bool
  • func (r RedisStore) MarkAttemptedCheckCancelled(ctx context.Context, s string) bool
  • func (r RedisStore) MarkCancelledCheckAttempted(ctx context.Context, s string) bool
  • func (r RedisStore) Once(ctx context.Context, key string) bool
  • func (r RedisStore) Unlock(ctx context.Context, key string)
• type Sequencer

Variables

var ErrNoLock = errors.New("failed to grab lock")

ErrNoLock is returned when the endpoint fail to fetch the distributed lock under the same CorrelationID.

var ErrNonIdempotent = errors.New("rejected repeated request")

ErrNonIdempotent is returned when an endpoint is requested more than once with the same CorrelationID.

Functions

func ContextToGRPC

func ContextToGRPC() grpc.ClientRequestFunc

ContextToGRPC moves a CorrelationID from context to grpc metadata. Particularly useful for clients.

func ContextToHTTP

func ContextToHTTP() http.RequestFunc

ContextToHTTP moves a CorrelationID from context to request header. Particularly useful for clients.

func GRPCToContext

func GRPCToContext() grpc.ServerRequestFunc

GRPCToContext moves a CorrelationID from grpc metadata to context. Particularly userful for servers.

func HTTPToContext

func HTTPToContext() http.RequestFunc

HTTPToContext moves a CorrelationID from request header to context. Particularly useful for servers.

func MakeAttempt

func MakeAttempt(s Sequencer) endpoint.Middleware

MakeAttempt returns a middleware that wraps around an attempt endpoint. If the this segment of the distributed transaction is already cancelled, the next endpoint will never be executed.

If the forward operation arrives later than the compensating operation due to network exceptions, the forward operation must be discarded. Otherwise, resource suspension occurs.

func MakeCancel

func MakeCancel(s Sequencer) endpoint.Middleware

MakeCancel returns a middleware that wraps around the cancellation endpoint. It guarantees if this segment of the distributed transaction is never attempted, the cancellation endpoint will not be executed.

Transaction participants may receive the compensation order before performing normal operations due to network exceptions. In this case, null compensation is required.

func MakeIdempotence

func MakeIdempotence(s Oncer) endpoint.Middleware

MakeIdempotence returns a middleware that ensures the next endpoint can only be executed once per CorrelationID.

func MakeLock

func MakeLock(l Locker) endpoint.Middleware

MakeLock returns a middleware that ensures the next endpoint is never concurrently accessed.

Types

type Locker

type Locker interface {
	// Lock should return true only when it successfully grabs the lock.
	Lock(ctx context.Context, key string) bool
	Unlock(ctx context.Context, key string)
}

Locker is an interface for the distributed lock.

type Oncer

type Oncer interface {
	Once(ctx context.Context, key string) bool
}

Oncer should return true if the key has been observed before.

type RedisStore

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

RedisStore is an implementation of Oncer, Locker and Sequencer.

func (RedisStore) Lock

func (r RedisStore) Lock(ctx context.Context, key string) bool

Lock grabs the lock for the given key. It returns true if the lock is successfully acquired. If the lock is not available, this method will block until the lock is released or the context expired. In latter case, false is returned.

func (RedisStore) MarkAttemptedCheckCancelled

func (r RedisStore) MarkAttemptedCheckCancelled(ctx context.Context, s string) bool

MarkAttemptedCheckCancelled returns true if the CorrelationID has been cancelled before. It also marks the CorrelationID as attempted.

func (RedisStore) MarkCancelledCheckAttempted

func (r RedisStore) MarkCancelledCheckAttempted(ctx context.Context, s string) bool

MarkCancelledCheckAttempted returns true if the CorrelationID has been attempted before. It also marks the CorrelationID as cancelled.

func (RedisStore) Once

func (r RedisStore) Once(ctx context.Context, key string) bool

Once returns true if this method has been called before with the given key. If not, it internally set the key as called and returns false.

func (RedisStore) Unlock

func (r RedisStore) Unlock(ctx context.Context, key string)

Unlock unlocks the lock named by key.

type Sequencer

type Sequencer interface {
	MarkCancelledCheckAttempted(context.Context, string) bool
	MarkAttemptedCheckCancelled(context.Context, string) bool
}

Sequencer is an interface that shields against the disordering of attempt and cancel in a transactional context.