Pular para o conteúdo principal

Adapters

No Casbin, o armazenamento de políticas é implementado como um adaptador (também conhecido como middleware para o Casbin). Um usuário do Casbin pode usar um adaptador para carregar regras de políticas de um armazenamento (conhecido como LoadPolicy()), ou salvar regras de políticas nele (conhecido como SavePolicy()). Para manter-se leve, não colocamos o código do adaptador na biblioteca principal.

Adaptadores suportados

Uma lista completa dos adaptadores Casbin é fornecida abaixo. Qualquer contribuição de terceiros em um novo adaptador é bem-vinda, por favor nos informe e nós o colocaremos nesta lista:

AdapterTypeAuthorAutoSaveDescription
File Adapter (built-in)FileCasbinFor .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)File@faceless-saintFor .CSV (Comma-Separated Values) files with policy subset loading support
SQL AdapterSQL@Blank-XuMySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by database/sql
Xorm AdapterORMCasbinMySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
GORM AdapterORMCasbinMySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
GORM Adapter ExORMCasbinMySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
Ent AdapterORMCasbinMySQL, MariaDB, PostgreSQL, SQLite, Gremlin-based graph databases are supported by ent ORM
Beego ORM AdapterORMCasbinMySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
SQLX AdapterORM@memweyMySQL, PostgreSQL, SQLite, Oracle are supported by SQLX
Sqlx AdapterORM@Blank-XuMySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by sqlx
GF ORM AdapterORM@vance-liuMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame ORM AdapterORM@kotlin2018MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
gf-adapterORM@zcycMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Gdb AdapterORM@jxo-meMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame V2 AdapterORM@hailazMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Bun AdapterORM@JunNishimuraMySQL, SQLite, PostgreSQL, SQL Server are supported by Bun ORM
Filtered PostgreSQL AdapterSQLCasbinFor PostgreSQL
Filtered pgx AdapterSQL@pckhoiPostgreSQL is supported by pgx
PostgreSQL AdapterSQL@cychiuaeFor PostgreSQL
RQLite AdapterSQLEDOMO SystemsFor RQLite
MongoDB AdapterNoSQLCasbinFor MongoDB based on MongoDB Go Driver
RethinkDB AdapterNoSQL@adityapandey9For RethinkDB
Cassandra AdapterNoSQLCasbinFor Apache Cassandra DB
DynamoDB AdapterNoSQLHOOQFor Amazon DynamoDB
DynacasbinNoSQLNewbMiaoFor Amazon DynamoDB
ArangoDB AdapterNoSQL@adamwasilaFor ArangoDB
Amazon S3 AdapterCloudSolutoFor Minio and Amazon S3
Go CDK AdapterCloud@bartventerAdapter based on Go Cloud Dev Kit that supports: Amazon DynamoDB, Azure CosmosDB, GCP Firestore, MongoDB, In-Memory
Azure Cosmos DB AdapterCloud@spacycoderFor Microsoft Azure Cosmos DB
GCP Firestore AdapterCloud@reedomFor Google Cloud Platform Firestore
GCP Cloud Storage AdapterCloudquramiFor Google Cloud Platform Cloud Storage
GCP Cloud Spanner AdapterCloud@flowerinthenightFor Google Cloud Platform Cloud Spanner
Consul AdapterKV store@ankitm123For HashiCorp Consul
Redis Adapter (Redigo)KV storeCasbinFor Redis
Redis Adapter (go-redis)KV store@mlsenFor Redis
Etcd AdapterKV store@sebastianliuFor etcd
BoltDB AdapterKV store@spezaFor Bolt
Bolt AdapterKV store@wirepairFor Bolt
BadgerDB AdapterKV store@initsFor BadgerDB
Protobuf AdapterStreamCasbinFor Google Protocol Buffers
JSON AdapterStringCasbinFor JSON
String AdapterString@qiangmzsxFor String
HTTP File AdapterHTTP@h4ckednekoFor http.FileSystem
FileSystem AdapterFile@nauconFor fs.FS and embed.FS
nota
  1. Se casbin.NewEnforcer() for chamado com um adaptador explícito ou implícito, a política será carregada automaticamente.
  2. Você pode chamar e.LoadPolicy() para recarregar as regras de políticas do armazenamento.
  3. Se o adaptador não suportar o recurso de Auto-Save, as regras de políticas não poderão ser salvas automaticamente de volta ao armazenamento quando você adicionar ou remover políticas. Você tem que chamar SavePolicy() manualmente para salvar todas as regras de políticas.

