casbinraft

README

casbin-raft

casbin-raft is the Dispatcher for Casbin. Provide a way to synchronize incremental changes of policy based on etcd/raft. With this library, Casbin can ensure the consistency of multiple Casbin instances in distributed situations.

Installation

    go get -u github.com/casbin/casbin-raft

Only casbin v3 supports the use of dispatcher, so you need to use the code of the beta branch

    go get -u github.com/casbin/casbin/v3@beta

Simple Example

package main

import (
	"github.com/casbin/casbin/v3"
	casbinraft "github.com/casbin/casbin-raft"
)

func main() {
    // Must guarantee that the initial state of all instances is the same, 
    e, _ := casbin.NewSyncedEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")

    // Need to provide the ID and URL of all nodes in the cluster. 
    peers := make(map[uint64]string)
    peers[1] = "127.0.0.1:8001"
    peers[2] = "127.0.0.1:8002"
    d := casbinraft.NewDispathcer(1, peers)

    e.SetDispathcer(d)
    e.EnableautoNotifyDispatcher(true)

    go d.Start()

    // Then you can continue to use the enforcer normally, and when the policy changes, dispathcer will automatically synchronize all clusters
    e.AddPolicy("alice", "data2", "read")
}

Dynamic Membership

casbin-raft supports dynamically adding/removing nodes while runtime, for the new node, you need set the param join to true.

    // peers should also contain all nodes info, although this is not needed by raft, it will be used for tranport between nodes
    peers := make(map[uint64]string)
    peers[1] = "http://127.0.0.1:8001"
    peers[2] = "http://127.0.0.1:8002"
    peers[3] = "http://127.0.0.1:8003"
    peers[4] = "http://127.0.0.1:8004"
    e, err := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")
    if err != nil {
        t.Fatal(err)
    }

    d := casbinraft.NewDispatcher(4, peers, true)
    _ = e.SetDispatcher(d)
    e.EnableautoNotifyDispatcher(true)
    
    go d.Start()

for the existing cluster, you can call AddMember on any node

    d.AddMember(4, "http://127.0.0.1:8004")

If you need to remove the node, you can call RemoveMember on any node

    d.RemoveMember(3)

Getting Help

• Casbin

License

This project is under Apache 2.0 License. See the LICENSE file for the full license text.

Documentation

Index

• type Cluster
  • func NewCluster(peers map[uint64]string) *Cluster
  • func (c *Cluster) AddMember(id uint64, url string)
  • func (c *Cluster) ApplyConfigChange(cc raftpb.ConfChange)
  • func (c *Cluster) GetURL(id uint64) string
  • func (c *Cluster) HasMember(id uint64) bool
  • func (c *Cluster) RemoveMember(id uint64)
• type Command
• type Dispatcher
  • func NewDispatcher(id uint64, peers map[uint64]string, join ...bool) *Dispatcher
  • func (d *Dispatcher) AddMember(id uint64, addr string) error
  • func (d *Dispatcher) AddPolicies(sec string, ptype string, rules [][]string) error
  • func (d *Dispatcher) ClearPolicy() error
  • func (d *Dispatcher) EnableTLSTransport(keyFile string, certFile string, caFile string)
  • func (d *Dispatcher) IsIDRemoved(id uint64) bool
  • func (d *Dispatcher) Process(ctx context.Context, m raftpb.Message) error
  • func (d *Dispatcher) RemoveFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValues ...string) error
  • func (d *Dispatcher) RemoveMember(id uint64) error
  • func (d *Dispatcher) RemovePolicies(sec string, ptype string, rules [][]string) error
  • func (d *Dispatcher) ReportSnapshot(id uint64, status raft.SnapshotStatus)
  • func (d *Dispatcher) ReportUnreachable(id uint64)
  • func (d *Dispatcher) Restart() error
  • func (d *Dispatcher) SetElectionTick(num int)
  • func (d *Dispatcher) SetEnforcer(enforcer interface{}) error
  • func (d *Dispatcher) SetHeartbeatTick(num int)
  • func (d *Dispatcher) SetSnapDirName(name string)
  • func (d *Dispatcher) SetSnapshotCount(count uint64)
  • func (d *Dispatcher) SetWalDirName(name string)
  • func (d *Dispatcher) Start() error
  • func (d *Dispatcher) Stop()
• type Engine
  • func (e *Engine) Apply(c Command)

Types

type Cluster

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

Cluster manage the node id and url

func NewCluster

func NewCluster(peers map[uint64]string) *Cluster

NewCluster create a Cluster frome map

func (*Cluster) AddMember

func (c *Cluster) AddMember(id uint64, url string)

AddMember add a new member to Cluster

func (*Cluster) ApplyConfigChange

func (c *Cluster) ApplyConfigChange(cc raftpb.ConfChange)

ApplyConfigChange apply the Ready ConfChange Message

func (*Cluster) GetURL

func (c *Cluster) GetURL(id uint64) string

GetURL find the url

func (*Cluster) HasMember

