kite: github.com/koding/kite/kontrol Index | Files | Directories

package kontrol

import "github.com/koding/kite/kontrol"

Package kontrol provides an implementation for the name service kite. It can be queried to get the list of running kites.

Index

Package Files

errors.go etcd.go handlers.go http.go idlock.go keypair.go kites.go kontrol.go node.go postgres.go storage.go

Constants

const (
    KontrolVersion = "0.0.4"
    KitesPrefix    = "/kites"
)

Variables

var (
    // TokenTTL - identifies the expiration time after which the JWT MUST NOT be
    // accepted for processing.
    TokenTTL = 48 * time.Hour

    // TokenLeeway - implementers MAY provide for some small leeway, usually
    // no more than a few minutes, to account for clock skew.
    TokenLeeway = 5 * time.Minute

    // DefaultPort is a default kite port value.
    DefaultPort = 4000

    // HeartbeatInterval is the interval in which kites are sending heartbeats
    HeartbeatInterval = time.Second * 10

    // HeartbeatDelay is the compensation interval which is added to the
    // heartbeat to avoid network delays
    HeartbeatDelay = time.Second * 20

    // UpdateInterval is the interval in which the key gets updated
    // periodically. Keeping it low increase the write load to the storage, so
    // be cautious when changing it.
    UpdateInterval = time.Second * 60

    // KeyTLL is the timeout in which a key expires. Each storage
    // implementation needs to set keys according to this Key. If a storage
    // doesn't support TTL mechanism (such as PostgreSQL), it should use a
    // background cleaner which cleans up keys that are KeyTTL old.
    KeyTTL = time.Second * 90
)
var (
    ErrQueryFieldsEmpty = errors.New("all query fields are empty")
    ErrNoKeyFound       = errors.New("no key pair found")
)
var ErrKeyDeleted = errors.New("key pair is removed")

ErrKeyDeleted is returned by Storage methods when requested key pair is no longer valid because it was deleted.

The caller upon receiving this error may decide to recreate / resign a new kitekey or token for the caller (update the key).

func GetQueryKey Uses

func GetQueryKey(q *protocol.KontrolQuery) (string, error)

getQueryKey returns the etcd key for the query.

type CachedStorage Uses

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

CachedStorage caches the requests that are going to backend and tries to lower the load on the backend

func NewCachedStorage Uses

func NewCachedStorage(backend KeyPairStorage, cache KeyPairStorage) *CachedStorage

NewCachedStorage creates a new CachedStorage

func (*CachedStorage) AddKey Uses

func (m *CachedStorage) AddKey(keyPair *KeyPair) error

func (*CachedStorage) DeleteKey Uses

func (m *CachedStorage) DeleteKey(keyPair *KeyPair) error

func (*CachedStorage) GetKeyFromID Uses

func (m *CachedStorage) GetKeyFromID(id string) (*KeyPair, error)

func (*CachedStorage) GetKeyFromPublic Uses

func (m *CachedStorage) GetKeyFromPublic(public string) (*KeyPair, error)

func (*CachedStorage) IsValid Uses

func (m *CachedStorage) IsValid(public string) error

type Etcd Uses

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

Etcd implements the Storage interface

func NewEtcd Uses

func NewEtcd(machines []string, log kite.Logger) *Etcd

func (*Etcd) Add Uses

func (e *Etcd) Add(k *protocol.Kite, value *kontrolprotocol.RegisterValue) error

func (*Etcd) Clear Uses

func (e *Etcd) Clear() error

func (*Etcd) Delete Uses

func (e *Etcd) Delete(k *protocol.Kite) error

func (*Etcd) Get Uses

func (e *Etcd) Get(query *protocol.KontrolQuery) (Kites, error)

func (*Etcd) Update Uses

func (e *Etcd) Update(k *protocol.Kite, value *kontrolprotocol.RegisterValue) error

func (*Etcd) Upsert Uses

func (e *Etcd) Upsert(k *protocol.Kite, value *kontrolprotocol.RegisterValue) error

type IdLock Uses

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

func NewIdlock Uses

func NewIdlock() *IdLock

New returns a new IdLock

func (*IdLock) Get Uses

func (i *IdLock) Get(id string) sync.Locker

Get returns a lock that is bound to a specific id.

type KeyPair Uses

type KeyPair struct {
    // ID is the unique id defining the key pair
    ID  string

    // Public key is used to validate tokens
    Public string

    // Private key is used to sign/generate tokens
    Private string
}

KeyPair defines a single key pair entity