Exemplos

Aqui fornecemos vários exemplos:

Adaptador de arquivo (integrado)

Abaixo mostra como inicializar um executor a partir do adaptador de arquivo integrado:

import "github.com/casbin/casbin"

e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")

Isto é o mesmo que:

import (
"github.com/casbin/casbin"
"github.com/casbin/casbin/file-adapter"
)

a := fileadapter.NewAdapter("examples/basic_policy.csv")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

Adaptador MySQL

Abaixo mostra como inicializar um executor a partir de um banco de dados MySQL. ele se conecta a um banco de dados MySQL em 127.0.0.1:3306 com root e senha em branco.

import (
"github.com/casbin/casbin"
"github.com/casbin/mysql-adapter"
)

a := mysqladapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

Use seu próprio adaptador de armazenamento

Você pode usar seu próprio adaptador como abaixo:

import (
"github.com/casbin/casbin"
"github.com/your-username/your-repo"
)

a := yourpackage.NewAdapter(params)
e := casbin.NewEnforcer("examples/basic_model.conf", a)

Migrar/Converter entre diferentes adaptadores

Se você quiser converter o adaptador de A para B, você pode fazer assim:

1.Carregar política de A para a memória

e, _ := NewEnforcer(m, A)

ou

e.SetAdapter(A)
e.LoadPolicy()

2.converter seu adaptador de A para B

e.SetAdapter(B)

3.Salvar política da memória para B

e.SavePolicy()

Carregar/Salvar em tempo de execução

Você também pode querer recarregar o modelo, recarregar a política ou salvar a política após a inicialização:

// Reload the model from the model CONF file.
e.LoadModel()

// Reload the policy from file/database.
e.LoadPolicy()

// Save the current policy (usually after changed with Casbin API) back to file/database.
e.SavePolicy()

AutoSave

Há um recurso chamado Auto-Save para adaptadores. Quando um adaptador suporta Auto-Save, significa que ele pode suportar a adição de uma única regra de política ao armazenamento, ou a remoção de uma única regra de política do armazenamento. Isso é diferente de SavePolicy(), porque este último excluirá todas as regras de políticas no armazenamento e salvará todas as regras de políticas do executor Casbin para o armazenamento. Portanto, pode sofrer problemas de desempenho quando o número de regras de políticas é grande.

Quando o adaptador suporta Auto-Save, você pode alternar esta opção através da função Enforcer.EnableAutoSave(). A opção está habilitada por padrão (se o adaptador suportar).

nota
  1. O recurso Auto-Save é opcional. Um adaptador pode escolher implementá-lo ou não.
  2. Auto-Save só funciona para um executor Casbin quando o adaptador que o executor usa suporta.
  3. Veja a coluna AutoSave na lista de adaptadores acima para ver se Auto-Save é suportado por um adaptador.

Aqui está um exemplo de como usar Auto-Save:

import (
"github.com/casbin/casbin"
"github.com/casbin/xorm-adapter"
_ "github.com/go-sql-driver/mysql"
)

// By default, the AutoSave option is enabled for an enforcer.
a := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

// Disable the AutoSave option.
e.EnableAutoSave(false)

// Because AutoSave is disabled, the policy change only affects the policy in Casbin enforcer,
// it doesn't affect the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

