fst

README

fst

fst is a high-performance, low-memory library for generating and parsing Fast Signed Tokens (FST). FST provides an alternative to JSON-based tokens and allows you to store any information that can be represented as []byte. You can use FST for the same purposes as JWT.

Description

fst is designed to be efficient and lightweight, making it ideal for applications that require fast token generation and parsing. With its optimized algorithms and data structures, fst minimizes memory usage and maximizes performance.

Performance

fst excels in terms of performance, especially when compared to traditional token formats like JSON Web Tokens (JWT). By leveraging its unique token structure and optimized parsing algorithms, fst significantly reduces the overhead associated with token generation and parsing.

To demonstrate the performance benefits of fst, we conducted a series of tests using various tokens sizes. The results are as follows:

Parse

speed in ns/op (less is better)

speed in total repetitions (more is better)

memory in bytes/op (less is better)

allocs in allocs/op (less is better)

Generate

speed in ns/op (less is better)

speed in total repetitions (more is better)

memory in bytes/op (less is better)

allocs in allocs/op (less is better)

Parallel parse

speed in ns/op (less is better)

speed in total repetitions (more is better)

Parallel generate

speed in ns/op (less is better)

speed in total repetitions (more is better)

To learn more about benchmarks, you can visit the benchmarks folder. There you will find the source code and data in the form of a table.

Installation

Install fst with the go get command:

go get github.com/Eugene-Usachev/fst

Example

You can see the examples in the example folder.

First you need to create a `Converter'. You can do it like this

converter := fst.NewConverter(&fst.ConverterConfig{
    SecretKey:   []byte(`secret`),
    Postfix:     nil,
    HashType:    sha256.New,
})

Then you can create a token using the NewToken

token := converter.NewToken([]byte(`token`))

To parse tokens, you can use the ParseToken

value, err := converter.ParseToken(token)

If you want to set expiration time create new converter

converterWithExpirationTime := fst.NewConverter(&fst.ConverterConfig{
    SecretKey:          []byte(`secret`),
    Postfix:            nil,
    ExpirationTime:     time.Minute * 5,
    HashType:           sha256.New,
    WithExpirationTime: true,
})

License

The fst library is released under the MIT License.

Documentation

Overview

Package fst is a high-performance, low-memory library for generating and parsing Fast Signed Tokens (FST). FST provides an alternative to JSON-based tokens and allows you to store any information that can be represented as []byte. You can use FST for the same purposes as JWT.

Index

• Variables
• type Converter
  • func NewConverter(cfg *ConverterConfig) *Converter
  • func (c *Converter) ExpireTime() time.Duration
  • func (c *Converter) Postfix() []byte
  • func (c *Converter) SecretKey() []byte
• type ConverterConfig

Variables

var (
	InvalidTokenFormat = errors.New("Invalid token format")
	InvalidSignature   = errors.New("Invalid signature")
	TokenExpired       = errors.New("Token expired")
)

Types

type Converter

type Converter struct {
	NewToken   func([]byte) string
	ParseToken func(string) ([]byte, error)
	// contains filtered or unexported fields
}

Converter represents a token converter that can generate and parse Fast Signed Tokens.

secretKey is the secret used to sign the token.

postfix is the postfix to add to the token to more secure the token.

hashType is the hash function used to sign the token.

timeBeforeExpire is the lifetime of the token.

hmacPool and expirationTime and timeNow are needed to improve performance.

NewToken is the function used to generate the token.

ParseToken is the function used to parse the token.

func NewConverter

func NewConverter(cfg *ConverterConfig) *Converter

NewConverter creates a new instance of the Converter based on the provided fst.ConverterConfig.

Example of the usage:

	converter := fst.NewConverter(&fst.ConverterConfig{
     SecretKey:      []byte(`secret`),
     Postfix:        nil,
     ExpirationTime: time.Minute * 5,
     HashType:       sha256.New,
     WithExpirationTime: true,
 })

func (*Converter) ExpireTime

func (c *Converter) ExpireTime() time.Duration

ExpireTime returns the expiration time used by the Converter.

func (*Converter) Postfix

func (c *Converter) Postfix() []byte

Postfix returns the postfix used by the Converter.

func (*Converter) SecretKey

func (c *Converter) SecretKey() []byte

SecretKey returns the secret key used by the Converter.

type ConverterConfig

type ConverterConfig struct {
	// SecretKey is the secret used to sign the token.
	SecretKey []byte
	// Postfix is the postfix to add to the token to more secure the token.
	Postfix []byte
	// ExpirationTime is the expiration time of the token.
	ExpirationTime time.Duration
	// HashType is the hash function used to sign the token.
	HashType func() hash.Hash

	WithExpirationTime bool
}

ConverterConfig represents the configuration options for creating a new Converter.

SecretKey is the secret used to sign the token.

Postfix is the postfix to add to the token to more secure the token.

ExpirationTime is the expiration time of the token.

HashType is the hash function used to sign the token.

WithExpirationTime is the flag to enable expiration time. By default, it is disabled.