Перейти к основному контенту

Adapters

В Casbin хранение политики реализовано в виде адаптера (также известного как промежуточное ПО для Casbin). Пользователь Casbin может использовать адаптер для загрузки правил политики из хранилища (также известного как LoadPolicy()), или сохранить правила политики в нем (также известное как SavePolicy()). Чтобы сохранить легкость, мы не помещаем код адаптера в основную библиотеку.

Поддерживаемые адаптеры​

Полный список адаптеров Casbin представлен ниже. Любой вклад от сторонних разработчиков в новый адаптер приветствуется, пожалуйста, сообщите нам, и мы добавим его в этот список:

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
Pgx AdapterSQL@gtoxlili✅PostgreSQL is supported by pgx, supports customizable column count
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
NATS JetStream AdapterKV storegrepplabs✅For NATS JetStream
Kubernetes AdapterCloudgrepplabs✅For Kubernetes
заметка
  1. Если вызывается casbin.NewEnforcer() с явным или неявным адаптером, политика будет загружена автоматически.
  2. Вы можете вызвать e.LoadPolicy() для перезагрузки правил политики из хранилища.
  3. Если адаптер не поддерживает функцию Auto-Save, правила политики не могут быть автоматически сохранены обратно в хранилище при добавлении или удалении политик. Вам придется вызвать SavePolicy() вручную, чтобы сохранить все правила политики.

Примеры​

Здесь мы предоставляем несколько примеров:

Адаптер файлов (встроенный)​

Ниже показано, как инициализировать принудительное выполнение из встроенного адаптера файлов:

import "github.com/casbin/casbin"

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

Это то же самое, что и:

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)

Адаптер MySQL​

Ниже показано, как инициализировать принудительное выполнение из базы данных MySQL. он подключается к MySQL DB на 127.0.0.1:3306 с root и пустым паролем.

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)

Используйте свой собственный адаптер хранения​

Вы можете использовать свой собственный адаптер, как показано ниже:

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

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

Миграция/Конвертация между различными адаптерами​

Если вы хотите конвертировать адаптер из A в B, вы можете сделать это так:

1.Загрузите политику из A в память

e, _ := NewEnforcer(m, A)

или

e.SetAdapter(A)
e.LoadPolicy()

2.конвертируйте ваш адаптер из A в B

e.SetAdapter(B)

3.Сохраните политику из памяти в B

e.SavePolicy()

Загрузка/Сохранение во время выполнения​

Вы также можете захотеть перезагрузить модель, перезагрузить политику или сохранить политику после инициализации:

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

Существует функция под названием Auto-Save для адаптеров. Когда адаптер поддерживает Auto-Save, это означает, что он может поддерживать добавление одного правила политики в хранилище или удаление одного правила политики из хранилища. Это отличается от SavePolicy(), потому что последний удалит все правила политики в хранилище и сохранит все правила политики из Casbin enforcer в хранилище. Таким образом, могут возникнуть проблемы с производительностью, когда количество правил политики велико.

Когда адаптер поддерживает Auto-Save, вы можете переключить эту опцию с помощью функции Enforcer.EnableAutoSave(). Опция включена по умолчанию (если адаптер ее поддерживает).

заметка
  1. Функция Auto-Save является необязательной. Адаптер может выбрать, реализовать ее или нет.
  2. Auto-Save работает только для Casbin enforcer, когда адаптер, который использует enforcer, поддерживает его.
  3. Смотрите столбец AutoSave в приведенном выше списке адаптеров, чтобы увидеть, поддерживает ли Auto-Save адаптер.

Вот пример использования 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(...)

Для большего количества примеров, пожалуйста, смотрите: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

Как написать адаптер​

Все адаптеры должны реализовать интерфейс Adapter, предоставив как минимум два обязательных метода: LoadPolicy(model model.Model) error и SavePolicy(model model.Model) error.

Остальные три функции являются необязательными. Они должны быть реализованы, если адаптер поддерживает функцию Auto-Save.

МетодТипОписание
LoadPolicy()обязательныйЗагрузить все правила политики из хранилища
SavePolicy()обязательныйСохранить все правила политики в хранилище
AddPolicy()необязательныйДобавить правило политики в хранилище
RemovePolicy()необязательныйУдалить правило политики из хранилища
RemoveFilteredPolicy()необязательныйУдалить правила политики, которые соответствуют фильтру, из хранилища
заметка

Если адаптер не поддерживает Auto-Save, он должен предоставить пустую реализацию для трех необязательных функций. Вот пример для 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 проигнорирует ошибку not implemented при вызове этих трех необязательных функций.

Здесь подробности о том, как написать адаптер.

  • Структура данных. Адаптер должен поддерживать чтение как минимум шести столбцов.
  • Имя базы данных. Имя базы данных по умолчанию должно быть casbin.
  • Имя таблицы. Имя таблицы по умолчанию должно быть casbin_rule.
  • Столбец Ptype. Имя этого столбца должно быть ptype, а не p_type или Ptype.
  • Определение таблицы должно быть (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar).
  • Уникальный индекс ключа должен быть построен на столбцах ptype,v0,v1,v2,v3,v4,v5.
  • LoadFilteredPolicy требует filter в качестве параметра. Фильтр должен быть таким.
{
    "p": ["", "domain1"],
    "g": ["", "", "domain1"]
}