// Enable the AutoSave option.
e.EnableAutoSave(true)

// Because AutoSave is enabled, the policy change not only affects the policy in Casbin enforcer,
// but also affects the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

Para mais exemplos, por favor veja: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

Como escrever um adaptador

Todos os adaptadores devem implementar a interface Adapter fornecendo pelo menos dois métodos obrigatórios:LoadPolicy(model model.Model) error e SavePolicy(model model.Model) error.

As outras três funções são opcionais. Elas devem ser implementadas se o adaptador suportar o recurso de Auto-Save.

MétodoTipoDescrição
LoadPolicy()obrigatórioCarregar todas as regras de política do armazenamento
SavePolicy()obrigatórioSalvar todas as regras de política no armazenamento
AddPolicy()opcionalAdicionar uma regra de política ao armazenamento
RemovePolicy()opcionalRemover uma regra de política do armazenamento
RemoveFilteredPolicy()opcionalRemover regras de política que correspondam ao filtro do armazenamento
nota

Se um adaptador não suportar 'Auto-Save', ele deve fornecer uma implementação vazia para as três funções opcionais. Aqui está um exemplo para Golang:

// AddPolicy adds a policy rule to the storage.
func (a *Adapter) AddPolicy(sec string, ptype string, rule []string) error {
return errors.New("not implemented")
}

// RemovePolicy removes a policy rule from the storage.
func (a *Adapter) RemovePolicy(sec string, ptype string, rule []string) error {
return errors.New("not implemented")
}

// RemoveFilteredPolicy removes policy rules that match the filter from the storage.
func (a *Adapter) RemoveFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValues ...string) error {
return errors.New("not implemented")
}

O executor do Casbin irá ignorar o erro 'not implemented' ao chamar essas três funções opcionais.

Há detalhes sobre como escrever um adaptador.

  • Estrutura de Dados. O adaptador deve suportar a leitura de pelo menos seis colunas.
  • Nome do Banco de Dados. O nome padrão do banco de dados deve ser 'casbin'.
  • Nome da Tabela. O nome padrão da tabela deve ser 'casbin_rule'.
  • Coluna Ptype. O nome desta coluna deve ser 'ptype' em vez de 'p_type' ou 'Ptype'.
  • A definição da tabela deve ser '(id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar)'.
  • O índice de chave única deve ser construído nas colunas 'ptype,v0,v1,v2,v3,v4,v5'.
  • 'LoadFilteredPolicy' requer um 'filter' como parâmetro. O filtro deve ser algo assim.
{
"p":[ [ "alice" ], [ "bob" ] ],
"g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
"g2":[ [ "alice" ] ]
}

Quem é responsável por criar o DB?

Como convenção, o adaptador deve ser capaz de criar automaticamente um banco de dados chamado 'casbin' se ele não existir e usá-lo para armazenamento de políticas. Por favor, use o adaptador Xorm como uma implementação de referência: https://github.com/casbin/xorm-adapter

Context Adapter

ContextAdapter fornece uma interface consciente de contexto para os adaptadores do Casbin.

Através do contexto, você pode implementar recursos como controle de tempo de espera para a API do Adaptador

Exemplo

gormadapter suporta adaptador com contexto, a seguir está um controle de tempo de espera implementado usando contexto

ca, _ := NewContextAdapter("mysql", "root:@tcp(127.0.0.1:3306)/", "casbin")
// Limited time 300s
ctx, cancel := context.WithTimeout(context.Background(), 300*time.Microsecond)
defer cancel()

err := ca.AddPolicyCtx(ctx, "p", "p", []string{"alice", "data1", "read"})
if err != nil {
panic(err)
}

Como escrever um adaptador de contexto

A API 'ContextAdapter' só tem uma camada extra de processamento de contexto além da API 'Adapter' comum, e com base na implementação da API Adapter comum, você pode encapsular sua própria lógica de processamento para o contexto

A simple reference to the gormadapter: adapter.go