func (*KeyPair) Validate Uses

func (k *KeyPair) Validate() error

type KeyPairStorage Uses

type KeyPairStorage interface {
    // AddKey adds the given key pair to the storage
    AddKey(*KeyPair) error

    // DeleteKey deletes the given key pairs from the storage
    DeleteKey(*KeyPair) error

    // GetKeyFromID retrieves the KeyPair from the given ID
    GetKeyFromID(id string) (*KeyPair, error)

    // GetKeyFromPublic retrieves the KeyPairs from the given public key.
    //
    // If the key is no longer valid and the storage is able to deterime
    // that it was deleted, the returned error is of *DeletedKeyPairError
    // type.
    GetKeyFromPublic(publicKey string) (*KeyPair, error)

    // Is valid checks if the given publicKey is valid or not. It's up to the
    // implementer how to implement it. A valid public key returns a nil error.
    //
    // If the key is no longer valid and the storage is able to deterime
    // that it was deleted, the returned error is of *DeletedKeyPairError
    // type.
    IsValid(publicKey string) error
}

KeyPairStorage is responsible of managing key pairs

type Kites Uses

type Kites []*protocol.KiteWithToken

Kites is a helpe type to work with a set of kites

func (Kites) Attach Uses

func (k Kites) Attach(token string)

Attach attaches the given token to each kite. It replaces any previous token.

func (*Kites) Filter Uses

func (k *Kites) Filter(constraint version.Constraints, keyRest string)

Filter filters out kites with the given constraints

func (*Kites) Shuffle Uses

func (k *Kites) Shuffle()

Shuffle shuffles the order of the kites. This is useful if you want send back a randomized list of kites.

type Kontrol Uses

type Kontrol struct {
    Kite *kite.Kite

    // MachineAuthenticate is used to authenticate the request in the
    // "handleMachine" method.  The reason for a separate auth function is, the
    // request must not be authenticated because clients do not have a kite.key
    // before they register to this machine. Also the requester can send a
    // authType argument which can be used to distinguish between several
    // authentication methods
    MachineAuthenticate func(authType string, r *kite.Request) error

    // MachineKeyPicker is used to choose the key pair to generate a valid
    // kite.key file for the "handleMachine" method. This overrides the default
    // last keypair added with kontrol.AddKeyPair method.
    MachineKeyPicker func(r *kite.Request) (*KeyPair, error)

    // TokenTTL describes default TTL for a token issued by the kontrol.
    //
    // If TokenTTL is 0, default global TokenTTL is used.
    TokenTTL time.Duration

    // TokenLeeway describes time difference to gracefully handle clock
    // skew between client and server.
    //
    // If TokenLeeway is 0, default global TokenLeeway is used.
    TokenLeeway time.Duration

    // TokenNoNBF when true does not set nbf field for generated JWT tokens.
    TokenNoNBF bool

    // RegisterURL defines the URL that is used to self register when adding
    // itself to the storage backend
    RegisterURL string
    // contains filtered or unexported fields
}

func New Uses

func New(conf *config.Config, version string) *Kontrol

New creates a new kontrol instance with the given version and config instance, and the default kontrol handlers. Publickey is used for validating tokens and privateKey is used for signing tokens.

Public and private keys are RSA pem blocks that can be generated with the following command:

openssl genrsa -out testkey.pem 2048
openssl rsa -in testkey.pem -pubout > testkey_pub.pem

If you need to provide custom handlers in place of the default ones, use the following command instead:

NewWithoutHandlers(conf, version)

func NewWithoutHandlers Uses

func NewWithoutHandlers(conf *config.Config, version string) *Kontrol

NewWithoutHandlers creates a new kontrol instance with the given version and config instance, but *without* the default handlers. If this is function is used, make sure to implement the expected kontrol functionality.

Example:

kontrol := NewWithoutHandlers(conf, version)
kontrol.Kite.HandleFunc("register", kontrol.HandleRegister)
kontrol.Kite.HandleFunc("registerMachine", kontrol.HandleMachine).DisableAuthentication()
kontrol.Kite.HandleFunc("getKites", kontrol.HandleGetKites)
kontrol.Kite.HandleFunc("getToken", kontrol.HandleGetToken)
kontrol.Kite.HandleFunc("getKey", kontrol.HandleGetKey)
kontrol.Kite.HandleHTTPFunc("/heartbeat", kontrol.HandleHeartbeat)
kontrol.Kite.HandleHTTPFunc("/register", kontrol.HandleRegisterHTTP)

