mnemosyne

README

Mnemosyne

Introduction

Mnemosyne is an open-source self-hosted session management service. It's written in Go, making it easy to build and deploy as a static binary.

It provides two ways for communication:

• Mnemosyne - Simplified way that hides complexity of gRPC library.
• RPCClient - Full feature client.

Quick Start

To install and run service:

$ go get -d github.com/piotrkowalczuk/mnemosyne/...
$ cd $GOPATH/src/github.com/piotrkowalczuk/mnemosyne
$ glide install
$ go install ./cmd/mnemosyned
$ mnemosyned -l.format=humane -s.p.address='postgres://localhost/example?sslmode=disable'

Simpliest implementation could looks like that:

package main

import (
	"fmt"

	"golang.org/x/net/context"
	"github.com/piotrkowalczuk/mnemosyne"
)

func main() {
	mnemo, err := mnemosyne.New(mnemosyne.MnemosyneOpts{
		Addresses: []string{"127.0.0.1:8080"},
		Block: true,
	})
	if err != nil {
		// ...
	}
	defer mnemo.Close()

	ses, err := mnemo.Start(context.Background(), "subject-id", "subject-client", map[string]string{
		"username": "johnsnow@gmail.com",
		"first_name": "John",
		"last_name": "Snow",
	})
	if err != nil {
		// ...
	}

	fmt.Println(ses.AccessToken.Encode())
}

Storage Engine

Goal is to support multiple storage's, like PostgreSQL, Redis or MongoDB. Nevertheless currently supported is only PostgreSQL.

Remote Procedure Call API

For communication, Mnemosyne is exposing RPC API that uses protocol buffers, Google’s mature open source mechanism for serializing structured data.

• Create
• Get
• List
• Exists
• Abandon
• SetData
• Delete

Installation

Mnemosyne can be installed in two ways, from source and using deb package that can be found in dist directory.

From source

To install from source both go tools and glide is required.

$ go get -d github.com/piotrkowalczuk/mnemosyne/...
$ cd $GOPATH/src/github.com/piotrkowalczuk/mnemosyne
$ glide install
$ go install ./cmd/mnemosyned

Configuration

mnemosyned accepts command line arguments to control its behavior. Possible options are is listed below.

Name	Flag	Default	Type
host	-host	127.0.0.1	string
port	-port	8080	int
time to live	-ttl	24m	duration
time to clear	-ttc	1m	duration
logger format	-l.format	json	enum(json, humane, logfmt)
logger adapter	-l.adapter	stdout	enum(stdout)
namespace	-namespace	string
subsystem	-subsystem	mnemosyne	string
monitoring engine	-m.engine	prometheus	enum(prometheus)
storage engine	-s.engine	postgres	enum(postgres)
storage postgres address	-s.p.address	postgres://localhost:5432?sslmode=disable	string
storage postgres table name	-s.p.table	mnemosyne_session	string
tls	-tls	false	boolean
tls certificate file	-tls.certfile		string
tls key file	-tls.keyfile		string

Running

As we know, mnemosyne can be configured in many ways. For the beginning we can start simple:

$ mnemosyned -namespace=acme -s.p.address="postgres://localhost/test?sslmode=disable"

Mnemosyne will automatically create all required tables/indexes for specified database.

Contribution

TODO

• Client library
  • Go
  • Python
• Engines
  • PostgreSQL
    • Get
    • List
    • Exists
    • Create
    • Abandon
    • SetData
    • Delete
    • Setup
    • TearDown
  • RAM
  • Redis

Building

Increment version in mnemosynd/config.go. Execute make package.

Changes to flags or flag value defaults should be into scripts/mnemosyne.service and mnemosyne.env.

Documentation

Index

• type Mnemosyne
  • func New(opts MnemosyneOpts) (Mnemosyne, error)
• type MnemosyneOpts

Types

type Mnemosyne

type Mnemosyne interface {
	Close() error
	FromContext(ctx context.Context) (ses *mnemosynerpc.Session, err error)
	Get(ctx context.Context, token string) (ses *mnemosynerpc.Session, err error)
	Start(ctx context.Context, subjectID string, subjectClient string, bag map[string]string) (ses *mnemosynerpc.Session, err error)
	Exists(ctx context.Context, token string) (bool, error)
	Abandon(ctx context.Context, token string) error
	SetValue(ctx context.Context, token, key, value string) (bag map[string]string, err error)
}

Mnemosyne ...

func New

func New(opts MnemosyneOpts) (Mnemosyne, error)

New allocates new mnemosyne instance.

type MnemosyneOpts

type MnemosyneOpts struct {
	Metadata []string
	// Only one supported now.
	Addresses   []string
	UserAgent   string
	Certificate *x509.CertPool
	Block       bool
	Timeout     time.Duration
}

MnemosyneOpts ...