Ir al contenido principal

Adapters

En Casbin, el almacenamiento de políticas se implementa como un adaptador (también conocido como middleware para Casbin). Un usuario de Casbin puede usar un adaptador para cargar reglas de políticas desde un almacenamiento (también conocido como LoadPolicy()), o guardar reglas de políticas en él (también conocido como SavePolicy()). Para mantenerse ligero, no incluimos el código del adaptador en la biblioteca principal.

Adaptadores compatibles

Se proporciona una lista completa de adaptadores de Casbin a continuación. Cualquier contribución de terceros sobre un nuevo adaptador es bienvenida, por favor infórmenos y lo incluiremos en esta 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. Si se llama a casbin.NewEnforcer() con un adaptador explícito o implícito, la política se cargará automáticamente.
  2. Puede llamar a e.LoadPolicy() para recargar las reglas de políticas desde el almacenamiento.
  3. Si el adaptador no admite la función de Auto-Guardado, las reglas de políticas no se pueden guardar automáticamente de vuelta en el almacenamiento cuando se agregan o eliminan políticas. Tiene que llamar a SavePolicy() manualmente para guardar todas las reglas de políticas.

Ejemplos

Aquí proporcionamos varios ejemplos:

Adaptador de archivo (integrado)

A continuación se muestra cómo inicializar un enforcer desde el adaptador de archivo integrado:

import "github.com/casbin/casbin"

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

Esto es lo mismo 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

A continuación se muestra cómo inicializar un enforcer desde una base de datos MySQL. se conecta a una base de datos MySQL en 127.0.0.1:3306 con root y contraseña en blanco.

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)

Utilice su propio adaptador de almacenamiento

Puede usar su propio adaptador como se muestra a continuación:

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

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

Migrar/Convertir entre diferentes adaptadores

Si desea convertir el adaptador de A a B, puede hacerlo de la siguiente manera:

1.Cargar la política de A a la memoria

e, _ := NewEnforcer(m, A)

o

e.SetAdapter(A)
e.LoadPolicy()

2.convertir su adaptador de A a B

e.SetAdapter(B)

3.Guardar la política de la memoria a B

e.SavePolicy()

Cargar/Guardar en tiempo de ejecución

También puede querer recargar el modelo, recargar la política o guardar la política después de la inicialización:

// 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()

AutoGuardado

Hay una función llamada Auto-Guardado para adaptadores. Cuando un adaptador admite Auto-Guardado, significa que puede admitir agregar una regla de política individual al almacenamiento, o eliminar una regla de política individual del almacenamiento. Esto es diferente de SavePolicy(), porque este último eliminará todas las reglas de políticas en el almacenamiento y guardará todas las reglas de políticas del enforcer de Casbin en el almacenamiento. Por lo tanto, puede sufrir problemas de rendimiento cuando el número de reglas de políticas es grande.

Cuando el adaptador admite Auto-Guardado, puede cambiar esta opción a través de la función Enforcer.EnableAutoSave(). La opción está habilitada por defecto (si el adaptador la admite).

nota
  1. La función de Auto-Guardado es opcional. Un adaptador puede elegir implementarlo o no.
  2. Auto-Guardado solo funciona para un enforcer de Casbin cuando el adaptador que utiliza el enforcer lo admite.
  3. Vea la columna AutoSave en la lista de adaptadores anterior para ver si un adaptador admite Auto-Guardado.

Aquí hay un ejemplo de cómo usar Auto-Guardado:

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 más ejemplos, por favor vea: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

Cómo escribir un adaptador

Todos los adaptadores deben implementar la interfaz Adapter proporcionando al menos dos métodos obligatorios:LoadPolicy(model model.Model) error y SavePolicy(model model.Model) error.

Las otras tres funciones son opcionales. Deben implementarse si el adaptador admite la función de Auto-Guardado.

MétodoTipoDescripción
LoadPolicy()obligatorioCargar todas las reglas de política desde el almacenamiento
SavePolicy()obligatorioGuardar todas las reglas de política en el almacenamiento
AddPolicy()opcionalAñadir una regla de política al almacenamiento
RemovePolicy()opcionalEliminar una regla de política del almacenamiento
RemoveFilteredPolicy()opcionalEliminar las reglas de política que coincidan con el filtro del almacenamiento
nota

Si un adaptador no soporta 'Auto-Save', debería proporcionar una implementación vacía para las tres funciones opcionales. Aquí hay un ejemplo 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")
}

Casbin enforcer ignorará el error de 'not implemented' cuando llame a estas tres funciones opcionales.

Hay detalles sobre cómo escribir un adaptador.

  • Estructura de Datos. El adaptador debería soportar la lectura de al menos seis columnas.
  • Nombre de la Base de Datos. El nombre predeterminado de la base de datos debería ser 'casbin'.
  • Nombre de la Tabla. El nombre predeterminado de la tabla debería ser 'casbin_rule'.
  • Columna Ptype. El nombre de esta columna debería ser 'ptype' en lugar de 'p_type' o 'Ptype'.
  • La definición de la tabla debería ser '(id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar)'.
  • El índice de clave única debería construirse en las columnas 'ptype,v0,v1,v2,v3,v4,v5'.
  • 'LoadFilteredPolicy' requiere un 'filter' como parámetro. El filtro debería ser algo así.
{
"p":[ [ "alice" ], [ "bob" ] ],
"g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
"g2":[ [ "alice" ] ]
}

¿Quién es responsable de crear la BD?

Como convención, el adaptador debería poder crear automáticamente una base de datos llamada 'casbin' si no existe y usarla para el almacenamiento de políticas. Por favor, use el adaptador Xorm como una implementación de referencia: https://github.com/casbin/xorm-adapter

Context Adapter

ContextAdapter proporciona una interfaz consciente del contexto para los adaptadores de Casbin.

A través del contexto, puedes implementar características como el control de tiempo de espera para la API del Adaptador

Ejemplo

gormadapter soporta adaptador con contexto, lo siguiente es un control de tiempo 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)
}

Cómo escribir un adaptador de contexto

La API de 'ContextAdapter' solo tiene una capa extra de procesamiento de contexto que la API de 'Adapter' ordinaria, y sobre la base de implementar la API de Adapter ordinaria, puedes encapsular tu propia lógica de procesamiento para el contexto

A simple reference to the gormadapter: adapter.go