Кто отвечает за создание БД?​

По соглашению, адаптер должен иметь возможность автоматически создавать базу данных с именем casbin, если она не существует, и использовать ее для хранения политики. Пожалуйста, используйте адаптер Xorm в качестве референсной реализации: https://github.com/casbin/xorm-adapter

Update Adapter​

The UpdateAdapter interface extends the basic Adapter interface to support updating policies directly in the storage. This is more efficient than removing and re-adding policies when you need to modify existing rules.

An adapter that implements the UpdateAdapter interface should provide the following methods:

MethodTypeDescription
UpdatePolicy()optionalUpdate a single policy rule in the storage
UpdatePolicies()optionalUpdate multiple policy rules in the storage
UpdateFilteredPolicies()optionalUpdate policy rules that match the filter in the storage

Пример​

Here's an example of using the update adapter methods:

import (
    "github.com/casbin/casbin/v2"
    "github.com/casbin/gorm-adapter/v3"
)

a, _ := gormadapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/")
e, _ := casbin.NewEnforcer("examples/rbac_model.conf", a)

// Update a single policy
// Change: p, alice, data1, read -> p, alice, data1, write
e.UpdatePolicy(
    []string{"alice", "data1", "read"},
    []string{"alice", "data1", "write"},
)

// Update multiple policies at once
e.UpdatePolicies(
    [][]string{{"alice", "data1", "write"}, {"bob", "data2", "read"}},
    [][]string{{"alice", "data1", "read"}, {"bob", "data2", "write"}},
)

// Update all policies matching a filter
e.UpdateFilteredPolicies(
    [][]string{{"alice", "data1", "write"}},
    0,
    "alice", "data1", "read",
)

How to write an update adapter​

To implement the UpdateAdapter interface, your adapter needs to implement the update methods in addition to the basic Adapter interface:

// UpdatePolicy updates a policy rule from storage.
// This is part of the UpdateAdapter interface.
func (a *Adapter) UpdatePolicy(sec string, ptype string, oldRule, newRule []string) error {
    // Implementation to update the policy in storage
    // For example, in SQL: UPDATE casbin_rule SET v0=?, v1=?, v2=? WHERE ptype=? AND v0=? AND v1=? AND v2=?
    return nil
}

// UpdatePolicies updates multiple policy rules in the storage.
// This is part of the UpdateAdapter interface.
func (a *Adapter) UpdatePolicies(sec string, ptype string, oldRules, newRules [][]string) error {
    // Implementation to update multiple policies in storage
    // This should be done in a transaction for consistency
    return nil
}

// UpdateFilteredPolicies updates policy rules that match the filter from the storage.
// This is part of the UpdateAdapter interface.
func (a *Adapter) UpdateFilteredPolicies(sec string, ptype string, newRules [][]string, fieldIndex int, fieldValues ...string) error {
    // Implementation to update filtered policies in storage
    // First find policies matching the filter, then update them
    return nil
}
заметка

If an adapter doesn't support the UpdateAdapter interface, Casbin will automatically fall back to using the combination of RemovePolicy() and AddPolicy() operations.

Адаптер контекста​

ContextAdapter предоставляет контекстно-зависимый интерфейс для адаптеров Casbin.

Через контекст вы можете реализовать такие функции, как контроль времени ожидания для API адаптера

Example​

gormadapter поддерживает адаптер с контекстом, ниже приведен контроль времени ожидания, реализованный с использованием контекста

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

Как написать адаптер контекста​

ContextAdapter API имеет только дополнительный слой обработки контекста, чем обычный Adapter API, и на основе реализации обычного Adapter API, вы можете инкапсулировать свою собственную логику обработки для контекста

A simple reference to the gormadapter: adapter.go

Transaction​

Casbin now supports Transactions. Here's an example about how to use Transaction in gormadapter:

db, _ := gorm.Open(...)
adapter, _ := gormadapter.NewTransactionalAdapterByDB(db)
e, _ := casbin.NewTransactionalEnforcer("examples/rbac_model.conf", adapter)

ctx := context.Background()

// WithTransaction executes a function within a transaction.
// If the function returns an error, the transaction is rolled back.
// Otherwise, it's committed automatically.
err := e.WithTransaction(ctx, func(tx *casbin.Transaction) error {
    tx.AddPolicy("alice", "data1", "read")
    tx.AddPolicy("alice", "data1", "write")
    return nil
})

// If you wish to manually handle the transaction
tx, _ := e.BeginTransaction(ctx)
tx.AddPolicy("alice", "data1", "write")
if err := tx.Commit(); err != nil {
    // handle if transaction failed
}

To add this capability to your adapter, you need to implement TransactionalAdapter and TransactionContext in persist/transaction.go.

Code reference to the gormadapter: adapter.go