andromeda

andromeda is a golang package that can be implemented on an object that has quotas.

Feature Overview

Add and reduce quota usage
Handle race conditions
Can be applied to multiple quotas
Reversible if an error occurs
Handling if quota usage is not exists in redis
Can be implemented according to your needs

Use cases

Flash sale
Claim vouchers
etc

Getting Started

Prerequisites

andromeda requires redis to store quota data, make sure your machine has it.

Installation

go get github.com/ramadani/andromeda

Guide

A quota consists of limits and usage. so the entity that you have must have these 2 attributes.

There are 4 functions that you need to prepare for each of your quota.

Get quota limit
Get the limit of a quota. Limit is used to keep usage from exceeding the limit.
Get quota usage
Get updated usage of a quota. This function will be called if the quota usage is not in Redis. After the value of the quota usage is obtained, the value will be saved to redis according to its key and expiration.
Get quota usage key
Generate key that will be used to store and get quota usage stored in redis.
Get quota usage expiration
Expiration is used to set how long the duration of a quota usage is stored in Redis.

Example

For example, we will use claim voucher use case.

type Voucher struct {
	ID    string
	Code  string
	Limit int64
	Usage int64
}

To get quota limit and usage, we create code using GetQuota interface

Get quota limit

type getVoucherQuotaLimit struct {
	voucherRepo VoucherRepository
}

func (v *getVoucherQuotaLimit) Do(ctx context.Context, req *andromeda.QuotaRequest) (int64, error) {
	voucher, err := v.voucherRepo.FindByID(ctx, req.QuotaID)
	if err != nil {
		return 0, err
	}

	return voucher.Limit, nil
}

func NewGetVoucherQuotaLimit(voucherRepo VoucherRepository) andromeda.GetQuota {
	return &getVoucherQuotaLimit{voucherRepo: voucherRepo}
}

Get quota usage

type getVoucherQuotaUsage struct {
	voucherRepo VoucherRepository
}

func (v *getVoucherQuotaUsage) Do(ctx context.Context, req *andromeda.QuotaRequest) (int64, error) {
	voucher, err := v.voucherRepo.FindByID(ctx, req.QuotaID)
	if err != nil {
		return 0, err
	}

	return voucher.Usage, nil
}

func NewGetVoucherQuotaUsage(voucherRepo VoucherRepository) andromeda.GetQuota {
	return &getVoucherQuotaUsage{voucherRepo: voucherRepo}
}

To get quota usage key, we create code using GetQuotaKey interface

Get quota usage key

type getVoucherQuotaUsageKey struct {
	keyFormat string
}

func (v *getVoucherQuotaUsageKey) Do(_ context.Context, req *andromeda.QuotaRequest) (string, error) {
	return fmt.Sprintf(v.keyFormat, req.QuotaID), nil
}

func NewGetVoucherQuotaUsageKey(keyFormat string) andromeda.GetQuotaKey {
	return &getVoucherQuotaUsageKey{keyFormat: keyFormat}
}

To get quota usage expiration, we create code using the GetQuotaExpiration interface

Get quota usage expiration

type getVoucherQuotaUsageExpiration struct{}

func (v *getVoucherQuotaUsageExpiration) Do(ctx context.Context, req *andromeda.QuotaRequest) (time.Duration, error) {
	return time.Hour * 5, nil
}

func NewGetVoucherQuotaUsageExpiration() andromeda.GetQuotaExpiration {
	return &getVoucherQuotaUsageExpiration{}
}

Then use these 4 code implementations to create add quota usage and reduce quota usage functions

keyUsageFormat := "voucher-quota-usage-%s"
getVoucherQuotaLimit := internal.NewGetVoucherQuotaLimit(voucherRepo)
getVoucherQuotaUsage := internal.NewGetVoucherQuotaUsage(voucherRepo)
getVoucherQuotaUsageKey := internal.NewGetVoucherQuotaUsageKey(keyUsageFormat)
getVoucherQuotaUsageExpiration := internal.NewGetVoucherQuotaUsageExpiration()
getVoucherQuotaUsageConf := andromeda.GetQuotaUsageConfig{
	LockIn:   time.Second * 3,
	MaxRetry: 10,
	RetryIn:  time.Millisecond * 100,
}

