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)FileCasbin❌For .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)File@faceless-saint❌For .CSV (Comma-Separated Values) files with policy subset loading support
SQL AdapterSQL@Blank-Xu✅MySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by database/sql
Xorm AdapterORMCasbin✅MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
GORM AdapterORMCasbin✅MySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
GORM Adapter ExORMCasbin✅MySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
Ent AdapterORMCasbin✅MySQL, MariaDB, PostgreSQL, SQLite, Gremlin-based graph databases are supported by ent ORM
Beego ORM AdapterORMCasbin✅MySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
SQLX AdapterORM@memwey✅MySQL, PostgreSQL, SQLite, Oracle are supported by SQLX
Sqlx AdapterORM@Blank-Xu✅MySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by sqlx
GF ORM AdapterORM@vance-liu✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame ORM AdapterORM@kotlin2018✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
gf-adapterORM@zcyc✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Gdb AdapterORM@jxo-me✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame V2 AdapterORM@hailaz✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Bun AdapterORM@JunNishimura✅MySQL, SQLite, PostgreSQL, SQL Server are supported by Bun ORM
Filtered PostgreSQL AdapterSQLCasbin✅For PostgreSQL
Filtered pgx AdapterSQL@pckhoi✅PostgreSQL is supported by pgx
PostgreSQL AdapterSQL@cychiuae✅For PostgreSQL
RQLite AdapterSQLEDOMO Systems✅For RQLite
MongoDB AdapterNoSQLCasbin✅For MongoDB based on MongoDB Go Driver
RethinkDB AdapterNoSQL@adityapandey9✅For RethinkDB
Cassandra AdapterNoSQLCasbin❌For Apache Cassandra DB
DynamoDB AdapterNoSQLHOOQ❌For Amazon DynamoDB
DynacasbinNoSQLNewbMiao✅For Amazon DynamoDB
ArangoDB AdapterNoSQL@adamwasila✅For ArangoDB
Amazon S3 AdapterCloudSoluto❌For Minio and Amazon S3
Go CDK AdapterCloud@bartventer✅Adapter based on Go Cloud Dev Kit that supports: Amazon DynamoDB, Azure CosmosDB, GCP Firestore, MongoDB, In-Memory
Azure Cosmos DB AdapterCloud@spacycoder✅For Microsoft Azure Cosmos DB
GCP Firestore AdapterCloud@reedom❌For Google Cloud Platform Firestore
GCP Cloud Storage AdapterCloudqurami❌For Google Cloud Platform Cloud Storage
GCP Cloud Spanner AdapterCloud@flowerinthenight✅For Google Cloud Platform Cloud Spanner
Consul AdapterKV store@ankitm123❌For HashiCorp Consul
Redis Adapter (Redigo)KV storeCasbin✅For Redis
Redis Adapter (go-redis)KV store@mlsen✅For Redis
Etcd AdapterKV store@sebastianliu❌For etcd
BoltDB AdapterKV store@speza✅For Bolt
Bolt AdapterKV store@wirepair❌For Bolt
BadgerDB AdapterKV store@inits✅For BadgerDB
Protobuf AdapterStreamCasbin❌For Google Protocol Buffers
JSON AdapterStringCasbin❌For JSON
String AdapterString@qiangmzsx❌For String
HTTP File AdapterHTTP@h4ckedneko❌For http.FileSystem
FileSystem AdapterFile@naucon❌For 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

Uma simples referência ao 'gormadapter': context_adapter.go