Merge pull request #36 from qor5/polish-permission-doc

polish permission doc

docs/appendix/all-demo-examples.html

@@ -507,12 +507,6 @@
 <a href='https://github.com/qor5/docs/tree/main/docsrc/examples/e00_basics/notification-center.go' target='_blank'>Source</a>
 </li>
 
-<li>
-<a href='/samples/presets-permissions/customers' target='_blank'>Permissions Demo</a>
- | 
-<a href='https://github.com/qor5/docs/tree/main/docsrc/examples/e21_presents/permissions.go' target='_blank'>Source</a>
-</li>
-
 <li>
 <a href='/samples/shortcut-sample' target='_blank'>Shortcut</a>
  | 

docsrc/content/basics/permissions.go

@@ -1,22 +1,97 @@
 package basics
 
 import (
-	"github.com/qor5/docs/docsrc/examples/e21_presents"
+	"fmt"
+	"strings"
+
 	"github.com/qor5/docs/docsrc/generated"
-	"github.com/qor5/docs/docsrc/utils"
 	. "github.com/theplant/docgo"
 	"github.com/theplant/docgo/ch"
 )
 
 var Permissions = Doc(
-	Markdown(`## To list all the permissions in your project`),
-	ch.Code(`perm.Verbose = true`).Language("go"),
-	Markdown(`Then reboot your app, you can see all the permissions in the console`),
+	Markdown(`
+QOR5 permission is based on https://github.com/ory/ladon.  
+A piece of policy looks like this:  
+**Who** is **able** to do **what** on **something** (with given some **context**)  
+    `),
+	ch.Code(generated.PermissionSyntax).Language("go"),
+	Markdown(fmt.Sprintf(`
+## Who - Subject
+Typically in admin system, they are roles like %s, %s.  
+Use %s to fetch current subjects:
+    `, "`Admin`", "`Super Admin`", "`SubjectsFunc`")),
+	ch.Code(generated.PermissionSubjectsFunc).Language("go"),
+	Markdown(fmt.Sprintf(`
+## Able - Effect
+- %s
+- %s
+
+## What - Action
+presets has a list of actions:
+- %s
+- %s
+- %s
+- %s
+- %s
 
+And you can define other specific actions if needed.
+## Something - Resource
+An arbitrary unique resource name.  
+For example %s represents the user record with id 1.  
+Use %s as wildcard.
+## Context - Condition
+Optional.  
+The current context that containing condition information about the resource.  
+Use %s to set the context:
+    `,
+		strings.TrimRight(generated.PermissionAllowed, ","),
+		strings.TrimRight(generated.PermissionDenied, ","),
+		strings.TrimRight(generated.PermissionPermList, ","),
+		strings.TrimRight(generated.PermissionPermGet, ","),
+		strings.TrimRight(generated.PermissionPermCreate, ","),
+		strings.TrimRight(generated.PermissionPermUpdate, ","),
+		strings.TrimRight(generated.PermissionPermDelete, ","),
+		"`:presets:users:1:`",
+		"`*`",
+		"`ContextFunc`",
+	)),
+	ch.Code(generated.PermissionContextFunc).Language("go"),
+	Markdown(fmt.Sprintf(`
+Policy uses %s to set conditions:  
+    `, "`Given`")),
+	ch.Code(generated.PermissionGivenFunc).Language("go"),
+	Markdown(fmt.Sprintf(`
+## Custom Action
+Let's say there is a button on User detailing page used to ban the user. And only %s users have permission to execute this action.  
+First, create a verifier
+    `, "`super_admin`")),
+	ch.Code(generated.PermissionNewVerifier).Language("go"),
+	Markdown(fmt.Sprintf(`
+Then inject this verifier to relevant logic, such as
+- whether to show the ban button.
+- validate permission before execute the ban action.
+    `)),
+	ch.Code(generated.PermissionVerifierCheck).Language("go"),
+	Markdown(`
+Finally, add policy
+    `),
+	ch.Code(generated.PermissionAddCustomPolicy).Language("go"),
+	Markdown(`
+## Example
+    `),
+	ch.Code(generated.PermissionExample).Language("go"),
+	Markdown(`
+## Debug
+    `),
+	ch.Code(generated.PermissionVerbose).Language("go"),
 	Markdown(`
-## Permissions sample:
-`),
-	ch.Code(generated.PresetsPermissionsSample).Language("go"),
-	utils.Demo("Permissions Demo", e21_presents.PresetsPermissionsPath+"/customers", "e21_presents/permissions.go"),
+prints permission logs which is very helpful for debugging the permission policies:
+    `),
+	ch.Code(`
+have permission: true, req: &ladon.Request{Resource:":presets:menu:articles:", Action:"presets:list", Subject:"viewer", Context:ladon.Context(nil)}
+have permission: true, req: &ladon.Request{Resource:":presets:articles:articles:1:", Action:"presets:update", Subject:"viewer", Context:ladon.Context(nil)}
+have permission: false, req: &ladon.Request{Resource:":presets:articles:articles:2:", Action:"presets:update", Subject:"viewer", Context:ladon.Context(nil)}
+    `).Language("plain"),
 ).Title("Permissions").
 	Slug("presets-guide/permissions")

docsrc/examples/example_basics/permission.go

@@ -0,0 +1,130 @@
+package example_basics
+
+import (
+	"net/http"
+
+	"github.com/ory/ladon"
+	"github.com/qor5/admin/presets"
+	"github.com/qor5/x/perm"
+)
+
+func permissionPieces() {
+	_ = []interface{}{
+		// @snippet_begin(PermissionAllowed)
+		perm.Allowed,
+		// @snippet_end
+		// @snippet_begin(PermissionDenied)
+		perm.Denied,
+		// @snippet_end
+		// @snippet_begin(PermissionPermList)
+		presets.PermList,
+		// @snippet_end
+		// @snippet_begin(PermissionPermGet)
+		presets.PermGet,
+		// @snippet_end
+		// @snippet_begin(PermissionPermCreate)
+		presets.PermCreate,
+		// @snippet_end
+		// @snippet_begin(PermissionPermUpdate)
+		presets.PermUpdate,
+		// @snippet_end
+		// @snippet_begin(PermissionPermDelete)
+		presets.PermDelete,
+		// @snippet_end
+	}
+
+	var Who, Able, What, Something string
+	var Context perm.Conditions
+	// @snippet_begin(PermissionSyntax)
+	perm.PolicyFor(Who).WhoAre(Able).ToDo(What).On(Something).Given(Context)
+	// @snippet_end
+
+	var permBuilder perm.Builder
+	var subjects_like_user_roles []string
+	// @snippet_begin(PermissionSubjectsFunc)
+	permBuilder.SubjectsFunc(func(r *http.Request) []string {
+		return subjects_like_user_roles
+	})
+	// @snippet_end
+
+	type resource1 struct {
+		Owner string
+	}
+	// @snippet_begin(PermissionContextFunc)
+	permBuilder.ContextFunc(func(r *http.Request, objs []interface{}) perm.Context {
+		c := make(perm.Context)
+		for _, obj := range objs {
+			switch v := obj.(type) {
+			case resource1:
+				c["owner"] = v.Owner
+				// ...other resource cases
+			}
+		}
+		return c
+	})
+	// @snippet_end
+
+	// @snippet_begin(PermissionGivenFunc)
+	perm.PolicyFor(Who).WhoAre(Able).ToDo(What).On("*:resource1:*").Given(perm.Conditions{
+		"owner": &ladon.EqualsSubjectCondition{},
+	})
+	// @snippet_end
+
+	var presetsBuilder *presets.Builder
+	type User struct {
+		ID    string
+		Roles []string
+	}
+	var getCurrentUser func(r *http.Request) *User
+	type Article struct {
+		OwnerID string
+	}
+	// @snippet_begin(PermissionExample)
+	presetsBuilder.Permission(
+		perm.New().Policies(
+			// admin can do anything
+			perm.PolicyFor("admin").WhoAre(perm.Allowed).ToDo(perm.Anything).On(perm.Anything),
+			// viewer can view anything except users
+			perm.PolicyFor("viewer").WhoAre(perm.Allowed).ToDo(presets.PermRead...).On(perm.Anything),
+			perm.PolicyFor("viewer").WhoAre(perm.Denied).ToDo(perm.Anything).On("*:users:*"),
+			// editor can edit their own articles
+			perm.PolicyFor("editor").WhoAre(perm.Allowed).ToDo(perm.Anything).On("*:articles:*").Given(perm.Conditions{
+				"owner_id": &ladon.EqualsSubjectCondition{},
+			}),
+		).SubjectsFunc(func(r *http.Request) (ss []string) {
+			user := getCurrentUser(r)
+			ss = append(ss, user.ID)
+			ss = append(ss, user.Roles...)
+			return ss
+		}).ContextFunc(func(r *http.Request, objs []interface{}) perm.Context {
+			c := make(perm.Context)
+			for _, obj := range objs {
+				switch v := obj.(type) {
+				case *Article:
+					c["owner_id"] = v.OwnerID
+				}
+			}
+			return c
+		}),
+	)
+	// @snippet_end
+
+	// @snippet_begin(PermissionVerbose)
+	perm.Verbose = true
+	// @snippet_end
+
+	var r *http.Request
+	var user interface{}
+	// @snippet_begin(PermissionNewVerifier)
+	verifier := perm.NewVerifier("users", presetsBuilder.GetPermission())
+	// @snippet_end
+	// @snippet_begin(PermissionVerifierCheck)
+	if verifier.Do("ban").ObjectOn(user).WithReq(r).IsAllowed() == nil {
+		// ui: show the ban button
+		// action: can execute the ban action
+	}
+	// @snippet_end
+	// @snippet_begin(PermissionAddCustomPolicy)
+	perm.PolicyFor("super_admin").WhoAre(perm.Allowed).ToDo("ban").On(":users:*")
+	// @snippet_end
+}