Lewati ke konten utama

Adapters

Di Casbin, penyimpanan kebijakan diimplementasikan sebagai adapter (alias middleware untuk Casbin). Pengguna Casbin dapat menggunakan adapter untuk memuat aturan kebijakan dari penyimpanan (alias LoadPolicy()), atau menyimpan aturan kebijakan ke dalamnya (alias SavePolicy()). Untuk menjaga agar tetap ringan, kami tidak menempatkan kode adapter di dalam pustaka utama.

Adapter yang didukung​

Daftar lengkap adaptor Casbin diberikan sebagai berikut. Kontribusi pihak ketiga pada adaptor baru sangat diterima, harap beri tahu kami dan kami akan menambahkannya dalam daftar ini:

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
catatan
  1. Jika casbin.NewEnforcer() dipanggil dengan adaptor eksplisit atau implisit, kebijakan akan dimuat secara otomatis.
  2. Anda dapat memanggil e.LoadPolicy() untuk memuat ulang aturan kebijakan dari penyimpanan.
  3. Jika adaptor tidak mendukung fitur Auto-Save, aturan kebijakan tidak dapat disimpan kembali ke penyimpanan secara otomatis saat Anda menambahkan atau menghapus kebijakan. Anda harus memanggil SavePolicy() secara manual untuk menyimpan semua aturan kebijakan.

Contoh​

Di sini kami memberikan beberapa contoh:

Adaptor File (bawaan)​

Di bawah ini menunjukkan cara menginisialisasi enforcer dari adaptor file bawaan:

import "github.com/casbin/casbin"

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

Ini sama dengan:

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

Di bawah ini menunjukkan cara menginisialisasi enforcer dari database MySQL. Ini terhubung ke DB MySQL di 127.0.0.1:3306 dengan pengguna root dan password kosong.

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)

Gunakan adapter penyimpanan Anda sendiri​

Anda dapat menggunakan adapter Anda sendiri seperti di bawah ini:

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

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

Migrasi/Konversi antara adapter yang berbeda​

Jika Anda ingin mengonversi adapter dari A ke B, Anda dapat melakukannya seperti ini:

  1. Muat kebijakan dari A ke memori
e, _ := NewEnforcer(m, A)

atau

e.SetAdapter(A)
e.LoadPolicy()

2.ubah adaptor Anda dari A ke B

e.SetAdapter(B)

3.Simpan kebijakan dari memori ke B

e.SavePolicy()

Muat/Simpan saat runtime​

Anda mungkin juga ingin memuat ulang model, memuat ulang kebijakan, atau menyimpan kebijakan setelah inisialisasi:

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

AutoSimpan​

Ada fitur yang disebut "Auto-Save" untuk adaptor. Ketika sebuah adaptor mendukung "Auto-Save", ini berarti adaptor tersebut dapat mendukung penambahan satu aturan kebijakan ke penyimpanan, atau penghapusan satu aturan kebijakan dari penyimpanan. Ini berbeda dengan "SavePolicy()", karena yang terakhir akan menghapus semua aturan kebijakan di penyimpanan dan menyimpan semua aturan kebijakan dari enforcer Casbin ke penyimpanan. Sehingga dapat mengalami masalah kinerja ketika jumlah aturan kebijakan besar.

Ketika adaptor mendukung "Auto-Save", Anda dapat mengaktifkan opsi ini melalui fungsi "Enforcer.EnableAutoSave()". Opsi ini diaktifkan secara default (jika adaptor mendukungnya).

catatan
  1. Fitur Auto-Save bersifat opsional. Sebuah adaptor dapat memilih untuk mengimplementasikannya atau tidak.
  2. Auto-Save hanya bekerja untuk enforcer Casbin ketika adaptor yang digunakan oleh enforcer tersebut mendukungnya.
  3. Lihat kolom AutoSave pada daftar adaptor di atas untuk mengetahui apakah Auto-Save didukung oleh sebuah adaptor.

Berikut adalah contoh tentang cara menggunakan 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(...)

Untuk lebih banyak contoh, silakan lihat: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

Cara menulis sebuah adaptor​

Semua adaptor harus mengimplementasikan antarmuka Adapter dengan menyediakan setidaknya dua metode wajib: LoadPolicy(model model.Model) error dan SavePolicy(model model.Model) error.

Tiga fungsi lainnya bersifat opsional. Mereka harus diimplementasikan jika adaptor mendukung fitur Auto-Save.

MetodeTipeDeskripsi
LoadPolicy()wajibMemuat semua aturan kebijakan dari penyimpanan
SavePolicy()wajibMenyimpan semua aturan kebijakan ke penyimpanan
AddPolicy()opsionalTambahkan aturan kebijakan ke penyimpanan
RemovePolicy()opsionalHapus aturan kebijakan dari penyimpanan
RemoveFilteredPolicy()opsionalHapus aturan kebijakan yang sesuai dengan filter dari penyimpanan
catatan

Jika sebuah adapter tidak mendukung Auto-Save, ia harus menyediakan implementasi kosong untuk tiga fungsi opsional tersebut. Berikut adalah contoh untuk 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")
}

Enforcer Casbin akan mengabaikan kesalahan tidak diimplementasikan saat memanggil tiga fungsi opsional ini.

Ada detail tentang cara menulis sebuah adapter.

  • Struktur Data. Adapter harus mendukung pembacaan setidaknya enam kolom.
  • Nama Database. Nama database default harus casbin.
  • Nama Tabel. Nama tabel default harus casbin_rule.
  • Kolom Ptype. Nama kolom ini seharusnya ptype bukan p_type atau Ptype.
  • Definisi tabel seharusnya (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar).
  • Indeks kunci unik seharusnya dibangun pada kolom ptype,v0,v1,v2,v3,v4,v5.
  • LoadFilteredPolicy memerlukan filter sebagai parameter. Filter seharusnya seperti ini.
{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

Siapa yang bertanggung jawab untuk membuat DB?​

Sebagai konvensi, adapter seharusnya dapat secara otomatis membuat database bernama casbin jika belum ada dan menggunakannya untuk penyimpanan kebijakan. Silakan gunakan Xorm adapter sebagai implementasi referensi: https://github.com/casbin/xorm-adapter

Adapter Konteks​

ContextAdapter menyediakan antarmuka yang sadar konteks untuk adapter Casbin.

Melalui konteks, Anda dapat mengimplementasikan fitur seperti kontrol timeout untuk Adapter API

Contoh​

gormadapter mendukung adapter dengan konteks, berikut adalah kontrol timeout yang diimplementasikan menggunakan konteks

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

Cara menulis adapter konteks​

ContextAdapter API hanya memiliki lapisan tambahan pemrosesan konteks dibandingkan Adapter API biasa,

Referensi sederhana untuk gormadapter: adapter.go