lid

README

WARNING

If for some bizarre reason you've randomly landed on this repo, do not use it. It has not yet been used in any capacity.

lid

lid (lock it down) is a library for locking via DynamoDB.

Documentation

Index

• Constants
• Variables
• func MergeErr(a ...error) error
• func MustErr(err error)
• func RunTestServiceSuite(t *testing.T, suites []ServiceBootstrap)
• type CheckResponse
• type Error
  • func (e *Error) Error() string
• type LockOpts
• type LockRequest
  • func (r LockRequest) IsValid() bool
• type LockResponse
  • func (a *LockResponse) Created() bool
  • func (a *LockResponse) Ok() bool
• type LockResponseStatus
• type Service
• type ServiceBootstrap
• type ServiceDebug
• type ServiceOpts
• type UnlockOpts
• type UnlockRequest
  • func (r UnlockRequest) IsValid() bool
• type UnlockResponse
  • func (r *UnlockResponse) Ok() bool
• type UnlockResponseStatus

Constants

const (
	// Forbidden describes a lock that exists but is owned by another signee.
	Forbidden = iota
)

Variables

var (
	ErrForbidden  = &Error{Forbidden, forbiddenMsg, nil}
	ErrBadRequest = errors.New("Bad request")
	ErrNotFound   = errors.New("Not found")
)

Functions

func MergeErr

func MergeErr(a ...error) error

MergeErr returns the first valid error. Clearly this belongs in a richer error handling package.

func MustErr

func MustErr(err error)

MustErr panics on a non-nil error. Clearly this belongs in a richer error handling package.

func RunTestServiceSuite

func RunTestServiceSuite(t *testing.T, suites []ServiceBootstrap)

RunTestServiceSuite provides scripted testing for the service, allowing chained command lists. It's a little painful to write tests, but there isn't much value in testing a single locking function. This is the main test function for any service implementations: Send in a bootstrap on the service for the standard testing.

Types

type CheckResponse

type CheckResponse struct {
	Signee string `json:"signee,omitempty"` // The owner of the lock.
	Level  int    `json:"level,omitempty"`  // The level of the lock.
}

CheckResponse provides the state of a lock.

type Error

type Error struct {
	Code    int
	Msg     string
	Payload interface{}
}

Error struct provides additional information about an error.

func (*Error) Error

func (e *Error) Error() string

type LockOpts

type LockOpts struct {
	Force      bool          `json:"force,omitempty"` // If true then force the lock, even if someone else owns it.
	Duration   time.Duration // Override the service default
	TimeToLive time.Duration // Override the service default
}

LockOpts provides options for the Lock operation.

type LockRequest

type LockRequest struct {
	Signature string `json:"signature,omitempty"` // The ID for this lock
	Signee    string `json:"signee,omitempty"`    // The owner requesting the lock
	Level     int    `json:"level,omitempty"`     // The level of lock requested. Leave this at the default 0 if you don't require levels.
}

LockRequest provides the parameters to the Lock function.

func (LockRequest) IsValid

func (r LockRequest) IsValid() bool

type LockResponse

type LockResponse struct {
	Status         LockResponseStatus `json:"status,omitempty"`
	PreviousSignee string             `json:"previous_signee,omitempty"` // If I acquired a stale lock, this is the former owner
}

LockResponse provides the output from the Lock function.

func (*LockResponse) Created

func (a *LockResponse) Created() bool

Created answers true if this operation actually created the lock. If it was already owned, this is false.

func (*LockResponse) Ok

func (a *LockResponse) Ok() bool

Ok answers true if the requester has the lock, regardless of previous state. See the status for more info.

type LockResponseStatus

type LockResponseStatus int

LockResponseStatus defines a status code for the response.

const (
	LockFailed      LockResponseStatus = iota // Someone else owns the lock
	LockOk                                    // The lock was free, now I own it
	LockTransferred                           // Someone else had a stale lock, now I own it
	LockRenewed                               // I previously owned it and still do
)

The status codes for the Lock response.

type Service

type Service interface {
	// Lock acquires the supplied lock. An error means the lock was not
	// acquired; success could be for various reasons supplied in the response.
	// The lock will be acquired if:
	// * It does not exist
	// * Or it does, and I own it
	// * Or it does, I don't own it, but my lock level is higher
	// * Or it does, I don't own it, but it's expired
	Lock(req LockRequest, opts *LockOpts) (LockResponse, error)

	// Unlock releases the supplied lock. Error is only returned if the lock
	// is owned by another signee; nil error means the lock no longer
	// exists, whether it did before or not.
	// The lock will be released if:
	// * It does not exist
	// * Or it does, and I own it
	Unlock(req UnlockRequest, opts *UnlockOpts) (UnlockResponse, error)

	// Check answers the current state of the lock.
	// DO NOT USE THIS FUNCTION. There's little value in finding out
	// what state a lock was in at some previous point in time; it
	// exists solely to ease transitioning of a private service to this
	// library. It will likely be removed at some point.
	Check(signature string) (CheckResponse, error)
}

Service defines the contract for anything that can perform locking operations.

type ServiceBootstrap

type ServiceBootstrap interface {
	OpenService() Service
	CloseService() error
}

ServiceBootstrap is responsible for initializing and cleaning up a service during testing.

type ServiceDebug

type ServiceDebug interface {
	SetDuration(time.Duration)
}

ServiceDebug provides debugging functions on services. A nice service will only implement during testing.

type ServiceOpts

type ServiceOpts struct {
	Table      string        // Name of the table with lock data. NOTE: The package will manage this table, deleting it at will.
	Duration   time.Duration // The duration before the lock expires.
	TimeToLive time.Duration // Non-empty values will enable time to live on the lock table and expire items after the duration.
}

ServiceOpts provides standard options when constructing a service.

type UnlockOpts

type UnlockOpts struct {
}

UnlockOpts is a placeholder in case we ever have options.

type UnlockRequest

type UnlockRequest struct {
	Signature string `json:"signature,omitempty"` // The ID for this lock
	Signee    string `json:"signee,omitempty"`    // The owner requesting the lock
}

UnlockRequest provides the parameters to the Unlock function.

func (UnlockRequest) IsValid

func (r UnlockRequest) IsValid() bool

type UnlockResponse

type UnlockResponse struct {
	Status UnlockResponseStatus `json:"status,omitempty"`
}

UnlockResponse provides the output from the Unlock function.

func (*UnlockResponse) Ok

func (r *UnlockResponse) Ok() bool

Ok answers true if the lock no longer exists.

type UnlockResponseStatus

type UnlockResponseStatus int

UnlockResponseStatus defines a status code for the response.

const (
	UnlockFailed UnlockResponseStatus = iota // Someone else owns the lock
	UnlockOk                                 // The lock was unlocked, no one owns it
	UnlockNoLock                             // Technically I succeeded - there was nothing to unlock.
)

The status codes for the Unlock response.