etcdstore

README

etcdstore

A etcd based session store for SCS.

Setup

You should follow the instructions to setup a connection, and pass the connection to etcdstore.New() to establish the session store.

Example

package main

import (
	"io"
	"net/http"

	"github.com/alexedwards/scs/v2"
	"github.com/alexedwards/scs/etcdstore"
	clientv3 "go.etcd.io/etcd/client/v3"
)

var sessionManager *scs.SessionManager

func main() {
	// Establish connection to etcd.
	cli, err := clientv3.New(clientv3.Config{
		Endpoints:   []string{"host:2379"},
		DialTimeout: 5 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer cli.Close()
	
	// Initialize a new session manager and configure it to use etcdstore as the session store.
	sessionManager = scs.New()
	sessionManager.Store = etcdstore.New(cli)

	mux := http.NewServeMux()
	mux.HandleFunc("/put", putHandler)
	mux.HandleFunc("/get", getHandler)

	http.ListenAndServe(":4000", sessionManager.LoadAndSave(mux))
}

func putHandler(w http.ResponseWriter, r *http.Request) {
	sessionManager.Put(r.Context(), "message", "Hello from a session!")
}

func getHandler(w http.ResponseWriter, r *http.Request) {
	msg := sessionManager.GetString(r.Context(), "message")
	io.WriteString(w, msg)
}

Expired Session Cleanup

Etcd will automatically remove expired session keys.

Key Collisions

By default keys are in the form scs:session:<token>. For example:

"scs:session:ZnirGwi2FiLwXeVlP5nD77IpfJZMVr6un9oZu2qtJrg"

Because the token is highly unique, key collisions are not a concern. But if you're configuring multiple session managers, both of which use etcdstore, then you may want the keys to have a different prefix depending on which session manager wrote them. You can do this by using the NewWithPrefix() method like so:

cli, err := clientv3.New(clientv3.Config{
	Endpoints:   []string{"host:2379"},
	DialTimeout: 5 * time.Second,
})
if err != nil {
	log.Fatal(err)
}
defer cli.Close()

sessionManagerOne = scs.New()
sessionManagerOne.Store = etcdstore.NewWithPrefix(cli, "scs:session:1:")

sessionManagerTwo = scs.New()
sessionManagerTwo.Store = etcdstore.NewWithPrefix(cli, "scs:session:2:")

Documentation

Index

• type EtcdStore
  • func New(client *clientv3.Client) *EtcdStore
  • func NewWithPrefix(client *clientv3.Client, prefix string) *EtcdStore
  • func (e *EtcdStore) AllCtx(ctx context.Context) (map[string][]byte, error)
  • func (e *EtcdStore) Commit(token string, b []byte, expiry time.Time) error
  • func (e *EtcdStore) CommitCtx(ctx context.Context, token string, b []byte, expiry time.Time) error
  • func (e *EtcdStore) Delete(token string) error
  • func (e *EtcdStore) DeleteCtx(ctx context.Context, token string) error
  • func (e *EtcdStore) Find(token string) ([]byte, bool, error)
  • func (e *EtcdStore) FindCtx(ctx context.Context, token string) (b []byte, exists bool, err error)

Types

type EtcdStore

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

EtcdStore represents the session store.

func New

func New(client *clientv3.Client) *EtcdStore

New returns a new EtcdStore instance. The client parameter should be a pointer to a etcd client instance.

func NewWithPrefix

func NewWithPrefix(client *clientv3.Client, prefix string) *EtcdStore

NewWithPrefix returns a new EtcdStore instance. The client parameter should be a pointer to a etcd client instance. The prefix parameter controls the etcd key prefix, which can be used to avoid naming clashes if necessary.

func (*EtcdStore) AllCtx

func (e *EtcdStore) AllCtx(ctx context.Context) (map[string][]byte, error)

AllCtx returns a map containing the token and data for all active (i.e. not expired) sessions in the EtcdStore instance.

func (*EtcdStore) Commit

func (e *EtcdStore) Commit(token string, b []byte, expiry time.Time) error

func (*EtcdStore) CommitCtx

func (e *EtcdStore) CommitCtx(ctx context.Context, token string, b []byte, expiry time.Time) error

CommitCtx adds a session token and data to the EtcdStore instance with the given expiry time. If the session token already exists then the data and expiry time are updated.

func (*EtcdStore) Delete

func (e *EtcdStore) Delete(token string) error

func (*EtcdStore) DeleteCtx

func (e *EtcdStore) DeleteCtx(ctx context.Context, token string) error

DeleteCtx removes a session token and corresponding data from the EtcdStore instance.

func (*EtcdStore) Find

func (e *EtcdStore) Find(token string) ([]byte, bool, error)

func (*EtcdStore) FindCtx

func (e *EtcdStore) FindCtx(ctx context.Context, token string) (b []byte, exists bool, err error)

FindCtx returns the data for a given session token from the EtcdStore instance. If the session token is not found or is expired, the returned exists flag will be set to false.