index.mld

{0 Guardian}

Generic framework for roles and permissions to be used in our projects

{1 Limitations and Notes}

- {b Supported Database}: Implementation with MariaDb
- {b Context (`ctx`)}: Allows to have multiple database pools {!section:mysection} (See {{: test} next section})

{1:mysection Setup with MariaDB backend (MultiPools)}

{[
  let open Guardian_backend.Pools in
  let module MariaConfig = struct
    include DefaultConfig

    let database =
      MultiPools
        [ "pool-one", "mariadb://root@database:3306/dev"
        ; "pool-two", "mariadb://root@database:3306/test"
        ]
    ;;
  end
  in
  let module MariaDb = Guardian_backend.MariaDb.Make (Roles) (Make (MariaConfig))
  let%lwt () = Lwt_list.iter (fun pool -> MariaDb.migrate ~ctx:["pool", pool] ()) ["pool-one"; "pool-two"]
  (** NOTE: To integrate migrations into your applications migration state see
      e.g. function 'MariaDB.find_migrations *)
]}

## Usage

The [test] directory shows an example implementation of how guardian can be used.

- {b [role.ml]} : Definition of actors and targets
- {b [role.mli]} : Signature of the defined actors and targets
- {b [guard.ml]} : Create the guardian service
- {b [article.ml]} : Definition of the article target
- {b [hacker.ml]} : Definition of the hacker actor
- {b [user.ml]} : Definition of the user actor and target
- {b [main.ml]} : implementation of all test cases

Example usage:

{[
  module Guard = Guardian.Make (Role.Actor) (Role.Target)

  let thomas = "Thomas", Guard.Uuid.Actor.create ()
  let mike = "Mike", Guard.Uuid.Actor.create ()

  let thomas_article = Article.make "Foo" "Bar" thomas
  let mike_article = Article.make "Hello" "World" mike

  let example_rule = `Actor (snd mike), `Update, `Target thomas_article.uuid

  let initialize_authorizables_and_rules ?ctx =
    (* Note: As a user can be an actor and a target, both need to be initialized *)
    let* (_: [> `User ] MariaDb.actor) = User.to_authorizable ?ctx thomas in
    let* (_: [> `User ] MariaDb.actor) = User.to_authorizable ?ctx mike in
    let* (_: [> `User ] MariaDb.target) = UserTarget.to_authorizable ?ctx thomas in
    let* (_: [> `User ] MariaDb.target) = UserTarget.to_authorizable ?ctx mike in
    let* (_: [> `Article ] MariaDb.target) = Article.to_authorizable ?ctx thomas_article in
    let* (_: [> `Article ] MariaDb.target) = Article.to_authorizable ?ctx mike_article in
    let* () = MariaDb.Rule.save ?ctx example_role in
    Lwt.return_unit

  (* let mike Update the title of thomas article -> returns a (Article.t, string) Lwt_result.t  *)
  let update_title = Article.update_title ?ctx mike thomas_article "Updated Title"
]}

{1:api API}

{!modules:
Guardian
Guardian_backend
}