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)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. 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

Una simple referencia al 'gormadapter': context_adapter.go