Passer au contenu principal

Adapters

Dans Casbin, le stockage des politiques est implémenté comme un adaptateur (aussi appelé middleware pour Casbin). Un utilisateur de Casbin peut utiliser un adaptateur pour charger des règles de politique à partir d'un stockage (aka LoadPolicy()), ou pour y sauvegarder des règles de politique (aka SavePolicy()). Pour rester léger, nous ne mettons pas le code de l'adaptateur dans la bibliothèque principale.

Adaptateurs pris en charge​

Une liste complète des adaptateurs Casbin est fournie ci-dessous. Toute contribution de tiers sur un nouvel adaptateur est la bienvenue, veuillez nous en informer et nous l'ajouterons à cette liste :

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
note
  1. Si casbin.NewEnforcer() est appelé avec un adaptateur explicite ou implicite, la politique sera chargée automatiquement.
  2. Vous pouvez appeler e.LoadPolicy() pour recharger les règles de politique à partir du stockage.
  3. Si l'adaptateur ne prend pas en charge la fonctionnalité Auto-Save, les règles de politique ne peuvent pas être automatiquement sauvegardées dans le stockage lorsque vous ajoutez ou supprimez des politiques. Vous devez appeler SavePolicy() manuellement pour sauvegarder toutes les règles de politique.

Exemples​

Nous fournissons ici plusieurs exemples :

Adaptateur de fichier (intégré)​

Voici comment initialiser un exécuteur à partir de l'adaptateur de fichier intégré :

import "github.com/casbin/casbin"

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

C'est la même chose avec :

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)

Adaptateur MySQL​

Voici comment initialiser un exécuteur à partir d'une base de données MySQL. il se connecte à une base de données MySQL sur 127.0.0.1:3306 avec root et sans mot de passe.

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)

Utilisez votre propre adaptateur de stockage​

Vous pouvez utiliser votre propre adaptateur comme ci-dessous :

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

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

Migrer/Convertir entre différents adaptateurs​

Si vous voulez convertir l'adaptateur de A à B, vous pouvez faire comme ceci :

1.Charger la politique de A en mémoire

e, _ := NewEnforcer(m, A)

ou

e.SetAdapter(A)
e.LoadPolicy()

2.convertir votre adaptateur de A à B

e.SetAdapter(B)

3.Sauvegarder la politique de la mémoire à B

e.SavePolicy()

Charger/Sauvegarder en temps réel​

Vous pouvez également vouloir recharger le modèle, recharger la politique ou sauvegarder la politique après l'initialisation :

// 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​

There is a feature called Auto-Save for adapters. When an adapter supports Auto-Save, it means it can support adding a single policy rule to the storage, or removing a single policy rule from the storage. This is unlike SavePolicy(), because the latter will delete all policy rules in the storage and save all policy rules from Casbin enforcer to the storage. So it may suffer performance issue when the number of policy rules is large.

When the adapter supports Auto-Save, you can switch this option via Enforcer.EnableAutoSave() function. The option is enabled by default (if the adapter supports it).

note
  1. The Auto-Save feature is optional. An adapter can choose to implement it or not.
  2. Auto-Save only works for a Casbin enforcer when the adapter the enforcer uses supports it.
  3. See the AutoSave column in the above adapter list to see if Auto-Save is supported by an adapter.

Here's an example about how to use 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(...)

For more examples, please see: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

How to write an adapter​

All adapters should implement the Adapter interface by providing at least two mandatory methods:LoadPolicy(model model.Model) error and SavePolicy(model model.Model) error.

The other three functions are optional. They should be implemented if the adapter supports the Auto-Save feature.

MethodTypeDescription
LoadPolicy()mandatoryLoad all policy rules from the storage
SavePolicy()mandatorySave all policy rules to the storage
AddPolicy()optionalAdd a policy rule to the storage
RemovePolicy()optionalSupprimer une règle de politique du stockage
RemoveFilteredPolicy()optionnelSupprimer les règles de politique qui correspondent au filtre du stockage
note

Si un adaptateur ne prend pas en charge Auto-Save, il doit fournir une implémentation vide pour les trois fonctions optionnelles. Voici un exemple pour 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")
}

L'exécuteur Casbin ignorera l'erreur non implémentée lors de l'appel de ces trois fonctions optionnelles.

Il y a des détails sur comment écrire un adaptateur.

  • Structure de données. L'adaptateur devrait supporter la lecture d'au moins six colonnes.
  • Nom de la base de données. Le nom de base de données par défaut devrait être casbin.
  • Nom de la table. Le nom de la table par défaut devrait être casbin_rule.
  • Colonne Ptype. Le nom de cette colonne devrait être ptype au lieu de p_type ou Ptype.
  • La définition de la table devrait être (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar).
  • L'index de clé unique devrait être construit sur les colonnes ptype,v0,v1,v2,v3,v4,v5.
  • LoadFilteredPolicy nécessite un filter comme paramètre. Le filtre devrait ressembler à ceci.
{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

Qui est responsable de la création de la base de données ?​

Par convention, l'adaptateur devrait être capable de créer automatiquement une base de données nommée casbin si elle n'existe pas et de l'utiliser pour le stockage des politiques. Veuillez utiliser l'adaptateur Xorm comme une implémentation de référence : https://github.com/casbin/xorm-adapter

Adaptateur de contexte​

ContextAdapter fournit une interface consciente du contexte pour les adaptateurs Casbin.

Grâce au contexte, vous pouvez implémenter des fonctionnalités telles que le contrôle du délai d'attente pour l'API de l'adaptateur

Exemple​

gormadapter prend en charge l'adaptateur avec contexte, voici un contrôle de délai d'attente implémenté à l'aide du contexte

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

Comment écrire un adaptateur de contexte​

ContextAdapter API n'a qu'une couche supplémentaire de traitement de contexte que l'API Adapter ordinaire, et sur la base de la mise en œuvre de l'API Adapter ordinaire, vous pouvez encapsuler votre propre logique de traitement pour le contexte

A simple reference to the gormadapter: context_adapter.go