Adapt Go SDK docs to next go-aserto version

docs/decision-logs/index.mdx

@@ -6,34 +6,34 @@ description: Topaz Decision Logs - Overview
 
 # Introduction
 
-Decision logs are records of authorization decisions Topaz makes. Decisions are made by the Topaz [is](/docs/authorizer-guide/is) API, 
+Decision logs are records of authorization decisions Topaz makes. Decisions are made by the Topaz [is](/docs/authorizer-guide/is) API,
 each decision generates one log entry and each log entry has details about the decision including the context in which it was made.
 
 # Configuration
 
-Topaz decision logs are implemented as an OPA plugin and can be configured in the [Topaz configuration file](/docs/command-line-interface/topaz-cli/configuration) 
+Topaz decision logs are implemented as an OPA plugin and can be configured in the [Topaz configuration file](/docs/command-line-interface/topaz-cli/configuration)
 by adding the plugin to the OPA runtime's configuration. For example, this adds to the default configuration generated by the Topaz CLI:
 
 ```yaml
 
 opa:
   instance_id: "-"
-  graceful_shutdown_period_seconds: 2  
+  graceful_shutdown_period_seconds: 2
   local_bundles:
     paths: []
     skip_verification: true
   config:
-    services:      
+    services:
       ghcr:
         url: https://ghcr.io/
         type: "oci"
         response_header_timeout_seconds: 5
-    bundles:      
+    bundles:
       todo:
-        service: ghcr    
+        service: ghcr
         resource: "ghcr.io/aserto-policies/policy-todo:latest"
         persist: false
-        config:          
+        config:
           polling:
             min_delay_seconds: 60
             max_delay_seconds: 120
@@ -44,7 +44,9 @@ opa:
 
 // Configure the file logger the plugin will log to
 decision_logger:
-  log_file_path: "/decision_logs"
-  max_file_size_mb: 20
-  max_file_count: 3
-```
+  type: "file"
+  config:
+    log_file_path: /tmp/topaz/decisions.log
+    max_file_size_mb: 20
+    max_file_count: 3
+```

docs/software-development-kits/go/authorizer.mdx

@@ -12,16 +12,15 @@ description: Aserto SDKs - Go - Creating a client and making authorization calls
 
 ```go
 import (
-    "github.com/aserto-dev/go-aserto/authorizer/grpc"
-    "github.com/aserto-dev/go-aserto/client"
+    "github.com/aserto-dev/go-aserto"
+    "github.com/aserto-dev/go-aserto/az"
 )
 
 ...
 