func (c *Cluster) HasMember(id uint64) bool

HasMember check if the member in the Cluster

func (*Cluster) RemoveMember

func (c *Cluster) RemoveMember(id uint64)

RemoveMember remove a existed member from Cluster

type Command

type Command struct {
	Op          int        `json:"op"`
	Sec         string     `json:"sec"`
	Ptype       string     `json:"ptype"`
	Rules       [][]string `json:"rules"`
	FiledIndex  int        `json:"filed_index"`
	FiledValues []string   `json:"filed_values"`
}

Command represents an instruction to change the state of the engine

type Dispatcher

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

Dispatcher is a casbin enforcer backed by raft

func NewDispatcher

func NewDispatcher(id uint64, peers map[uint64]string, join ...bool) *Dispatcher

NewDispatcher return a instance of dispatcher, the peers is a collection of id and url of all nodes in the cluster

func (*Dispatcher) AddMember

func (d *Dispatcher) AddMember(id uint64, addr string) error

AddMember add a new node to Cluster.

func (*Dispatcher) AddPolicies

func (d *Dispatcher) AddPolicies(sec string, ptype string, rules [][]string) error

AddPolicies add policies to casbin enforcer This function will be call by casbin. Please call casbin ManagementAPI for use.

func (*Dispatcher) ClearPolicy

func (d *Dispatcher) ClearPolicy() error

ClearPolicy clears all policy. This function will be call by casbin. Please call casbin ManagementAPI for use.

func (*Dispatcher) EnableTLSTransport

func (d *Dispatcher) EnableTLSTransport(keyFile string, certFile string, caFile string)

EnableTLSTransport make transport protected by TLS. This function must be called before call node.Start().

func (*Dispatcher) IsIDRemoved

func (d *Dispatcher) IsIDRemoved(id uint64) bool

func (*Dispatcher) Process

func (d *Dispatcher) Process(ctx context.Context, m raftpb.Message) error

These functions are to satisfy the raft interface in transport.

func (*Dispatcher) RemoveFilteredPolicy

func (d *Dispatcher) RemoveFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValues ...string) error

RemoveFilteredPolicy removes a role inheritance rule from the current named policy, field filters can be specified. This function will be call by casbin. Please call casbin ManagementAPI for use.

func (*Dispatcher) RemoveMember

func (d *Dispatcher) RemoveMember(id uint64) error

RemoveMember remove a exist Node from Cluster.

func (*Dispatcher) RemovePolicies

func (d *Dispatcher) RemovePolicies(sec string, ptype string, rules [][]string) error

RemovePolicies remove policies from casbin enforcer This function will be call by casbin. Please call casbin ManagementAPI for use.

func (*Dispatcher) ReportSnapshot

func (d *Dispatcher) ReportSnapshot(id uint64, status raft.SnapshotStatus)

func (*Dispatcher) ReportUnreachable

func (d *Dispatcher) ReportUnreachable(id uint64)

func (*Dispatcher) Restart

func (d *Dispatcher) Restart() error

Restart init raft from wal and snapshot that already existing, then begin serving requests

func (*Dispatcher) SetElectionTick

func (d *Dispatcher) SetElectionTick(num int)

SetElectionTick set the number of Node.Tick invocations that must pass between elections. ElectionTick must be greater than HeartbeatTick. We suggest ElectionTick = 10 * HeartbeatTick to avoid unnecessary leader switching. This function must be called before call node.Start().

func (*Dispatcher) SetEnforcer

func (d *Dispatcher) SetEnforcer(enforcer interface{}) error

SetEnforcer set up the instance that need to be maintained. The parameter should be SyncedEnforced

func (*Dispatcher) SetHeartbeatTick

func (d *Dispatcher) SetHeartbeatTick(num int)

SetHeartbeatTick set the number of Node.Tick invocations that must pass between heartbeats. That is, a leader sends heartbeat messages to maintain its leadership every HeartbeatTick ticks. This function must be called before call node.Start().

func (*Dispatcher) SetSnapDirName

func (d *Dispatcher) SetSnapDirName(name string)

SetSnapDirName set the directory name that store sanpshot file. This function must be called before call node.Start().

func (*Dispatcher) SetSnapshotCount

func (d *Dispatcher) SetSnapshotCount(count uint64)

SetSnapshotCount set the number of logs that trigger a snapshot save. This function must be called before call node.Start().

func (*Dispatcher) SetWalDirName

func (d *Dispatcher) SetWalDirName(name string)

SetWalDirName set the directory name that store write ahead log file. This function must be called before call node.Start().

func (*Dispatcher) Start

func (d *Dispatcher) Start() error

Start performs any initialization of the Server necessary for it to begin serving requests.

func (*Dispatcher) Stop

func (d *Dispatcher) Stop()

Stop close the raft node and http server

type Engine

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

Engine is a wapper for casbin enforcer

func (*Engine) Apply

func (e *Engine) Apply(c Command)

Apply applies a Raft log entry to the casbin engine.