addVoucherUsage := andromeda.AddQuotaUsage(andromeda.AddQuotaUsageConfig{
	Cache:                   cacheRedis,
	GetQuotaLimit:           getVoucherQuotaLimit,
	GetQuotaUsage:           getVoucherQuotaUsage,
	GetQuotaUsageKey:        getVoucherQuotaUsageKey,
	GetQuotaUsageExpiration: getVoucherQuotaUsageExpiration,
	GetQuotaUsageConfig:     getVoucherQuotaUsageConf,
})

reduceVoucherUsage := andromeda.ReduceQuotaUsage(andromeda.ReduceQuotaUsageConfig{
	Cache:                   cacheRedis,
	GetQuotaUsage:           getVoucherQuotaUsage,
	GetQuotaUsageKey:        getVoucherQuotaUsageKey,
	GetQuotaUsageExpiration: getVoucherQuotaUsageExpiration,
	GetQuotaUsageConfig:     getVoucherQuotaUsageConf,
})

use these functions in your logic code

func (c *claimVoucher) Do(ctx context.Context, code, userID string) (*History, error) {
	voucher, err := c.voucherRepo.FindByCode(ctx, code)
	if err != nil {
		return nil, err
	}

	history := &History{
		ID:        uuid.NewV4().String(),
		VoucherID: voucher.ID,
		UserID:    userID,
		CreatedAt: time.Now(),
	}

	usageReq := andromeda.QuotaUsageRequest{
		QuotaID: voucher.ID,
		Usage:   1,
	}

	if _, err = c.addVoucherUsage.Do(ctx, &usageReq); err != nil {
		return nil, err
	}

	if err = c.historyRepo.Create(ctx, history); err == nil {
		return history, nil
	}

	// has error, do reverse usage quota
	if _, er := c.reduceVoucherUsage.Do(ctx, &usageReq); er != nil {
		err = er
	}

	return nil, err
}

Listener

You can implement a listener to know the events on success or error using the UpdateQuotaUsageListener interface.

type updateVoucherQuotaUsageListener struct{}

func (v *updateVoucherQuotaUsageListener) OnSuccess(ctx context.Context, req *andromeda.QuotaUsageRequest, updatedUsage int64) {
	log.Println("updated quota", updatedUsage)
}

func (v *updateVoucherQuotaUsageListener) OnError(ctx context.Context, req *andromeda.QuotaUsageRequest, err error) {
	log.Println("err", err)
}

func NewUpdateVoucherQuotaUsageListener() andromeda.UpdateQuotaUsageListener {
	return &updateVoucherQuotaUsageListener{}
}

Add the listener to the option

updateVoucherQuotaUsageListener := internal.NewUpdateVoucherQuotaUsageListener()

addVoucherUsage := andromeda.AddQuotaUsage(andromeda.AddQuotaUsageConfig{
	Cache:                   cacheRedis,
	GetQuotaLimit:           getVoucherQuotaLimit,
	GetQuotaUsage:           getVoucherQuotaUsage,
	GetQuotaUsageKey:        getVoucherQuotaUsageKey,
	GetQuotaUsageExpiration: getVoucherQuotaUsageExpiration,
	GetQuotaUsageConfig:     getVoucherQuotaUsageConf,
	Option: andromeda.AddUsageOption{
		Listener: updateVoucherQuotaUsageListener,
	},
})

reduceVoucherUsage := andromeda.ReduceQuotaUsage(andromeda.ReduceQuotaUsageConfig{
	Cache:                   cacheRedis,
	GetQuotaUsage:           getVoucherQuotaUsage,
	GetQuotaUsageKey:        getVoucherQuotaUsageKey,
	GetQuotaUsageExpiration: getVoucherQuotaUsageExpiration,
	GetQuotaUsageConfig:     getVoucherQuotaUsageConf,
	Option: andromeda.ReduceUsageOption{
		Listener: updateVoucherQuotaUsageListener,
	},
})

Check out the examples to find out more

Tips

Use job scheduling to update usage from redis to database
Set expiration is longer than the original quota time. For example, the quota period is only 3 days, the set expiration is more than 3 days so that the value in redis will still be there when the job scheduling period is still running
To get the quota limit, you can save it to redis so that it doesn't always get it from the database

Contributing

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

ramadani / andromeda