lock

Documentation

Overview

Package lock contains helper functions for maintaining a lock table and utilizing it to guard critical sections in the code.

Index

• func AcquireLock(options *Options) error
• func GetLockStatus(options *Options) (*dynamodb.GetItemOutput, error)
• func NewAuthenticatedSession(awsRegion string) (*session.Session, error)
• func NewDynamoDb(awsRegion string) (*dynamodb.DynamoDB, error)
• func ReleaseLock(options *Options) error
• func ScanLocks(options *Options) ([]string, error)
• type Lock
• type Options
• type TableNotActiveError
  • func (err TableNotActiveError) Error() string
• type TimeoutExceeded
  • func (err TimeoutExceeded) Error() string

Functions

func AcquireLock

func AcquireLock(options *Options) error

AcquireLock will attempt to acquire a lock in DynamoDB table while taking the configuration options into account. We are using DynamoDB to create a table to help us track the lock status of different resources. The acquiring of a lock attempts to create a table. The intention is that we have 1 table per resource in a single region. This would allow the locking mechanism to flexibly decide if a resource is locked or not. For test cases where the AWS resource is multi-region, or global, the configuration of which regions to use should reflect that.

func GetLockStatus

func GetLockStatus(options *Options) (*dynamodb.GetItemOutput, error)

GetLockStatus attempts to acquire the lock and check if the expected item is there If there's the expected Item with the correct `LockString` value - then the status is `locked`, if the item is not there - then the status is `not locked`

func NewAuthenticatedSession

func NewAuthenticatedSession(awsRegion string) (*session.Session, error)

NewAuthenticatedSession gets an AWS Session, checking that the user has credentials properly configured in their environment

func NewDynamoDb

func NewDynamoDb(awsRegion string) (*dynamodb.DynamoDB, error)

NewDynamoDb returns an authenticated client object for accessing DynamoDb

func ReleaseLock

func ReleaseLock(options *Options) error

ReleaseLock will attempt to release the lock defined by the provided lock string in the configured lock table for the configured region

func ScanLocks

func ScanLocks(options *Options) ([]string, error)

ScanLocks will perform a scan operation on the indicated DynamoDB table. This operation is useful in certain cases, for example when we want to generate a report of all currently active ref arch deployments tracked in our lock table. It returns a slice of strings representing a list of lock IDs on the table that are currently held

Types

type Lock

type Lock struct {
	// In the DynamoDB lock table, "LockID" will be the key and the deployment URL will be the value
	ID string `json:"LockID"`
}

type Options

type Options struct {
	// The AWS region for which you wish to create the distributed lock for. For example, if set  to `us-east-1`,
	// the lock will create a DynamoDB table and record for the AWS resource (e.g. Security Hub) in the same region to mark it as locked.
	// This means if the same AWS resource (Security Hub) is then reference from a different part of the system, also using this lock mechanism,
	// the resource will appear as it's locked already and therefore not available to modify.
	AwsRegion string
	// The name of the DynamoDB table that will store the lock status for the resource in the given region.
	LockTable string
	// The name of the DynamoDB Item value that will store the lock status for the resource in the given region.
	LockString string
	// The value for how many times AcquireLock will retry to acquire the lock
	MaxRetries int
	// The value for how long AcquireLock will sleep for between retries to get the lock
	SleepBetweenRetries time.Duration
	// The logger to use for the lock
	Logger *logrus.Logger

	// Custom session to use to authenticate to AWS in the SDK. If nil, constructs the session based on the default
	// authentication chain in the SDK.
	AwsSession *session.Session
}

type TableNotActiveError

type TableNotActiveError struct {
	LockTable string
}

func (TableNotActiveError) Error

func (err TableNotActiveError) Error() string

type TimeoutExceeded

type TimeoutExceeded struct {
	LockTable  string
	LockString string
	Timeout    time.Duration
}

func (TimeoutExceeded) Error

func (err TimeoutExceeded) Error() string