bitset

README

bitset

A simple bit set with JSON support

Motivation

The package built specially to be used in package github.com/axkit/aaa as a JWT permissions holder but can be used independently.

Concepts

• Application functionality can be limited by using permissions.
• Permission (access right) represented by unique string code.
• Application supports many permissions.
• A user has a role.
• A role is set of allowed permission, it's subset of all permissions supported by application.
• As a result of successful sign in, a backend provides access and refresh tokens.
• The payload of access token have list of allowed permissions.
• A single permission code looks like "Customers.Create", "Customer.AttachDocuments", "Customer.Edit", etc.
• Store allowed permission codes could increase token size.
• Bitset comes here.
• Every permission shall be associated with a single bit in the set.
• Bitset adds to the token as hexadecimal string. Every 8 permissions represented by 2 characters.

Usage Examples

Sign In

    var perms bitset.Bitset
    perms.Set(1)                    // 0000_0010
    perms.Set(2)                    // 0000_0110
    perms.Set(8, 10)                // 0000_0110 0000_0101
    tokenPerms := perms.String()    // returns "0605" as hex representation of 0000_0110 0000_0101

Check allowed permission in auth middleware

    ...
    tokenPerms := accessToken.Payload.Perms     // "0605"
    bs, err := bitset.Parse(tokenPerms)         // returns 0000_0110 0000_0101
    if bs.AreSet(2,8) {
        // the permission allowed
    }

Further Improvements

• Finalize integration BitSet with database/sql
• Add benchmarks
• Reduce memory allocations

Prague 2020

Documentation

Index

• Variables
• func AreSet(buf []byte, bitpos ...uint) (bool, error)
• type BitSet
  • func Clone(bs BitSet) BitSet
  • func New(size uint) *BitSet
  • func Parse(buf []byte) (BitSet, error)
  • func (bs *BitSet) AnySet(bitpos ...uint) bool
  • func (bs *BitSet) AreSet(bitpos ...uint) bool
  • func (bs *BitSet) Bytes() []byte
  • func (bs *BitSet) IsAllocated(bitpos uint) bool
  • func (bs *BitSet) IsSet(bitpos uint) bool
  • func (bs *BitSet) Len() uint
  • func (bs *BitSet) Reset(bitpos uint)
  • func (bs *BitSet) Scan(value interface{}) error
  • func (bs *BitSet) Set(bitpos ...uint) *BitSet
  • func (bs *BitSet) String() string
  • func (bs *BitSet) Valid() bool
  • func (bs BitSet) Value() (driver.Value, error)

Variables

var ErrParseFailed = errors.New("invalid character found")

ErrParseFailed returns if Parse function found character out of ranges 0..9, a..f, A..F

Functions

func AreSet

func AreSet(buf []byte, bitpos ...uint) (bool, error)

AreSet recieves string representation of BitSet and returns true if every bit with position bitpos is equal 1.

Types

type BitSet

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

BitSet holds set of bits using slice of bytes.

func Clone

func Clone(bs BitSet) BitSet

Clone clones bs.

func New

func New(size uint) *BitSet

New creates BitSet with allocated space for size amount of bits.

func Parse

func Parse(buf []byte) (BitSet, error)

Parse converts []byte to BitSet.

func (*BitSet) AnySet

func (bs *BitSet) AnySet(bitpos ...uint) bool

AnySet returns true if at least one bit with position bitpos is equal 1.

func (*BitSet) AreSet

func (bs *BitSet) AreSet(bitpos ...uint) bool

AreSet returns true if every bit with position bit pos is equal 1. Return false if bitops or bs are empty.

func (*BitSet) Bytes

func (bs *BitSet) Bytes() []byte

Bytes returns bitset as byte slice.

func (*BitSet) IsAllocated

func (bs *BitSet) IsAllocated(bitpos uint) bool

IsAllocated returns true if space for the bit with position bitpos is allocated already.

func (*BitSet) IsSet

func (bs *BitSet) IsSet(bitpos uint) bool

IsSet returns true if bit with position bitpos is 1. Returns false if bitpos above maximal available bitpos.

func (*BitSet) Len

func (bs *BitSet) Len() uint

Len returns len of allocated byte slice.

func (*BitSet) Reset

func (bs *BitSet) Reset(bitpos uint)

Reset sets bit with position bitpos to 0. Does not resize internal storage.

func (*BitSet) Scan

func (bs *BitSet) Scan(value interface{}) error

Scan implements database/sql Scanner. It's expected that PostgreSQL type BIT VARYING is used.

func (*BitSet) Set

func (bs *BitSet) Set(bitpos ...uint) *BitSet

Set sets bits to 1. Extends internal storage if it's required.

func (*BitSet) String

func (bs *BitSet) String() string

String returns hex representation of bit array. Every 8 bits presented as 2 hex digits.

func (*BitSet) Valid

func (bs *BitSet) Valid() bool

Valid returns true if at least one bit is set.

func (BitSet) Value

func (bs BitSet) Value() (driver.Value, error)

Value implements database/sql Valuer.