sets3lock

README

sets3lock

Distributed locking using Amazon S3.

sets3lock provides a distributed locking mechanism backed by Amazon S3. It allows you to implement mutual exclusion across multiple processes or servers easily and cost-effectively using only S3, without the need to manage additional infrastructure like Redis or ZooKeeper.

INSTALL

# use sets3lock via CLI.
go get github.com/shogo82148/cmd/sets3lock

# use sets3lock as a library.
go install github.com/shogo82148/sets3lock@latest

USAGE

$ sets3lock [-nNxX] s3://bucket/key program [args...]
-n: No delay. If fn is locked by another process, sets3lock gives up.
-N: (Default.) Delay. If fn is locked by another process, sets3lock waits until it can obtain a new lock.
-x: If lock object creation/update fails or the lock cannot be obtained, sets3lock exits zero.
-X: (Default.) If lock object creation/update fails or the lock cannot be obtained, sets3lock prints an error message and exits nonzero.
-version: show version
-expire-grace-period: set expire grace period duration after TTL expiration

import "github.com/shogo82148/sets3lock"

func main() {
  ctx := context.Background()
  l, err := sets3lock.New(ctx, "s3://bucket/key")
  if err != nil {
    panic(err)
  }
  if _, err := l.LockWithErr(ctx); err != nil {
    panic(err)
  }
  defer func() {
    if err := l.UnlockWithErr(ctx); err != nil {
      panic(err)
    }
  }()

  // do something that requires mutual exclusion.
}

You need to allow s3:GetObject, s3:PutObject, s3:DeleteObject actions by your IAM policy.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::bucket/key"
    }
  ]
}

RELATED WORKS

• The setlock program (an utility of daemontools)
• moznion/go-setlock
• fujiwara/go-redis-setlock
• mashiike/setddblock

Documentation

Overview

Package sets3lock provides a distributed lock mechanism using Amazon S3.

Index

• func Recover(e any) error
• func WithAPIClient(client APIClient) func(*Options)
• func WithContext(ctx context.Context) func(*Options)
• func WithDelay(delay bool) func(*Options)
• func WithExpireGracePeriod(d time.Duration) func(*Options)
• func WithNoPanic() func(*Options)
• type APIClient
• type Locker
  • func New(ctx context.Context, rawurl string, opts ...func(*Options)) (*Locker, error)
  • func (l *Locker) ClearLastErr()
  • func (l *Locker) LastErr() error
  • func (l *Locker) Lock()
  • func (l *Locker) LockWithErr(ctx context.Context) (bool, error)
  • func (l *Locker) Unlock()
  • func (l *Locker) UnlockWithErr(ctx context.Context) error
• type Options

Functions

func Recover

func Recover(e any) error

Recover for Locker.Lock() and [Locker.Unlock()]() panic.

func WithAPIClient

func WithAPIClient(client APIClient) func(*Options)

WithAPIClient allows you to specify a custom S3 client for the locker.

func WithContext

func WithContext(ctx context.Context) func(*Options)

WithContext allows you to specify a context for the locker. The context will be used for all operations of the locker.

func WithDelay

func WithDelay(delay bool) func(*Options)

WithDelay will delay the acquisition of the lock if it fails to acquire the lock. This is similar to the N option of setlock. The default is delay enabled (true). Specify false if you want to exit immediately if Lock acquisition fails.

func WithExpireGracePeriod

func WithExpireGracePeriod(d time.Duration) func(*Options)

WithExpireGracePeriod specifies the grace period after the lease expires during which the lock can still be reclaimed.

If the grace period is greater than zero, the lock may be forcibly reacquired once both the lease has expired and the specified grace period has elapsed.

If the grace period is zero or negative, automatic reclamation is disabled; expired locks will remain until removed by S3's TTL mechanism.

func WithNoPanic

func WithNoPanic() func(*Options)

WithNoPanic changes the behavior so that it does not panic if an error occurs in the Locker.Lock() and Locker.Unlock() functions. Check the Locker.LastErr() function to see if an error has occurred when WithNoPanic is specified.

Types

type APIClient

type APIClient interface {
	HeadObject(ctx context.Context, params *s3.HeadObjectInput, optFns ...func(*s3.Options)) (*s3.HeadObjectOutput, error)
	PutObject(ctx context.Context, params *s3.PutObjectInput, optFns ...func(*s3.Options)) (*s3.PutObjectOutput, error)
	DeleteObject(ctx context.Context, params *s3.DeleteObjectInput, optFns ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)
}

APIClient is an interface for the S3 client used by Locker.

type Locker

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

Locker provides a Lock mechanism using Amazon S3.

func New

func New(ctx context.Context, rawurl string, opts ...func(*Options)) (*Locker, error)

New returns new Locker.

func (*Locker) ClearLastErr

func (l *Locker) ClearLastErr()

func (*Locker) LastErr

func (l *Locker) LastErr() error

func (*Locker) Lock

func (l *Locker) Lock()

Lock for implements sync.Locker.

func (*Locker) LockWithErr

func (l *Locker) LockWithErr(ctx context.Context) (bool, error)

LockWithErr try get lock. The return value of bool indicates whether the lock has been released. If true, it is lock granted.

func (*Locker) Unlock

func (l *Locker) Unlock()

Unlock implements sync.Locker.

func (*Locker) UnlockWithErr

func (l *Locker) UnlockWithErr(ctx context.Context) error

UnlockWithErr unlocks. It removes the lock object from S3.

type Options

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

Options are for changing the behavior of the lock mechanism.