goncierge

Documentation

Overview

Package goncierge holds the capabilities each role carries, as granted by named sources.

Index

• Variables
• func Declare(r *Registry, rules Rules, source string, roles []Role) error
• type Registry
  • func New() *Registry
  • func (r *Registry) Can(role, capability string) bool
  • func (r *Registry) Capabilities() []string
  • func (r *Registry) CapabilitiesOf(role string) []string
  • func (r *Registry) Grant(source, role string, capabilities ...string) error
  • func (r *Registry) Grantable(caller string) []string
  • func (r *Registry) HoldersOf(capability string) []string
  • func (r *Registry) Known(role string) bool
  • func (r *Registry) Outranks(caller, target string) bool
  • func (r *Registry) Replace(source string, roles []Role) error
  • func (r *Registry) Revoke(source, role string, capabilities ...string)
  • func (r *Registry) Roles() []string
  • func (r *Registry) Withdraw(source string)
• type Role
• type Rules

Examples

• Declare
• Registry
• Registry.Grant

Variables

var ErrEmptySource = errors.New("goncierge: empty source")

ErrEmptySource reports that a grant names no source.

var ErrInvalidName = errors.New("goncierge: invalid name")

ErrInvalidName reports that a role or capability name breaks the name rule.

var ErrOutsidePrefix = errors.New("goncierge: new capability outside the source's prefix")

ErrOutsidePrefix reports a new capability whose name does not start with its source and a dot.

var ErrUnknownAdmin = errors.New("goncierge: unknown admin role")

ErrUnknownAdmin reports an administrator role that no other source created.

Functions

func Declare

func Declare(r *Registry, rules Rules, source string, roles []Role) error

Declare replaces the source's grants with its roles under the rules, refusing a new capability outside its prefix.

Example

package main

import (
	"fmt"

	"github.com/gopherium/framework/goncierge"
)

func main() {
	registry := goncierge.New()
	if err := registry.Grant("core", "admin", "manage_users"); err != nil {
		return
	}
	rules := goncierge.Rules{Admin: "admin"}

	fmt.Println(goncierge.Declare(registry, rules, "events", []goncierge.Role{
		{Name: "organizer", Capabilities: []string{"events.manage"}},
	}))
	fmt.Println(registry.CapabilitiesOf("admin"))
	fmt.Println(goncierge.Declare(registry, rules, "tickets", []goncierge.Role{
		{Name: "seller", Capabilities: []string{"sell_tickets"}},
	}))
}

Output:
<nil>
[events.manage manage_users]
goncierge: new capability outside the source's prefix "tickets.": "sell_tickets"

Types

type Registry

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

Registry holds the capabilities each role carries, as granted by named sources.

Example

package main

import (
	"fmt"

	"github.com/gopherium/framework/goncierge"
)

func main() {
	registry := goncierge.New()
	if err := registry.Grant("core", "admin", "users.manage", "events.manage"); err != nil {
		return
	}
	if err := registry.Grant("core", "member"); err != nil {
		return
	}
	if err := registry.Grant("events", "organizer", "events.manage"); err != nil {
		return
	}

	fmt.Println(registry.Can("organizer", "events.manage"))
	fmt.Println(registry.Grantable("organizer"))
	fmt.Println(registry.HoldersOf("users.manage"))

	registry.Withdraw("events")
	fmt.Println(registry.Roles())
}

Output:
true
[organizer member]
[admin]
[admin member]

func New

func New() *Registry

New returns an empty registry.

func (*Registry) Can

func (r *Registry) Can(role, capability string) bool

Can reports whether the role carries the capability, an empty role never carrying one.

func (*Registry) Capabilities

func (r *Registry) Capabilities() []string

Capabilities returns every capability any source granted, sorted.

func (*Registry) CapabilitiesOf

func (r *Registry) CapabilitiesOf(role string) []string

CapabilitiesOf returns the capabilities the role carries, sorted, from every source.

func (*Registry) Grant

func (r *Registry) Grant(source, role string, capabilities ...string) error

Grant records that the source gives the role the capabilities, creating the role when it is new.

Example

package main

import (
	"fmt"

	"github.com/gopherium/framework/goncierge"
)

func main() {
	err := goncierge.New().Grant("core", "Shop manager", "orders.manage")

	fmt.Println(err)
}

Output:
goncierge: invalid name for a role: "Shop manager"

func (*Registry) Grantable

func (r *Registry) Grantable(caller string) []string

Grantable returns the roles the caller outranks, the one carrying most capabilities first.

func (*Registry) HoldersOf

func (r *Registry) HoldersOf(capability string) []string

HoldersOf returns the roles that carry the capability, sorted.

func (*Registry) Known

func (r *Registry) Known(role string) bool

Known reports whether any source created the role.

func (*Registry) Outranks

func (r *Registry) Outranks(caller, target string) bool

Outranks reports whether the caller carries every capability the target carries.

func (*Registry) Replace

func (r *Registry) Replace(source string, roles []Role) error

Replace swaps every grant the source made for the roles given, in one step.

func (*Registry) Revoke

func (r *Registry) Revoke(source, role string, capabilities ...string)

Revoke removes the capabilities from the source's grant to the role, or the whole grant when none is named.

func (*Registry) Roles

func (r *Registry) Roles() []string

Roles returns every role any source created, sorted.

func (*Registry) Withdraw

func (r *Registry) Withdraw(source string)

Withdraw removes every grant the source made, and every role only the source created.

type Role

type Role struct {
	Name         string
	Capabilities []string
}

Role is one role a source grants, with the capabilities the source gives it.

type Rules

type Rules struct {
	// Admin names the role that also receives every capability a source declares, empty for none.
	Admin string
}

Rules are the declaration rules a program sets once for every source that declares roles.