bitset

README

bitset

A simple bit set with JSON support

Motivation

The package built specially for usage in JWT tokens in package github.com/axkit/aaa

Concepts

• Application functionality can be limited by using permissions.
• Permission (access right) represented by unique string code.
• Application can have 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 succesfull sign in backend provides access and resresh tokens.
• Payload of access token shall 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 accociated with a single bit in the set.
• Bitset adds to the token as hexadecimal string.

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"

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) AreSet(bitpos ...uint) bool
  • 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)
  • 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) 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) 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 setted 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 PostgresSQL type BIT VARYING is used.

func (*BitSet) Set

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

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 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.