fst

README

fst

fst is a high-performance, lightweight library for generating and parsing Fast Signed Token (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 test results and source code for the tests are available on https://github.com/Eugene-Usachev/fst/tree/main/benchmarks.

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:     []byte(`postfix`),
    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 a new converter

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

Attention, please!

For work with the browser and HTTP in general, use EncodedConverter! But if you don't need it, you can use Converter instead, as it is faster and more lightweight.

To create EncodedConverter call NewEncodedConverter with ConverterConfig

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

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

License

The fst library is released under the MIT License.

Documentation

Overview

Package fst is a high-performance, lightweight 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.

For work with the browser and HTTP in general, use EncodedConverter! But if you don't need it, you can use Converter instead, as it is faster and more lightweight.

See https://github.com/Eugene-Usachev/fst/tree/main/example

Index

• Variables
• type Converter
  • func NewConverter(cfg *ConverterConfig) *Converter
  • func (c *Converter) ExpireTime() time.Duration
  • func (c *Converter) NewToken(value []byte) []byte
  • func (c *Converter) ParseToken(token []byte) ([]byte, error)
  • func (c *Converter) Postfix() []byte
  • func (c *Converter) SecretKey() []byte
• type ConverterConfig
• type EncodedConverter
  • func NewEncodedConverter(cfg *ConverterConfig) *EncodedConverter
  • func (c *EncodedConverter) NewToken(id []byte) string
  • func (c *EncodedConverter) ParseToken(token string) ([]byte, error)

Variables

var (
	// InvalidTokenFormat means that the token is malformed.
	InvalidTokenFormat = errors.New("Invalid token format")
	// InvalidSignature means that the token is forged.
	InvalidSignature = errors.New("Invalid signature")
	// TokenExpired means that the token is expired.
	TokenExpired = errors.New("Token expired")
)

Types

type Converter

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

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

Be careful!

Browsers cannot use this! To work with the browser and HTTP in general, use EncodedConverter!

Example:

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

	token := converter.NewToken([]byte(`token`))
	fmt.Println(string(token)) //s♣�♠����▬]>¶4s\n'�a→Jtoken

	value, err := converter.ParseToken(token)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(string(value)) // token

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

	tokenWithEx := converterWithExpirationTime.NewToken([]byte(`token`))
	fmt.Println(string(tokenWithEx)) // Something like k:�e 6��Y�ٟ→%��v◄5t��+�v▬���<�+�token

	value, err = converterWithExpirationTime.ParseToken(tokenWithEx)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(string(value)) // 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:        []byte(`postfix`),
    ExpirationTime: time.Minute * 5,
    HashType:       sha256.New,
})

func (*Converter) ExpireTime

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

ExpireTime returns the expiration time used by the Converter.

func (*Converter) NewToken

func (c *Converter) NewToken(value []byte) []byte

NewToken creates a new FST with the provided value. This method does not encode the token in base64.

func (*Converter) ParseToken

func (c *Converter) ParseToken(token []byte) ([]byte, error)

ParseToken parses a FST and returns the value. This method will use token to return the value, instead of copying.

It can return errors like InvalidTokenFormat, InvalidSignature, TokenExpired.

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
}

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. It is zero by default and will not expire.

HashType is the hash function used to sign the token.

type EncodedConverter

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

EncodedConverter represents a token converter that can generate and parse Fast Signed Tokens that are encoded.

Attention!

Browsers can use this, but if you don't need it, you can use Converter instead, as it is faster and more lightweight.

Example:

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

	token := converter.NewToken([]byte(`token`))
	fmt.Println(token) //IOlBEQ49K_6CYh8OPhQ0cw1zBdEGxfaMhxZdCyekYRpKdG9rZW4=

	value, err := converter.ParseToken(token)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(string(value)) // token

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

	tokenWithEx := converterWithExpirationTime.NewToken([]byte(`token`))
	fmt.Println(tokenWithEx) // Something like azriZQAAAAAgNujiWdAI6NmfGiWnt3YRNXSD1ivpdhb-8-Y8_bIIK7h0b2tlbg==

	value, err = converterWithExpirationTime.ParseToken(tokenWithEx)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(string(value)) // token

func NewEncodedConverter

func NewEncodedConverter(cfg *ConverterConfig) *EncodedConverter

NewEncodedConverter creates a new instance of the EncodedConverter based on the provided fst.ConverterConfig.

Example of the usage:

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

func (*EncodedConverter) NewToken

func (c *EncodedConverter) NewToken(id []byte) string

NewToken creates a new FST with the provided value. This method encodes the token in base64.

func (*EncodedConverter) ParseToken

func (c *EncodedConverter) ParseToken(token string) ([]byte, error)

ParseToken parses a FST and returns the value. This method will copy the token's value.

It can return errors like InvalidTokenFormat, InvalidSignature, TokenExpired.