update documentation and actions (#9)

.devcontainer/postCreate.sh

@@ -10,6 +10,6 @@ opam remote remove --all default
 opam repository add default --all-switches --set-default https://opam.ocaml.org
 
 opam pin add -yn guardian .
-opam depext -y guardian
+opam depext --with-test --with-doc -y guardian
 
 make deps

.github/actions/notify-failure.yml

@@ -0,0 +1,21 @@
+name: notify-failure
+description: Send a notification to Econ MS Teams channel
+
+inputs:
+  webhook:
+    required: true
+    description: The webhook URL to be called
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        # Restore directory permissions to avoid conflicts
+        sudo chown -R 1001:123 .
+
+        # Prepare and send notification
+        cat << EOF > message.json
+        {"@type":"MessageCard","@context":"https://schema.org/extensions","summary":"Pipeline failed!","themeColor":"ff0000","title":"$GITHUB_REPOSITORY pipeline failed 💢!","sections":[{"facts":[{"name":"Repository:","value":"$GITHUB_REPOSITORY"},{"name":"Branch:","value":"$GITHUB_REF_NAME"},{"name":"Commit:","value":"$GITHUB_SHA"}]}],"potentialAction":[{"@type":"OpenUri","name":"View on GitHub","targets":[{"os":"default","uri":"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"}]}]}
+        EOF
+        curl -X POST ${{ inputs.webhook }} --header 'Content-Type: application/json' -d @message.json

.github/workflows/ci.yml

@@ -3,12 +3,14 @@ on:
   pull_request:
   push:
     branches: main
+    tags: ["**"]
+  workflow_dispatch:
 
 jobs:
   build:
     name: Build and test
 
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
 
     env:
       MYSQL_DATABASE: test
@@ -26,7 +28,6 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest]
         ocaml-compiler: [4.12.x]
 
     steps:
@@ -47,21 +48,28 @@ jobs:
       - name: Pin current guardian
         run: |
           opam pin add -yn guardian .
-          OPAMSOLVERTIMEOUT=180 opam depext -y guardian
+          OPAMSOLVERTIMEOUT=180 opam depext --with-test --with-doc -y guardian
 
       - name: Install dependencies
-        run: opam install --deps-only --with-test -y .
+        run: opam install --deps-only --with-test --with-doc -y .
 
       - name: Build
-        run: opam exec -- dune build --root .
+        run: |
+          make build
+          make doc
 
       - name: Check formatting
         run: make format
 
       - name: Run tests
         env:
           DATABASE_URL: mariadb://root:${{ env.MYSQL_ROOT_PASSWORD }}@127.0.0.1:3306/${{ env.MYSQL_DATABASE }}
-        run: opam config exec -- make test
+        run: make test
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: documentation
+          path: _build/default/_doc/_html
 
       - uses: actions/upload-artifact@v3
         if: failure()
@@ -71,8 +79,30 @@ jobs:
 
       - name: Notify about failure
         if: failure()
-        run: |
-           cat << EOF > message.json
-           {"@type":"MessageCard","@context":"https://schema.org/extensions","summary":"Pipeline failed!","themeColor":"ff0000","title":"$GITHUB_REPOSITORY pipeline failed 💢!","sections":[{"facts":[{"name":"Repository:","value":"$GITHUB_REPOSITORY"},{"name":"Branch:","value":"$GITHUB_REF_NAME"},{"name":"Commit:","value":"$GITHUB_SHA"}]}],"potentialAction":[{"@type":"OpenUri","name":"View on GitHub","targets":[{"os":"default","uri":"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"}]}]}
-           EOF
-           curl -X POST ${{ secrets.ECON_TEAMS_WEBHOOK }} --header 'Content-Type: application/json' -d @message.json
+        uses: ./.github/actions/notify-failure
+        with:
+          webhook: ${{ secrets.ECON_TEAMS_WEBHOOK }}
+
+  deploy-doc:
+    name: Deploy documentation
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.ref_name == 'main'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Download all workflow run artifacts
+        uses: actions/download-artifact@v3
+
+      - name: Deploy odoc to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ github.token }}
+          publish_dir: documentation
+
+      - name: Notify about failure
+        if: failure()
+        uses: ./.github/actions/notify-failure
+        with:
+          webhook: ${{ secrets.ECON_TEAMS_WEBHOOK }}

Makefile

@@ -40,3 +40,7 @@ utop: ## Run a REPL and link with the project's libraries
 .PHONY: format
 format: ## Format the codebase with ocamlformat
 	opam exec -- dune build --root . --auto-promote @fmt
+
+.PHONY: doc
+doc: ## Build the documentation
+	opam exec -- dune build --root . @doc

README.md

@@ -22,7 +22,7 @@ Generic framework for roles and permissions to be used in our projects
     ;;
   end
   in
-  let module MariaDb = Guardian_backend.MariaDb.Make (Role) (Make (MariaConfig))
+  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 *)
@@ -55,13 +55,13 @@ Example usage:
 
   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.authorizable) = User.to_authorizable ?ctx thomas in
-    let* (_: [> `User ] MariaDb.authorizable) = User.to_authorizable ?ctx mike in
-    let* (_: [> `User ] MariaDb.authorizable_target) = UserTarget.to_authorizable ?ctx thomas in
-    let* (_: [> `User ] MariaDb.authorizable_target) = UserTarget.to_authorizable ?ctx mike in
-    let* (_: [> `Article ] MariaDb.authorizable_target) = Article.to_authorizable ?ctx thomas_article in
-    let* (_: [> `Article ] MariaDb.authorizable_target) = Article.to_authorizable ?ctx mike_article in
-    let* () = MariaDb.Actor.save_rule ?ctx example_role in
+    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  *)

dune

@@ -3,4 +3,7 @@
   (flags
    (:standard -w +A-42-44-45-48-66 -warn-error +A-3))))
 
+(documentation
+ (package guardian))
+
 (data_only_dirs .devcontainer .git node_modules)

dune-project

@@ -61,6 +61,8 @@
    (>= 0.9.8))
   (yojson
    (>= 2.0.2))
+  ;; Documentation
+  (odoc :with-doc)
   ;; Test/Dev dependencies
   (alcotest-lwt :with-test)))
 

guardian.opam

@@ -29,8 +29,8 @@ depends: [
   "uri" {>= "4.2.0"}
   "uuidm" {>= "0.9.8"}
   "yojson" {>= "2.0.2"}
-  "alcotest-lwt" {with-test}
   "odoc" {with-doc}
+  "alcotest-lwt" {with-test}
 ]
 build: [
   ["dune" "subst"] {dev}

index.mld

@@ -0,0 +1,76 @@
+{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
+}