Add docs from gofiber/contrib@dab06c7

gofiber · Jul 6, 2023 · b500a56 · b500a56
1 parent b26b234
commit b500a56
Show file tree

Hide file tree

Showing 14 changed files with 1,344 additions and 0 deletions.
diff --git a/docs/contrib/README.md b/docs/contrib/README.md
@@ -0,0 +1,47 @@
+# Contrib
+
+[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord)
+![Test](https://github.com/gofiber/contrib/workflows/Tests/badge.svg)
+![Security](https://github.com/gofiber/contrib/workflows/Security/badge.svg)
+![Linter](https://github.com/gofiber/contrib/workflows/Linter/badge.svg)
+
+Repository for third party middlewares with dependencies
+
+## 📑 Middleware Implementations
+
+* [Paseto](/paseto) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+  <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+  </a>
+* [Fiberzap](/fiberzap) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+  <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+  </a>
+* [Otelfiber (OpenTelemetry)](/otelfiber) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+    <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+    </a>
+* [Fibersentry](/fibersentry) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+    <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+    </a>
+* [Swagger](/swagger) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+    <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+    </a>
+* [Casbin](/casbin) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+    <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+    </a>
+* [NewRelic](/fibernewrelic) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+    <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+    </a>
+* [Open Policy Agent](/opafiber) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+    <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+    </a>
+* [Fiberi18n](/fiberi18n) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+  <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+  </a>
+* [Fiberzerolog](/fiberzerolog) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+  <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+  </a>
+* [JWT](/jwt) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+  <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+  </a>
+* [Websocket](/websocket) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Tests%22">
+  <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B">
+  </a>
diff --git a/docs/contrib/casbin/README.md b/docs/contrib/casbin/README.md
@@ -0,0 +1,141 @@
+### Casbin
+Casbin middleware for Fiber
+
+### Install
+```
+go get -u github.com/gofiber/fiber/v2
+go get -u github.com/gofiber/contrib/casbin
+```
+choose an adapter from [here](https://casbin.org/docs/en/adapters)
+```
+go get -u github.com/casbin/xorm-adapter
+```
+
+### Signature
+```go
+casbin.New(config ...casbin.Config) *casbin.Middleware
+```
+
+### Config
+| Property | Type | Description | Default |
+| :--- | :--- | :--- | :--- |
+| ModelFilePath | `string` | Model file path | `"./model.conf"` |
+| PolicyAdapter | `persist.Adapter` | Database adapter for policies | `./policy.csv` |
+| Enforcer | `*casbin.Enforcer` | Custom casbin enforcer | `Middleware generated enforcer using ModelFilePath & PolicyAdapter` |
+| Lookup | `func(*fiber.Ctx) string` | Look up for current subject | `""` |
+| Unauthorized | `func(*fiber.Ctx) error` | Response body for unauthorized responses | `Unauthorized` |
+| Forbidden | `func(*fiber.Ctx) error` | Response body for forbidden responses | `Forbidden` |
+
+### Examples
+- [Gorm Adapter](https://github.com/svcg/-fiber_casbin_demo)
+- [File Adapter](https://github.com/gofiber/contrib/casbin/tree/master/example)
+
+### CustomPermission
+
+```go
+package main
+
+import (
+  "github.com/gofiber/fiber/v2"
+  "github.com/gofiber/contrib/casbin"
+  _ "github.com/go-sql-driver/mysql"
+  "github.com/casbin/xorm-adapter/v2"
+)
+
+func main() {
+  app := fiber.New()
+
+  authz := casbin.New(casbin.Config{
+      ModelFilePath: "path/to/rbac_model.conf",
+      PolicyAdapter: xormadapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/"),
+      Lookup: func(c *fiber.Ctx) string {
+          // fetch authenticated user subject
+      },
+  })
+
+  app.Post("/blog",
+      authz.RequiresPermissions([]string{"blog:create"}, casbin.WithValidationRule(casbin.MatchAllRule)),
+      func(c *fiber.Ctx) error {
+        // your handler
+      },
+  )
+
+  app.Delete("/blog/:id",
+    authz.RequiresPermissions([]string{"blog:create", "blog:delete"}, casbin.WithValidationRule(casbin.AtLeastOneRule)),
+    func(c *fiber.Ctx) error {
+      // your handler
+    },
+  )
+
+  app.Listen(":8080")
+}
+```
+
+### RoutePermission
+
+```go
+package main
+
+import (
+  "github.com/gofiber/fiber/v2"
+  "github.com/gofiber/contrib/casbin"
+  _ "github.com/go-sql-driver/mysql"
+  "github.com/casbin/xorm-adapter/v2"
+)
+
+func main() {
+  app := fiber.New()
+
+  authz := casbin.New(casbin.Config{
+      ModelFilePath: "path/to/rbac_model.conf",
+      PolicyAdapter: xormadapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/"),
+      Lookup: func(c *fiber.Ctx) string {
+          // fetch authenticated user subject
+      },
+  })
+
+  // check permission with Method and Path
+  app.Post("/blog",
+    authz.RoutePermission(),
+    func(c *fiber.Ctx) error {
+      // your handler
+    },
+  )
+
+  app.Listen(":8080")
+}
+```
+
+### RoleAuthorization
+
+```go
+package main
+
+import (
+  "github.com/gofiber/fiber/v2"
+  "github.com/gofiber/contrib/casbin"
+  _ "github.com/go-sql-driver/mysql"
+  "github.com/casbin/xorm-adapter/v2"
+)
+
+func main() {
+  app := fiber.New()
+
+  authz := casbin.New(casbin.Config{
+      ModelFilePath: "path/to/rbac_model.conf",
+      PolicyAdapter: xormadapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/"),
+      Lookup: func(c *fiber.Ctx) string {
+          // fetch authenticated user subject
+      },
+  })
+
+  app.Put("/blog/:id",
+    authz.RequiresRoles([]string{"admin"}),
+    func(c *fiber.Ctx) error {
+      // your handler
+    },
+  )
+
+  app.Listen(":8080")
+}
+```
diff --git a/docs/contrib/fiberi18n/README.md b/docs/contrib/fiberi18n/README.md
@@ -0,0 +1,74 @@
+# Fiberi18n
+
+![Release](https://img.shields.io/github/release/gofiber/contrib.svg)
+[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord)
+![Test](https://github.com/gofiber/contrib/workflows/Tests/badge.svg)
+![Security](https://github.com/gofiber/contrib/workflows/Security/badge.svg)
+![Linter](https://github.com/gofiber/contrib/workflows/Linter/badge.svg)
+
+[go-i18n](https://github.com/nicksnyder/go-i18n) support for Fiber.
+
+### Install
+
+This middleware supports Fiber v2.
+
+```
+go get -u github.com/gofiber/fiber/v2
+go get -u github.com/gofiber/contrib/fiberi18n
+```
+
+### Signature
+
+```
+fiberi18n.New(config ...*Config) fiber.Handler
+```
+
+### Config
+
+| Property         | Type                                              | Description                                                  | Default                                                      |
+| ---------------- | ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| Next             | `func(c *fiber.Ctx) bool`                         | A function to skip this middleware when returned `true`.     | `nil`                                                        |
+| RootPath         | `string`                                          | The i18n template folder path.                               | `"./example/localize"`                                       |
+| AcceptLanguages  | `[]language.Tag`                                  | A collection of languages that can be processed.             | `[]language.Tag{language.Chinese, language.English}`         |
+| FormatBundleFile | `string`                                          | The type of the template file.                               | `"yaml"`                                                     |
+| DefaultLanguage  | `language.Tag`                                    | The default returned language type.                          | `language.English`                                           |
+| Loader           | `Loader`                                          | The implementation of the Loader interface, which defines how to read the file. We provide both os.ReadFile and embed.FS.ReadFile. | `LoaderFunc(os.ReadFile)`                                    |
+| UnmarshalFunc    | `i18n.UnmarshalFunc`                              | The function used for decoding template files.               | `yaml.Unmarshal`                                             |
+| LangHandler      | `func(ctx *fiber.Ctx, defaultLang string) string` | Used to get the kind of language handled by *fiber.Ctx and defaultLang. | Retrieved from the request header `Accept-Language` or query parameter `lang`. |
+
+### Example
+
+```go
+package main
+
+import (
+	"github.com/gofiber/contrib/fiberi18n"
+	"github.com/gofiber/fiber/v2"
+	"github.com/nicksnyder/go-i18n/v2/i18n"
+	"golang.org/x/text/language"
+)
+
+func main() {
+	app := fiber.New()
+	app.Use(
+		fiberi18n.New(&fiberi18n.Config{
+			RootPath:        "./example/localize",
+			AcceptLanguages: []language.Tag{language.Chinese, language.English},
+			DefaultLanguage: language.Chinese,
+		}),
+	)
+	app.Get("/", func(c *fiber.Ctx) error {
+		return c.SendString(fiberi18n.MustGetMessage("welcome"))
+	})
+	app.Get("/:name", func(ctx *fiber.Ctx) error {
+		return ctx.SendString(fiberi18n.MustGetMessage(&i18n.LocalizeConfig{
+			MessageID: "welcomeWithName",
+			TemplateData: map[string]string{
+				"name": ctx.Params("name"),
+			},
+		}))
+	})
+	app.Listen("127.0.0.1:3000")
+}
+```
+
diff --git a/docs/contrib/fibernewrelic/README.md b/docs/contrib/fibernewrelic/README.md
@@ -0,0 +1,95 @@
+### NewRelic
+![Release](https://img.shields.io/github/release/gofiber/contrib.svg)
+[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord)
+![Test](https://github.com/gofiber/contrib/workflows/Tests/badge.svg)
+![Security](https://github.com/gofiber/contrib/workflows/Security/badge.svg)
+![Linter](https://github.com/gofiber/contrib/workflows/Linter/badge.svg)
+
+[NewRelic](https://github.com/newrelic/go-agent) support for Fiber.
+
+### Install
+
+```
+go get -u github.com/gofiber/fiber/v2
+go get -u github.com/gofiber/contrib/fibernewrelic
+```
+
+### Signature
+
+```go
+fibernewrelic.New(config fibernewrelic.Config) fiber.Handler
+```
+
+### Config
+
+| Property          | Type             | Description                            | Default        |
+|:------------------|:-----------------|:---------------------------------------|:---------------|
+| License           | `string`         | Required - New Relic License Key       | `""`           |
+| AppName           | `string`         | New Relic Application Name             | `fiber-api`    |
+| Enabled           | `bool`           | Enable/Disable New Relic               | `false`        |
+| ~~TransportType~~ | ~~`string`~~     | ~~Can be HTTP or HTTPS~~ (Deprecated)  | ~~`"HTTP"`~~   |
+| Application       | `Application`    | Existing New Relic App                 | `nil`          |
+| ErrorStatusCodeHandler       | `func(c *fiber.Ctx, err error) int`    | If you want to change newrelic status code, you can use it.                 | `DefaultErrorStatusCodeHandler`          |
+
+### Usage
+
+```go
+package main
+
+import (
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/contrib/fibernewrelic"
+)
+
+func main() {
+	app := fiber.New()
+
+	app.Get("/", func(ctx *fiber.Ctx) error {
+		return ctx.SendStatus(200)
+	})
+
+	cfg := fibernewrelic.Config{
+		License:       "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",
+		AppName:       "MyCustomApi",
+		Enabled:       true,
+	}
+
+	app.Use(fibernewrelic.New(cfg))
+
+	app.Listen(":8080")
+}
+```
+
+### Usage with existing New Relic application
+
+```go
+package main
+
+import (
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/contrib/fibernewrelic"
+	"github.com/newrelic/go-agent/v3/newrelic"
+)
+
+func main() {
+	newrelicApp, err := newrelic.NewApplication(
+		newrelic.ConfigAppName("MyCustomApi"),
+		newrelic.ConfigLicense("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"),
+		newrelic.ConfigEnabled(true),
+	)
+
+	app := fiber.New()
+
+	app.Get("/", func(ctx *fiber.Ctx) error {
+		return ctx.SendStatus(200)
+	})
+
+	cfg := fibernewrelic.Config{
+		Application:       newrelicApp
+	}
+
+	app.Use(fibernewrelic.New(cfg))
+
+	app.Listen(":8080")
+}
+```