func (*Kontrol) AddAuthenticator Uses

func (k *Kontrol) AddAuthenticator(keyType string, fn func(*kite.Request) error)

func (*Kontrol) AddKeyPair Uses

func (k *Kontrol) AddKeyPair(id, public, private string) error

AddKeyPair add the given key pair so it can be used to validate and sign/generate tokens. If id is empty, a unique ID will be generated. The last added key pair is also used to generate tokens for machine registrations via "handleMachine" method. This can be overiden with the kontorl.MachineKeyPicker function.

func (*Kontrol) Close Uses

func (k *Kontrol) Close()

Close stops kontrol and closes all connections

func (*Kontrol) DeleteKeyPair Uses

func (k *Kontrol) DeleteKeyPair(id, public string) error

DeleteKeyPair deletes the key with the given id or public key. (One of them can be empty)

func (*Kontrol) HandleGetKey Uses

func (k *Kontrol) HandleGetKey(r *kite.Request) (interface{}, error)

func (*Kontrol) HandleGetKites Uses

func (k *Kontrol) HandleGetKites(r *kite.Request) (interface{}, error)

func (*Kontrol) HandleGetToken Uses

func (k *Kontrol) HandleGetToken(r *kite.Request) (interface{}, error)

func (*Kontrol) HandleHeartbeat Uses

func (k *Kontrol) HandleHeartbeat(rw http.ResponseWriter, req *http.Request)

func (*Kontrol) HandleMachine Uses

func (k *Kontrol) HandleMachine(r *kite.Request) (interface{}, error)

func (*Kontrol) HandleRegister Uses

func (k *Kontrol) HandleRegister(r *kite.Request) (interface{}, error)

func (*Kontrol) HandleRegisterHTTP Uses

func (k *Kontrol) HandleRegisterHTTP(rw http.ResponseWriter, req *http.Request)

func (*Kontrol) HandleVerify Uses

func (k *Kontrol) HandleVerify(r *kite.Request) (interface{}, error)

func (*Kontrol) InitializeSelf Uses

func (k *Kontrol) InitializeSelf() error

InitializeSelf registers his host by writing a key to ~/.kite/kite.key

func (*Kontrol) KeyPair Uses

func (k *Kontrol) KeyPair() (pair *KeyPair, err error)

KeyPair looks up a key pair that was used to sign Kontrol's kite key.

The value is cached on first call of the function.

func (*Kontrol) Run Uses

func (k *Kontrol) Run()

func (*Kontrol) SetKeyPairStorage Uses

func (k *Kontrol) SetKeyPairStorage(storage KeyPairStorage)

SetKeyPairStorage sets the backend storage that kontrol is going to use to store keypairs

func (*Kontrol) SetStorage Uses

func (k *Kontrol) SetStorage(storage Storage)

SetStorage sets the backend storage that kontrol is going to use to store kites

func (*Kontrol) Verify Uses

func (k *Kontrol) Verify(pub string) error

Verify is used for token and kiteKey authenticators to verify client's kontrol keys. In order to allow for graceful key updates deleted keys are allowed.

If Config.VerifyFunc is nil during Kontrol instantiation with one of New* functions, this is the default verify method used by kontrol kite.

type MemKeyPairStorage Uses

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

func NewMemKeyPairStorage Uses

func NewMemKeyPairStorage() *MemKeyPairStorage

func NewMemKeyPairStorageTTL Uses

func NewMemKeyPairStorageTTL(ttl time.Duration) *MemKeyPairStorage

func (*MemKeyPairStorage) AddKey Uses

func (m *MemKeyPairStorage) AddKey(keyPair *KeyPair) error

func (*MemKeyPairStorage) DeleteKey Uses

func (m *MemKeyPairStorage) DeleteKey(keyPair *KeyPair) error

func (*MemKeyPairStorage) GetKeyFromID Uses

func (m *MemKeyPairStorage) GetKeyFromID(id string) (*KeyPair, error)

func (*MemKeyPairStorage) GetKeyFromPublic Uses

func (m *MemKeyPairStorage) GetKeyFromPublic(public string) (*KeyPair, error)

func (*MemKeyPairStorage) IsValid Uses

func (m *MemKeyPairStorage) IsValid(public string) error

type Node Uses

type Node struct {
    Node *etcd.Node
}

Node is a wrapper around an etcd node to provide additional functionality around kites.

func NewNode Uses

func NewNode(node *etcd.Node) *Node

