Merge pull request #201 from aserto-dev/go-aserto

Adapt Go SDK docs to next version of go-aserto

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

@@ -6,26 +6,31 @@ description: Aserto SDKs - Go - Creating a client and making authorization calls
 
 # Authorizer Client
 
-[`AuthorizerClient`](https://github.com/aserto-dev/go-grpc-authz/blob/main/aserto/authorizer/authorizer/v1/authorizer_grpc.pb.go#L20)
+[`AuthorizerClient`](https://github.com/aserto-dev/go-authorizer/blob/main/aserto/authorizer/v2/authorizer_grpc.pb.go#L34)
 is the low-level interface that talks to the Aserto [authorization API](/docs/authorizer-guide/authz).
-It can be used on its own to make authorization calls or, more commonly, it can be used to create authorization
+It can be used on its own to make authorization requests or, more commonly, it can be used to create authorization
 middleware.
 
 ## Create a Client
 
 ```go
 import (
-    authz "github.com/aserto-dev/aserto-go/authorizer/grpc"
-    "github.com/aserto-dev/aserto-go/client"
+    "log"
+
+    "github.com/aserto-dev/go-aserto"
+    "github.com/aserto-dev/go-aserto/az"
 )
 
 ...
 
-authClient, err := authz.New(
-        ctx,
-        client.WithAPIKeyAuth("<Aserto authorizer API key"),
-        client.WithTenantID("<Aserto tenant ID>"),
+azClient, err := az.New(
+    aserto.WithAPIKeyAuth("<Aserto authorizer API key"),
+    aserto.WithTenantID("<Aserto tenant ID>"),
 )
+if err != nil {
+    log.Fatal("Failed to create authorizer client:", err)
+}
+defer azClient.Close()
 ```
 
 ## Make Authorization Calls
@@ -35,24 +40,30 @@ to perform an operation.
 
 ```go
 import (
+    "context"
     "fmt"
+    "log"
 
-    "github.com/aserto-dev/go-grpc-authz/aserto/authorizer/authorizer/v1"
-    "github.com/aserto-dev/go-grpc/aserto/api/v1"
+    "github.com/aserto-dev/go-authorizer/aserto/authorizer/v2"
+    "github.com/aserto-dev/go-authorizer/aserto/authorizer/v2/api"
 )
 
 ...
 
-result, err := authClient.Is(ctx, &authorizer.IsRequest{
+ctx := context.Background()
+
+result, err := azClient.Is(ctx, &authorizer.IsRequest{
     IdentityContext: &api.IdentityContext{          // The user performing the operation.
         Type: api.IdentityType_IDENTITY_TYPE_SUB,
         Identity: "username",
     },
     PolicyContext: &api.PolicyContext{
-        Id:        "<Aserto Policy ID>",
         Path:      "peoplefinder.GET.users",  // Policy module to evaluate.
         Decisions: []string{"allowed"},       // Policy rules to evaluate.
     },
+    PolicyInstance: &api.PolicyInstance {
+        Name: "<policy name>",
+    },
 })
 if err != nil {
     log.Fatal("Failed to call authorizer:", err)

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

@@ -1,18 +1,18 @@
 ---
 sidebar_label: Install
 title: Aserto SDKs - Go - Installation
-description: Aserto SDKs - Go - Installing the aserto-go SDK
+description: Aserto SDKs - Go - Installing the go-aserto SDK
 ---
 
-# aserto-go
+# go-aserto
 
-The [`aserto-go`](https://github.com/aserto-dev/aserto-go) package implements Go clients and middleware for the Aserto
+The [`go-aserto`](https://github.com/aserto-dev/go-aserto) package implements Go clients and middleware for the Aserto
 services.
 
 ## Install
 
 In your Go environment run:
 
 ```sh
-go get -u github.com/aserto-dev/aserto-go
+go get -u github.com/aserto-dev/go-aserto
 ```

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

@@ -12,6 +12,12 @@ to a single component instead of fragmenting the logic across many service metho
 The middleware can be configured to retrieve authorization information, such as user identity, from incoming messages
 and streams.
 
+## Installation
+
+```shell
+go get github.com/aserto-dev/go-aserto/middleware/grpz
+```
+
 ## Creating Middleware
 
 Creating middleware requires two arguments: an [authorizer client](/docs/software-development-kits/go/authorizer),
@@ -21,17 +27,18 @@ request's URL. This behavior too can be further customized to fit other naming s
 
 ```go
 import (
-    middleware "github.com/aserto-dev/aserto-go/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{
-        ID:       "<Aserto policy ID>",
-        Decision: "allowed",             // Name of the policy rule to evaluate.
+mw := grpcz.New(
+    azClient,
+    middleware.Policy{
+        Name:     "<policy name>",
+        Decision: "allowed",        // Name of the policy rule to evaluate.
     },
 )
 ```

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

@@ -11,6 +11,32 @@ to a single component instead of fragmenting the logic across all routes.
 
 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).
+
+## Installation
+
+**net/http**:
+
+```shell
+go get github.com/aserto-dev/go-aserto/middleware/httpz
+```
+
+**gorilla/mux**:
+
+```shell
+go get github.com/aserto-dev/go-aserto/middleware/gorillaz
+```
+
+**Gin**:
+
+```shell
+go get github.com/aserto-dev/go-aserto/middleware/ginz
+```
+
 ## Creating Middleware
 
 Creating middleware requires two arguments: an [authorizer client](/docs/software-development-kits/go/authorizer),
@@ -20,17 +46,18 @@ request's URL. This behavior too can be further customized to fit other naming s
 
 ```go
 import (
-    middleware "github.com/aserto-dev/aserto-go/middleware/http"
+     "github.com/aserto-dev/aserto-go/middleware"
+     "github.com/aserto-dev/aserto-go/middleware/httpz"
 )
 
 ...
 
 // Create HTTP middleware.
-mw := middleware.New(
-    authClient,
-    mw.Policy{
-        ID:       "<Aserto policy ID>",
-        Decision: "allowed",             // Name of the policy rule to evaluate.
+mw := httpz.New(
+    azClient,
+    middleware.Policy{
+        Name:       "< policy name>",
+        Decision: "allowed",           // Name of the policy rule to evaluate.
     },
 )
 ```
@@ -89,15 +116,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)
     },
 )
 ```
@@ -120,22 +141,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:
+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)
+    },
+)
 ```

src/sdks.js

@@ -24,7 +24,7 @@ export default [
     title: 'Go',
     icon: 'go.svg',
     link: 'https://go.dev/',
-    github: 'https://github.com/aserto-dev/aserto-go',
+    github: 'https://github.com/aserto-dev/go-aserto',
     docs: '/docs/software-development-kits/go/install',
   },
   {
@@ -38,8 +38,7 @@ export default [
     title: 'Flask',
     icon: 'flask.svg',
     link: 'https://flask.palletsprojects.com',
-    github:
-      'https://github.com/aserto-dev/flask-aserto',
+    github: 'https://github.com/aserto-dev/flask-aserto',
     docs: '/docs/software-development-kits/python/flask',
   },
   {