-authClient, err := grpc.New(
-  context.Background(),
-	client.WithAddr("localhost:8282"),
-	client.WithInsecure(true),
+azClient, err := az.New(
+    aserto.WithAddr("localhost:8282"),
+    aserto.WithInsecure(true),
 )
 ```
 
@@ -32,34 +31,35 @@ to perform an operation.
 
 ```go
 import (
+    "context"
     "fmt"
+    "log"
 
-    "github.com/aserto-dev/go-aserto/authorizer/grpc"
-  	"github.com/aserto-dev/go-aserto/authorizer/http"
-  	"github.com/aserto-dev/go-aserto/client"
-  	authz "github.com/aserto-dev/go-authorizer/aserto/authorizer/v2"
-  	"github.com/aserto-dev/go-authorizer/aserto/authorizer/v2/api"
+    "github.com/aserto-dev/go-aserto"
+    "github.com/aserto-dev/go-aserto/az"
+    "github.com/aserto-dev/go-authorizer/aserto/authorizer/v2"
+    "github.com/aserto-dev/go-authorizer/aserto/authorizer/v2/api"
 )
 
 ...
-clientAuthz, err := grpc.New(
-	context.Background(),
-	client.WithAddr("localhost:8282"),
-	client.WithInsecure(true),
+azClient, err := az.New(
+    aserto.WithAddr("localhost:8282"),
+    aserto.WithInsecure(true),
 )
 if err != nil {
-	panic(err)
+    log.Fatalf("failed to create authorizer client: %v", err)
 }
+defer azClient.Close()
 
-result, err := clientAuthz.Is(context.Background(), &authz.IsRequest{
-	PolicyContext: &api.PolicyContext{
-		Path:      "peoplefinder.GET.api.users.__id",
-		Decisions: []string{"allowed"},
-	},
-	IdentityContext: &api.IdentityContext{
-		Identity: "[email protected]",
-		Type:     api.IdentityType_IDENTITY_TYPE_SUB,
-	},
+result, err := azClient.Is(context.Background(), &authorizer.IsRequest{
+    PolicyContext: &api.PolicyContext{
+        Path:      "peoplefinder.GET.api.users.__id",
+        Decisions: []string{"allowed"},
+    },
+    IdentityContext: &api.IdentityContext{
+        Identity: "[email protected]",
+        Type:     api.IdentityType_IDENTITY_TYPE_SUB,
+    },
 })
 
 // Check the authorizer's decision.

docs/software-development-kits/go/middleware-grpc.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_label: gRPC
+sidebar_label: gRPC Middleware
 title: Aserto SDKs - Go - gRPC Middleware
 description: Aserto SDKs - Go - Creating and using the gRPC middleware
 ---
@@ -16,16 +16,17 @@ Creating middleware requires two arguments: an [authorizer client](/docs/softwar
 
 ```go
 import (
-    middleware "github.com/aserto-dev/go-aserto/middleware/grpc"
+    "github.com/aserto-dev/go-aserto/middleware"
+    "github.com/aserto-dev/go-aserto/middleware/grpcz"
 )
 
 ...
 
 // Create gRPC middleware.
-mw := middleware.New(
-    authClient,
-    mw.Policy{
-        Decision: "allowed",             // Name of the policy rule to evaluate.
+mw := grpcz.New(
+    azClient,
+    middleware.Policy{
+        Decision: "allowed",  // policy rule to evaluate.
     },
 )
 ```

docs/software-development-kits/go/middleware-http.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_label: HTTP
+sidebar_label: HTTP Middleware
 title: Aserto SDKs - Go - HTTP Middleware
 description: Aserto SDKs - Go - Creating and using the HTTP middleware
 ---
@@ -10,22 +10,37 @@ Using authorization middleware when building HTTP servers focuses the responsibi
 
 The middleware can be configured to retrieve authorization information, such as user identity, from incoming requests.
 
+There are three flavors of the HTTP middleware:
+
+* `middleware/httpz` provides middleware for HTTP servers using the standard [net/http](https://pkg.go.dev/net/http) package.
+* `middleware/gorillaz` provides middleware for HTTP servers using [gorilla/mux](https://github.com/gorilla/mux) routers.
+* `middleware/ginz` provides middleware for HTTP servers using the [Gin web framework](https://gin-gonic.com).
+
 ## Creating Middleware
 
 Creating middleware requires two arguments: an [authorizer client](/docs/software-development-kits/go/authorizer), and a `Policy` that identifies the authorization policy to be applied, the decision rule to evaluate, and optionally a path to a policy module. If a path isn't provided, the middleware infers the policy path from the incoming request's URL. This behavior too can be further customized to fit other naming schemes.
 
 ```go
 import (
-    middleware "github.com/aserto-dev/go-aserto/middleware/http"
+    "github.com/aserto-dev/go-aserto"
+    "github.com/aserto-dev/go-aserto/az"
+    "github.com/aserto-dev/go-aserto/middleware"
+    "github.com/aserto-dev/go-aserto/middleware/httpz"
 )
 
 ...
 
+// Create an authorizer client.
+azClient, err := az.New(
+    aserto.WithAddr("localhost:8282"),
+    aserto.WithInsecure(true),
+)
+
 // Create HTTP middleware.
-mw := middleware.New(
-    authClient,
-    mw.Policy{
-      Decision: "allowed",             // Name of the policy rule to evaluate.
+mw := httpz.New(
+    azClient,
+    middleware.Policy{
+      Decision: "allowed",  // policy rule to evaluate.
     },
 )
 ```
@@ -81,15 +96,9 @@ mw.WithPolicyPathMapper(
 
 ```go
 mw.WithResourceMapper(
-    func(r *http.Request) *structpb.Struct {
-        resourceContext, err := structpb.NewStruct(map[string]string{
-            "ownerId": GetOwner(r),  // Custom function to retrieve the owner of the resource being accessed.
-        })
-        if err != nil {
-            return resourceContext
-        }
-
-        return nil
+    func(r *http.Request, resource map[string]interface{}) {
+        // Custom function to retrieve the owner of the resource being accessed.
+        resource["ownerId"] = GetOwner(r)
     },
 )
 ```
@@ -112,21 +121,45 @@ func Hello(w http.ResponseWriter, r *http.Request) {
 mux := http.NewServeMux()
 
 // Attach middleware to route handler.
-mux.Handle("/", mw.Handler(http.HandlerFunc(Hello)))
+mux.Handle("/hello", mw.HandlerFunc(Hello))
 
 ```
 
 ### gorilla/mux
 
-The popular [`gorilla/mux`](https://pkg.go.dev/github.com/gorilla/mux) package lets you set apply middleware to all routes:
+The popular [`gorilla/mux`](https://pkg.go.dev/github.com/gorilla/mux) package lets you set apply middleware to all
+handlers in a router:
 
 ```go
 func Hello(w http.ResponseWriter, r *http.Request) {
-    w.Write([]byte(`"hello"`))
+	name = mux.Vars(r)["name"]
+    w.Write([]byte(fmt.Sprintf(`"hello %s"`, name)))
 }
 
 r := mux.NewRouter()  // Create new gorilla/mux Router.
 r.Use(mw)             // Attach authorization middleware to all routes.
 
-r.HandleFunc("/", Hello) // Define route.
+r.HandleFunc("/hello/{name}", Hello) // Define route.
+```
+
+## Gin
+
+The `middleware/ginz` package is similar to the `middleware/gorillaz` module but uses `gin.Context` instead of
+`http.Request`.
+
+```go
+func Hello(c *gin.Context) {
+	name = c.Params.ByName("name")
+	c.JSON(http.StatusOK, fmt.Sprintf("hello %s", name))
+}
+```
+
+A Gin resource mapper would look like this:
+```go
+mw.WithResourceMapper(
+    func(c *gin.Context, resource map[string]interface{}) {
+        // Custom function to retrieve the owner of the resource being accessed.
+        resource["ownerId"] = GetOwner(c)
+    },
+)
 ```