change the project name

documentation

Author: ixtendio

Diff for: README.md

@@ -1,6 +1,133 @@
-# GOW
+<h1 align="center">GOFRE - A Sweet Web Framework for Go</h1>
 
-GOW is a go web framework with middleware support, templating, SSE and more.
+<p align="center">
+<img src="docs/img/gopher.png" />
+</p>
+
+_Gofre_ if a web framework for Go that makes the development of the web applications a joy.  Gofre integrates with `http.Server` and supports the standard handlers: `http.Handler` and `http.HandlerFunc`. 
+
+This framework was developed around simplicity of usage and extensibility and offers the following features: 
+* **Middleware**
+* **Path pattern matching** - including path variable extraction and validation
+* **Templating** - including static resources
+* **Authentication** - OAUTH2 flow included for GitHub and Google
+* **Authorization** - RBAC implementation
+* **SSE (Server Sent-Events)**
+* **Security** - CSRF Middleware protection
+
+## Architecture Overview
+
+_Gofre_ has the following components:
+* **HttpRequest** - an object that encapsulates the initial `http.Request` and the path variables, if exists 
+* **HttpResponse** - an object that encapsulates the response and knows how to write it back to the client
+* **Handler** - a function that receives a `Context` and an `HttpRequest` and returns an `HttpResponse` or an `error`
+* **Middleware** - a function that receives a `Handler` and returns another `Handler`
+* **Router** - an object that knows how to parse the `http.Request` and to route it to the corresponding `Handler`
+
+![Architecture](docs/img/gofre-architecture.png)
+
+### Path Pattern Matching
+
+_Gofre_ supports a complex path matching where the most specific pattern is chosen first. 
+
+Supported path patterns matching:
+
+1. **exact matching**  - `/a/b/c`
+2. **capture variable without constraints** 
+   1. `/a/{b}/{c}`
+      1. `/a/john/doe` => b: john, c: doe
+3. **capture variable with constraints** 
+   1. `/a/{uuid:^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-4[a-fA-F0-9]{3}-[8|9|aA|bB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$}` - UUID matching
+      1. `/a/zyw3040f-0f1c-4e98-b71c-d3cd61213f90` => false (z,x and w are not part of UUID regex)
+      2. `/a/fbd3040f-0f1c-4e98-b71c-d3cd61213f90` => true
+   2. `/a/{number:^[0-9]{3}$}` - number with 3 digits
+      1. `/a/12` => false
+      1. `/a/123` => true
+      1. `/a/012` => true
+      1. `/a/0124` => false
+4. **literal match regex** 
+   1. **&ast;** - matches any number of characters or a single segment path
+      1. `/a/abc*hij`
+         1. `/a/abcdhij` => true
+         2. `/a/abcdefghij` => true
+         3`/a/abcdefgij` => false (the path doesn't end with `hij`)
+      2. `/a/*/c`
+         1. `/a/b/c` => true
+         2. `/a/b/c/c` => false (max 3 path segments allowed, and we have 4)
+      3. `/a/abc*hij/*`
+         1. `/a/abcdefghij/abc` => true
+         2. `/a/abcdefghij/abc/xyz` => false (`*` matches a single path segment and, we have 2 `abc/xyz`)
+   2. **?** - matches a single character
+      1. `/a/abc?hij`
+         1. `/a/abcdhij` => true
+         2. `/a/abcdehij` => false (the character `e` will not match)
+5. **greedy match** 
+   1. **&ast;&ast;** - matches multiple path segments
+      1. `/a/**/z`
+         1. `/a/b/c/d/e/f/z` => true
+         1. `/a/b/c/d/e/f` => false (the path should end in `/z`)
+      2. `/a/**`
+         1. `/a/b/c/d/e/f` => true
+
+Comparing with other libraries, _Gofre_ does not require to declare the path patterns in a specific order so that the match to work as you expect. 
+
+For example, these path matching patterns (assuming we handle only GET requests) can be declared in any order in your code: 
+
+1. `/users/john/{lastName}`
+2. `/users/john/doe`
+3. `/users/*/doe`
+
+Let's consider the following HTTP requests:
+
+* `https://www.website.com/users/john/doe` - the second pattern will match
+* `https://www.website.com/users/john/wick` - the first pattern will match, where the lastName will be `wick`
+* `https://www.website.com/users/jane/doe` - the third pattern will match
+
+_Gofre_ includes also support for greedy path matching: `**`
+
+* `/users/**/doe` - matches any path that starts with `/users` and ends with `/doe` 
+* `/users/**` - matches any path that starts with `/users`
+
+The path matching can be **case-sensitive** (default) or **case-insensitive**
+
+## Installation
+
+You can install this repo with `go get`:
+```sh
+go get github.com/ixtendio/gofre
+```
+## Usage
+
+```go
+gowConfig := &gofre.Config{
+	CaseInsensitivePathMatch: false,
+	ContextPath:              "",
+	ErrLogFunc: func(err error) {
+		log.Printf("An error occurred in the gofre framework: %v", err)
+	},
+}
+gowMux, err := gofre.NewMuxHandler(gowConfig)
+if err != nil {
+	log.Fatalf("Failed to create gofre mux handler, err: %v", err)
+}
+
+// JSON with vars path
+gowMux.HandleGet("/hello/{firstName}/{lastName}", func(ctx context.Context, r *request.HttpRequest) (response.HttpResponse, error) {
+	return response.JsonHttpResponseOK(r.UriVars), nil
+})
+
+httpServer := http.Server{
+	Addr:              ":8080",
+	Handler:           gowMux,
+}
+if err := httpServer.ListenAndServe(); err != nil {
+	log.Fatalf("Failed starting the HTTP server, err: %v", err)
+}
+```
+
+```shell
+curl -vvv "https://localhost:8080/hello/John/Doe"
+```
 
 # Run the examples
 

Diff for: auth/oauth/github.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"github.com/ixtendio/gow/auth"
+	"github.com/ixtendio/gofre/auth"
 	"net/http"
 	"net/url"
 	"strconv"

Diff for: auth/oauth/google.go

@@ -5,7 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"github.com/ixtendio/gow/auth"
+	"github.com/ixtendio/gofre/auth"
 	"net/http"
 	"net/url"
 	"strconv"

Diff for: auth/oauth/oauth2.go

@@ -2,8 +2,8 @@ package oauth
 
 import (
 	"context"
-	"github.com/ixtendio/gow/auth"
-	"github.com/ixtendio/gow/cache"
+	"github.com/ixtendio/gofre/auth"
+	"github.com/ixtendio/gofre/cache"
 	"net"
 	"net/http"
 	"time"

Diff for: examples/cmd.go

@@ -2,14 +2,14 @@ package main
 
 import (
 	"context"
-	"github.com/ixtendio/gow"
-	"github.com/ixtendio/gow/auth"
-	"github.com/ixtendio/gow/auth/oauth"
-	"github.com/ixtendio/gow/cache"
-	"github.com/ixtendio/gow/middleware"
-	"github.com/ixtendio/gow/request"
-	"github.com/ixtendio/gow/response"
-	"github.com/ixtendio/gow/router"
+	"github.com/ixtendio/gofre"
+	"github.com/ixtendio/gofre/auth"
+	"github.com/ixtendio/gofre/auth/oauth"
+	"github.com/ixtendio/gofre/cache"
+	"github.com/ixtendio/gofre/handler"
+	"github.com/ixtendio/gofre/middleware"
+	"github.com/ixtendio/gofre/request"
+	"github.com/ixtendio/gofre/response"
 	"log"
 	"net"
 	"net/http"
@@ -133,7 +133,7 @@ func main() {
 	gowMux.HandleGet("/security/authorize/{permission}", func(ctx context.Context, r *request.HttpRequest) (response.HttpResponse, error) {
 		return response.JsonHttpResponseOK(map[string]string{"authorized": "true"}), nil
 	}, middleware.ErrJsonResponse(),
-		func(handler router.Handler) router.Handler {
+		func(handler handler.Handler) handler.Handler {
 			// authentication provider
 			return func(ctx context.Context, req *request.HttpRequest) (resp response.HttpResponse, err error) {
 				permission, err := auth.ParsePermission("domain/subdomain/resource:" + req.UriVars["permission"])

Diff for: examples/evtgen.go

@@ -3,7 +3,7 @@ package main
 import (
 	"context"
 	"fmt"
-	"github.com/ixtendio/gow/response"
+	"github.com/ixtendio/gofre/response"
 	"sync/atomic"
 	"time"
 )

Diff for: go.mod

@@ -1,5 +1,3 @@
-module github.com/ixtendio/gow
+module github.com/ixtendio/gofre
 
-go 1.19
-
-require github.com/dimfeld/httptreemux/v5 v5.4.0
+go 1.19

Diff for: go.sum

@@ -1,2 +0,0 @@
-github.com/dimfeld/httptreemux/v5 v5.4.0 h1:IiHYEjh+A7pYbhWyjmGnj5HZK6gpOOvyBXCJ+BE8/Gs=
-github.com/dimfeld/httptreemux/v5 v5.4.0/go.mod h1:QeEylH57C0v3VO0tkKraVz9oD3Uu93CKPnTLbsidvSw=

Diff for: gow.go renamed to gofre.go

@@ -4,13 +4,14 @@ import (
 	"context"
 	"expvar"
 	"fmt"
-	"github.com/ixtendio/gow/auth"
-	"github.com/ixtendio/gow/auth/oauth"
-	"github.com/ixtendio/gow/errors"
-	"github.com/ixtendio/gow/middleware"
-	"github.com/ixtendio/gow/request"
-	"github.com/ixtendio/gow/response"
-	"github.com/ixtendio/gow/router"
+	"github.com/ixtendio/gofre/auth"
+	"github.com/ixtendio/gofre/auth/oauth"
+	"github.com/ixtendio/gofre/errors"
+	"github.com/ixtendio/gofre/handler"
+	"github.com/ixtendio/gofre/middleware"
+	"github.com/ixtendio/gofre/request"
+	"github.com/ixtendio/gofre/response"
+	"github.com/ixtendio/gofre/router"
 	"html/template"
 	"log"
 	"math/rand"
@@ -97,7 +98,7 @@ func NewMuxHandler(config *Config) (*MuxHandler, error) {
 		}
 		assetsPath := config.ResourcesConfig.AssetsPath
 		assetsDirPath := config.ResourcesConfig.AssetsDirPath
-		r.Handle(http.MethodGet, fmt.Sprintf("%s/%s/*", contextPath, assetsPath), router.Handler2Handler(http.StripPrefix(fmt.Sprintf("%s/%s/", contextPath, assetsPath), http.FileServer(http.Dir(assetsDirPath)))))
+		r.Handle(http.MethodGet, fmt.Sprintf("%s/%s/*", contextPath, assetsPath), handler.Handler2Handler(http.StripPrefix(fmt.Sprintf("%s/%s/", contextPath, assetsPath), http.FileServer(http.Dir(assetsDirPath)))))
 	}
 	return &MuxHandler{
 		router:    r,
@@ -121,12 +122,12 @@ func (m *MuxHandler) RegisterCommonMiddlewares(middlewares ...middleware.Middlew
 // If the OAUTH2 flow successfully completes, then the oauth.AccessToken will be passed to context.Context
 // to extract it, you have to use the method oauth.GetAccessTokenFromContext(context.Context)
 
-func (m *MuxHandler) HandleOAUTH2(oauthConfig oauth.Config, handler router.Handler, middlewares ...middleware.Middleware) {
+func (m *MuxHandler) HandleOAUTH2(oauthConfig oauth.Config, handler handler.Handler, middlewares ...middleware.Middleware) {
 	m.HandleOAUTH2WithCustomPaths("/oauth/initiate", "/oauth/authorize", oauthConfig, handler, middlewares...)
 }
 
 // HandleOAUTH2WithCustomPaths registers the necessary handlers to initiate and complete the OAUTH2 flow using custom paths
-func (m *MuxHandler) HandleOAUTH2WithCustomPaths(initiatePath string, authorizeBasePath string, oauthConfig oauth.Config, handler router.Handler, middlewares ...middleware.Middleware) {
+func (m *MuxHandler) HandleOAUTH2WithCustomPaths(initiatePath string, authorizeBasePath string, oauthConfig oauth.Config, handler handler.Handler, middlewares ...middleware.Middleware) {
 	cache := oauthConfig.CacheConfig.Cache
 	// initiate OAUTH flow handler
 	authorizationFlowBasePath := authorizeBasePath
@@ -195,73 +196,73 @@ func (m *MuxHandler) HandleOAUTH2WithCustomPaths(initiatePath string, authorizeB
 
 // HandleGet registers a handler with middlewares for GET requests
 // The middlewares will be applied only for this handler
-func (m *MuxHandler) HandleGet(path string, handler router.Handler, middlewares ...middleware.Middleware) {
+func (m *MuxHandler) HandleGet(path string, handler handler.Handler, middlewares ...middleware.Middleware) {
 	m.HandleRequest(http.MethodGet, path, handler, middlewares...)
 }
 
 // HandlePost registers a handler with middlewares for POST requests
 // The middlewares will be applied only for this handler
-func (m *MuxHandler) HandlePost(path string, handler router.Handler, middlewares ...middleware.Middleware) {
+func (m *MuxHandler) HandlePost(path string, handler handler.Handler, middlewares ...middleware.Middleware) {
 	m.HandleRequest(http.MethodPost, path, handler, middlewares...)
 }
 
 // HandlePut registers a handler with middlewares for PUT requests
 // The middlewares will be applied only for this handler
-func (m *MuxHandler) HandlePut(path string, handler router.Handler, middlewares ...middleware.Middleware) {
+func (m *MuxHandler) HandlePut(path string, handler handler.Handler, middlewares ...middleware.Middleware) {
 	m.HandleRequest(http.MethodPut, path, handler, middlewares...)
 }
 
 // HandlePath registers a handler with middlewares for PATCH requests
 // The middlewares will be applied only for this handler
-func (m *MuxHandler) HandlePath(path string, handler router.Handler, middlewares ...middleware.Middleware) {
+func (m *MuxHandler) HandlePath(path string, handler handler.Handler, middlewares ...middleware.Middleware) {
 	m.HandleRequest(http.MethodPatch, path, handler, middlewares...)
 }
 
 // HandleDelete registers a handler with middlewares for DELETE requests
 // The middlewares will be applied only for this handler
-func (m *MuxHandler) HandleDelete(path string, handler router.Handler, middlewares ...middleware.Middleware) {
+func (m *MuxHandler) HandleDelete(path string, handler handler.Handler, middlewares ...middleware.Middleware) {
 	m.HandleRequest(http.MethodDelete, path, handler, middlewares...)
 }
 
 // HandleRequest registers a handler with middlewares for the specified HTTP method
 // The middlewares will be applied only for this handler
-func (m *MuxHandler) HandleRequest(httpMethod string, path string, handler router.Handler, middlewares ...middleware.Middleware) {
-	handler = wrapMiddleware(wrapMiddleware(handler, middlewares...), m.commonMiddlewares...)
+func (m *MuxHandler) HandleRequest(httpMethod string, path string, h handler.Handler, middlewares ...middleware.Middleware) {
+	h = wrapMiddleware(wrapMiddleware(h, middlewares...), m.commonMiddlewares...)
 	var tmpl *template.Template
 	if m.webConfig.ResourcesConfig != nil {
 		tmpl = m.webConfig.ResourcesConfig.Template
 	}
 	//expose contextPath and template on request context
-	handler = wrapMiddleware(handler, func(handler router.Handler) router.Handler {
+	h = wrapMiddleware(h, func(h handler.Handler) handler.Handler {
 		return func(ctx context.Context, r *request.HttpRequest) (response.HttpResponse, error) {
 			ctx = context.WithValue(ctx, KeyValues, &CtxValues{
 				ContextPath: m.webConfig.ContextPath,
 				Template:    tmpl,
 			})
-			return handler(ctx, r)
+			return h(ctx, r)
 		}
 	})
-	m.router.Handle(httpMethod, path, handler)
+	m.router.Handle(httpMethod, path, h)
 }
 
 // EnableDebugEndpoints enable debug endpoints
 func (m MuxHandler) EnableDebugEndpoints() {
 	// Register all the standard library debug endpoints.
-	m.router.Handle(http.MethodGet, "/debug/pprof/", router.HandlerFunc2Handler(pprof.Index))
-	m.router.Handle(http.MethodGet, "/debug/pprof/allocs", router.HandlerFunc2Handler(pprof.Index))
-	m.router.Handle(http.MethodGet, "/debug/pprof/block", router.HandlerFunc2Handler(pprof.Index))
-	m.router.Handle(http.MethodGet, "/debug/pprof/goroutine", router.HandlerFunc2Handler(pprof.Index))
-	m.router.Handle(http.MethodGet, "/debug/pprof/heap", router.HandlerFunc2Handler(pprof.Index))
-	m.router.Handle(http.MethodGet, "/debug/pprof/mutex", router.HandlerFunc2Handler(pprof.Index))
-	m.router.Handle(http.MethodGet, "/debug/pprof/threadcreate", router.HandlerFunc2Handler(pprof.Index))
-	m.router.Handle(http.MethodGet, "/debug/pprof/cmdline", router.HandlerFunc2Handler(pprof.Cmdline))
-	m.router.Handle(http.MethodGet, "/debug/pprof/profile", router.HandlerFunc2Handler(pprof.Profile))
-	m.router.Handle(http.MethodGet, "/debug/pprof/symbol", router.HandlerFunc2Handler(pprof.Symbol))
-	m.router.Handle(http.MethodGet, "/debug/pprof/trace", router.HandlerFunc2Handler(pprof.Trace))
-	m.router.Handle(http.MethodGet, "/debug/vars", router.Handler2Handler(expvar.Handler()))
+	m.router.Handle(http.MethodGet, "/debug/pprof/", handler.HandlerFunc2Handler(pprof.Index))
+	m.router.Handle(http.MethodGet, "/debug/pprof/allocs", handler.HandlerFunc2Handler(pprof.Index))
+	m.router.Handle(http.MethodGet, "/debug/pprof/block", handler.HandlerFunc2Handler(pprof.Index))
+	m.router.Handle(http.MethodGet, "/debug/pprof/goroutine", handler.HandlerFunc2Handler(pprof.Index))
+	m.router.Handle(http.MethodGet, "/debug/pprof/heap", handler.HandlerFunc2Handler(pprof.Index))
+	m.router.Handle(http.MethodGet, "/debug/pprof/mutex", handler.HandlerFunc2Handler(pprof.Index))
+	m.router.Handle(http.MethodGet, "/debug/pprof/threadcreate", handler.HandlerFunc2Handler(pprof.Index))
+	m.router.Handle(http.MethodGet, "/debug/pprof/cmdline", handler.HandlerFunc2Handler(pprof.Cmdline))
+	m.router.Handle(http.MethodGet, "/debug/pprof/profile", handler.HandlerFunc2Handler(pprof.Profile))
+	m.router.Handle(http.MethodGet, "/debug/pprof/symbol", handler.HandlerFunc2Handler(pprof.Symbol))
+	m.router.Handle(http.MethodGet, "/debug/pprof/trace", handler.HandlerFunc2Handler(pprof.Trace))
+	m.router.Handle(http.MethodGet, "/debug/vars", handler.Handler2Handler(expvar.Handler()))
 }
 
-func wrapMiddleware(handler router.Handler, middlewares ...middleware.Middleware) router.Handler {
+func wrapMiddleware(handler handler.Handler, middlewares ...middleware.Middleware) handler.Handler {
 	wrappedHandlers := handler
 	for i := len(middlewares) - 1; i >= 0; i-- {
 		mid := middlewares[i]

Diff for: gow_test.go renamed to gofre_test.go

@@ -1,9 +1,9 @@
-package router
+package handler
 
 import (
 	"context"
-	"github.com/ixtendio/gow/request"
-	"github.com/ixtendio/gow/response"
+	"github.com/ixtendio/gofre/request"
+	"github.com/ixtendio/gofre/response"
 	"net/http"
 )