Vai al contenuto principale

Adapters

In Casbin, l'archiviazione delle policy è implementata come un adattatore (aka middleware per Casbin). Un utente di Casbin può utilizzare un adattatore per caricare regole di policy da una memoria (aka LoadPolicy()), o salvare regole di policy su di essa (aka SavePolicy()). Per mantenere leggero il peso, non inseriamo il codice dell'adattatore nella libreria principale.

Adattatori supportati​

Un elenco completo degli adattatori Casbin è fornito come segue. Sono benvenuti eventuali contributi di terze parti su un nuovo adattatore, vi preghiamo di informarci e lo inseriremo in questo elenco:

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() viene chiamato con un adattatore esplicito o implicito, la politica verrà caricata automaticamente.
  2. Puoi chiamare e.LoadPolicy() per ricaricare le regole della politica dallo storage.
  3. Se l'adattatore non supporta la funzione Auto-Save, le regole della politica non possono essere salvate automaticamente nello storage quando aggiungi o rimuovi politiche. Devi chiamare SavePolicy() manualmente per salvare tutte le regole della politica.

Esempi​

Qui forniamo diversi esempi:

Adattatore file (built-in)​

Di seguito è mostrato come inizializzare un enforcer dall'adattatore file built-in:

import "github.com/casbin/casbin"

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

Questo è lo stesso con:

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)

Adattatore MySQL​

Di seguito viene mostrato come inizializzare un enforcer da un database MySQL. Si connette a un DB MySQL su 127.0.0.1:3306 con utente root e password vuota.

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)

Utilizza il tuo adattatore di storage​

Puoi utilizzare il tuo adattatore come di seguito:

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

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

Migrazione/Conversione tra diversi adattatori​

Se desideri convertire l'adattatore da A a B, puoi procedere in questo modo:

  1. Carica i policy da A in memoria
e, _ := NewEnforcer(m, A)

o

e.SetAdapter(A)
e.LoadPolicy()

Converti il tuo adattatore da A a B

e.SetAdapter(B)

Salva la politica dalla memoria su B

e.SavePolicy()

Carica/Salva in fase di esecuzione​

Potresti anche voler ricaricare il modello, ricaricare la politica o salvare la politica dopo l'inizializzazione:

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

AutoSalvataggio​

Esiste una funzionalità chiamata "Auto-Save" per gli adattatori. Quando un adattatore supporta "Auto-Save", significa che può supportare l'aggiunta di una singola regola di politica alla memoria di archiviazione, o la rimozione di una singola regola di politica dalla memoria di archiviazione. Questo è diverso da "SavePolicy()", perché quest'ultimo eliminerà tutte le regole di politica nella memoria di archiviazione e salverà tutte le regole di politica dall'enforcer di Casbin alla memoria di archiviazione. Quindi potrebbe riscontrare problemi di prestazioni quando il numero di regole di politica è elevato.

Quando l'adattatore supporta "Auto-Save", puoi attivare questa opzione tramite la funzione "Enforcer.EnableAutoSave()". L'opzione è abilitata di default (se l'adattatore la supporta).

nota
  1. La funzionalità Auto-Salvataggio è opzionale. Un adattatore può scegliere di implementarla o meno.
  2. Auto-Salvataggio funziona solo per un enforcer di Casbin quando l'adattatore che l'enforcer utilizza lo supporta.
  3. Consulta la colonna AutoSave nella lista degli adattatori sopra per verificare se Auto-Salvataggio è supportato da un adattatore.

Ecco un esempio su come utilizzare Auto-Salvataggio:

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

Per ulteriori esempi, consulta: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

Come scrivere un adattatore​

Tutti gli adattatori dovrebbero implementare l'interfaccia Adapter fornendo almeno due metodi obbligatori: LoadPolicy(model model.Model) error e SavePolicy(model model.Model) error.

Le altre tre funzioni sono opzionali. Dovrebbero essere implementati se l'adattatore supporta la funzione Auto-Salvataggio.

MetodoTipoDescrizione
LoadPolicy()obbligatorioCarica tutte le regole di policy dallo storage
SavePolicy()obbligatorioSalva tutte le regole di policy nello storage
AddPolicy()opzionaleAggiungi una regola di politica alla memoria di archiviazione
RemovePolicy()opzionaleRimuovi una regola di politica dalla memoria di archiviazione
RemoveFilteredPolicy()opzionaleRimuovi regole di politica che corrispondono al filtro dalla memoria di archiviazione
nota

Se un adattatore non supporta Auto-Save, dovrebbe fornire un'implementazione vuota per le tre funzioni opzionali. Ecco un esempio per 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")
}

Il modulo di applicazione di Casbin ignorerà l'errore "non implementato" quando chiama queste tre funzioni opzionali.

Ci sono dettagli su come scrivere un adattatore.

  • Struttura dei dati. L'adattatore dovrebbe supportare la lettura di almeno sei colonne.
  • Nome del database. Il nome predefinito del database dovrebbe essere casbin.
  • Nome della tabella. Il nome predefinito della tabella dovrebbe essere casbin_rule.
  • Colonna Ptype. Il nome di questa colonna dovrebbe essere ptype invece di p_type o Ptype.
  • La definizione della tabella dovrebbe essere (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar).
  • L'indice di chiave unica dovrebbe essere costruito sulle colonne ptype,v0,v1,v2,v3,v4,v5.
  • LoadFilteredPolicy richiede un filter come parametro. Il filtro dovrebbe essere qualcosa del genere.
{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

Chi è responsabile della creazione del DB?​

Per convenzione, l'adattatore dovrebbe essere in grado di creare automaticamente un database chiamato casbin se non esiste e utilizzarlo per la memorizzazione dei criteri. Si prega di utilizzare l'adattatore Xorm come implementazione di riferimento: https://github.com/casbin/xorm-adapter

Adattatore Context​

ContextAdapter fornisce un'interfaccia consapevole del contesto per gli adattatori di Casbin.

Attraverso il contesto, puoi implementare funzionalità come il controllo del timeout per l'API dell'Adapter

Esempio​

gormadapter supporta l'adapter con contesto, il seguente è un controllo del timeout implementato utilizzando il contesto

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

Come scrivere un adapter di contesto​

L'API ContextAdapter ha solo un ulteriore livello di elaborazione del contesto rispetto all'API Adapter ordinaria,

Un semplice riferimento a gormadapter: adapter.go