New returns a new initialized node with the given etcd node.

func (*Node) Flatten Uses

func (n *Node) Flatten() []*Node

Flatten converts the recursive etcd directory structure to a flat one that contains all kontrolNodes

func (*Node) HasValue Uses

func (n *Node) HasValue() bool

HasValue returns true if the give node has a non-empty value

func (*Node) Kite Uses

func (n *Node) Kite() (*protocol.KiteWithToken, error)

Kite returns a single kite gathered from the key and the value for the current node.

func (*Node) KiteFromKey Uses

func (n *Node) KiteFromKey() (*protocol.Kite, error)

KiteFromKey returns a *protocol.Kite from an etcd key. etcd key is like: "/kites/devrim/env/mathworker/1/localhost/tardis.local/id"

func (*Node) Kites Uses

func (n *Node) Kites() (Kites, error)

Kites returns a list of kites that are gathered by collecting recursively all nodes under the current node.

func (*Node) Value Uses

func (n *Node) Value() (kontrolprotocol.RegisterValue, error)

Value returns the value associated with the current node.

type Postgres Uses

type Postgres struct {
    DB  *sql.DB
    Log kite.Logger
}

func NewPostgres Uses

func NewPostgres(conf *PostgresConfig, log kite.Logger) *Postgres

func (*Postgres) Add Uses

func (p *Postgres) Add(kiteProt *protocol.Kite, value *kontrolprotocol.RegisterValue) error

func (*Postgres) AddKey Uses

func (p *Postgres) AddKey(keyPair *KeyPair) error

func (*Postgres) CleanExpiredRows Uses

func (p *Postgres) CleanExpiredRows(expire time.Duration) (int64, error)

CleanExpiredRows deletes rows that are at least "expire" duration old. So if say an expire duration of 10 second is given, it will delete all rows that were updated 10 seconds ago

func (*Postgres) Delete Uses

func (p *Postgres) Delete(kiteProt *protocol.Kite) error

func (*Postgres) DeleteKey Uses

func (p *Postgres) DeleteKey(keyPair *KeyPair) error

func (*Postgres) Get Uses

func (p *Postgres) Get(query *protocol.KontrolQuery) (Kites, error)

func (*Postgres) GetKeyFromID Uses

func (p *Postgres) GetKeyFromID(id string) (*KeyPair, error)

func (*Postgres) GetKeyFromPublic Uses

func (p *Postgres) GetKeyFromPublic(public string) (*KeyPair, error)

func (*Postgres) IsValid Uses

func (p *Postgres) IsValid(public string) error

func (*Postgres) RunCleaner Uses

func (p *Postgres) RunCleaner(interval, expire time.Duration)

RunCleaner deletes every "interval" duration rows which are older than "expire" duration based on the "updated_at" field. For more info check CleanExpireRows which is used to delete old rows.

func (*Postgres) Update Uses

func (p *Postgres) Update(kiteProt *protocol.Kite, value *kontrolprotocol.RegisterValue) error

func (*Postgres) Upsert Uses

func (p *Postgres) Upsert(kiteProt *protocol.Kite, value *kontrolprotocol.RegisterValue) (err error)

type PostgresConfig Uses

type PostgresConfig struct {
    Host           string `default:"localhost"`
    Port           int    `default:"5432"`
    Username       string `required:"true"`
    Password       string
    DBName         string `required:"true" `
    ConnectTimeout int    `default:"20"`
}

Postgres holds Postgresql database related configuration

type RegisterValue Uses

type RegisterValue struct {
    URL string `json:"url"`
}

RegisterValue is the type of the value that is saved to etcd.

type Storage Uses

type Storage interface {
    // Get retrieves the Kites with the given query
    Get(query *protocol.KontrolQuery) (Kites, error)

    // Add inserts the given kite with the given value
    Add(kite *protocol.Kite, value *kontrolprotocol.RegisterValue) error

    // Update updates the value for the given kite
    Update(kite *protocol.Kite, value *kontrolprotocol.RegisterValue) error

    // Delete deletes the given kite from the storage
    Delete(kite *protocol.Kite) error

    // Upsert inserts or updates the value for the given kite
    Upsert(kite *protocol.Kite, value *kontrolprotocol.RegisterValue) error
}

Storage is an interface to a kite storage. A storage should be safe to concurrent access.

Directories

PathSynopsis
kontrol
onceevery
protocol

Package kontrol imports 27 packages (graph) and is imported by 14 packages. Updated 2017-06-30. Refresh now. Tools for package owners.