diff --git a/docs/index.md b/docs/index.md index 42af2cb..49665f6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -101,10 +101,6 @@ docker pull ghcr.io/jkaninda/goma-gateway Documentation references Docker Hub, but all examples will work using ghcr.io just as well. -## Supported Engines - -This image is developed and tested against the Docker CE engine exclusively. -While it may work against different implementations, there are no guarantees about support for non-Docker engines. ## References diff --git a/docs/middleware/intro.md b/docs/middleware/intro.md deleted file mode 100644 index 7519046..0000000 --- a/docs/middleware/intro.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Intro -layout: default -parent: Middleware -nav_order: 1 ---- -# Middlewares - -Middleware is a function executed before (or after) the route callback. - -This is a great way to add API authentication checks, or to validate that the user has permission to access the route. - -With Goma you can create your middleware based on the type you want and apply it on your routes - -Goma Gateway supports : - -- Authentication middleware - - JWT `client authorization based on the result of a request` - - Basic-Auth - - OAuth -- Rate limiting middleware - - In-Memory client IP based -- Access middleware \ No newline at end of file diff --git a/docs/middleware/jwt.md b/docs/middleware/jwt.md index 1f7ea8c..76af83f 100644 --- a/docs/middleware/jwt.md +++ b/docs/middleware/jwt.md @@ -9,7 +9,7 @@ nav_order: 4 ### JWT middleware As BasicAuth, JWT middleware grants also access to route to authorized users only. -It implements client authorization based on the result of a request. +It implements client authorization based on the result of a request using JSON Web Tokens. If the request returns a 200 response code, access is allowed. If it returns 401 or 403, the access is denied with the corresponding error code. Any other response code returned by the request is considered an error. diff --git a/docs/middleware/overview.md b/docs/middleware/overview.md new file mode 100644 index 0000000..c81203d --- /dev/null +++ b/docs/middleware/overview.md @@ -0,0 +1,29 @@ +--- +title: Overview +layout: default +parent: Middleware +nav_order: 1 +--- +# Middlewares + +Middleware functions are executed before or after a route callback, enabling you to extend the behavior of your routes. + +They are an excellent way to implement features like API authentication, access control, or request validation. + +With Goma, you can create custom middleware tailored to your needs and apply them to your routes seamlessly. + +## Supported Middleware Types + +- **Authentication Middleware** + - **JWT**: Performs client authorization based on the result of a request using JSON Web Tokens. + - **Basic-Auth**: Verifies credentials through Basic Authentication. + - **OAuth**: Supports OAuth-based authentication flows. + +- **Rate Limiting Middleware** + - **In-Memory Client IP Based**: Throttles requests based on the client’s IP address using an in-memory store. + - **Distributed Rate Limiting**: Leverage Redis for scalable, client IP-based rate limits. + +- **Access Middleware** + - Validates user permissions or access rights for specific route paths. + +Middleware provides a flexible and powerful way to enhance the functionality, security, and performance of your API. diff --git a/docs/quickstart/distrubuted-intance.md b/docs/quickstart/distrubuted-intance.md index e798575..2c0657f 100644 --- a/docs/quickstart/distrubuted-intance.md +++ b/docs/quickstart/distrubuted-intance.md @@ -8,6 +8,10 @@ nav_order: 5 # Distributed instances +Goma Gateway includes built-in support for Redis-based rate limiting, enabling efficient and scalable deployments. + +By leveraging Redis, the Gateway ensures high-performance request throttling and distributed rate limiting across multiple instances, making it ideal for modern, cloud-native architectures. + ```yaml version: "1.0" gateway: diff --git a/docs/quickstart/extra-route.md b/docs/quickstart/extra-route.md index e6267d5..efef503 100644 --- a/docs/quickstart/extra-route.md +++ b/docs/quickstart/extra-route.md @@ -31,6 +31,8 @@ gateway: - path: / name: example ``` +## Routes Configuration +Below is an example of configuring routes for the Gateway, defining service paths, methods, backends, health checks, and other settings. Create a file in `/etc/goma/extra` using `yaml` or `.yaml` extension. @@ -86,6 +88,7 @@ Create a file in `/etc/goma/extra` using `yaml` or `.yaml` extension. disableHostFording: true interceptErrors: [404,401] blockCommonExploits: false + ## List of middleware middlewares: - auth-middleware diff --git a/docs/quickstart/gateway.md b/docs/quickstart/gateway.md index e8db1e7..97c2e28 100644 --- a/docs/quickstart/gateway.md +++ b/docs/quickstart/gateway.md @@ -7,49 +7,51 @@ nav_order: 1 # Gateway -```yaml -version: 1.0 -gateway: - sslCertFile: /etc/goma/cert.pem - sslKeyFile: /etc/goma/key.pem - writeTimeout: 15 - readTimeout: 15 - idleTimeout: 30 - # Rate limiting - rateLimit: 0 - accessLog: /dev/Stdout - errorLog: /dev/stderr - logLevel: info - ## Add additional routes - extraRoutes: - # path - directory: /etc/goma/extra - watch: true - disableRouteHealthCheckError: false - disableDisplayRouteOnStart: false - disableKeepAlive: false - disableHealthCheckStatus: false - blockCommonExploits: true - # Intercept backend errors - interceptErrors: - - 500 - cors: - origins: - - http://localhost:8080 - - https://example.com - headers: - Access-Control-Allow-Credentials: "true" - Access-Control-Allow-Headers: Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id - Access-Control-Max-Age: "1728000" - routes: [] -``` -## Extra Routes +The Gateway serves as the entry point to the server. This section provides options to configure the proxy server, define routes, and specify additional routes. -The Extra Routes feature allows you to define additional routes by using .yml or .yaml files stored in a specified directory. +These settings enable precise control over traffic flow and routing within your deployment. -This approach helps you avoid the complexity of managing all routes in a single file. +## Configuration Options -When dealing with many routes, maintaining them in one file can quickly become unwieldy. With this feature, you can organize your routes into separate files, making them easier to manage and maintain. +- **`sslCertFile`** (`string`): Path to the SSL certificate file. +- **`sslKeyFile`** (`string`): Path to the SSL certificate private key file. +- **`redis`**: Redis configuration settings. +- **`writeTimeout`** (`integer`): Timeout for writing responses (in seconds). +- **`readTimeout`** (`integer`): Timeout for reading requests (in seconds). +- **`idleTimeout`** (`integer`): Timeout for idle connections (in seconds). +- **`rateLimit`** (`integer`): Global rate limiting for the proxy. +- **`blockCommonExploits`** (`boolean`): Enable or disable blocking of common exploits. +- **`accessLog`** (`string`, default: `/dev/stdout`): Path for access logs. +- **`errorLog`** (`string`, default: `/dev/stderr`): Path for error logs. +- **`logLevel`** (`string`): Log verbosity level (e.g., `info`, `debug`, `error`). +- **`disableHealthCheckStatus`** (`boolean`): Enable or disable exposing the health check route status. +- **`disableRouteHealthCheckError`** (`boolean`): Enable or disable returning health check error responses for routes. +- **`disableDisplayRouteOnStart`** (`boolean`): Enable or disable displaying routes during server startup. +- **`disableKeepAlive`** (`boolean`): Enable or disable `keepAlive` for the proxy. +- **`enableMetrics`** (`boolean`): Enable or disable server metrics collection. +- **`interceptErrors`** (`array of integers`): List of HTTP status codes to intercept for custom handling. + +### CORS Configuration + +Customize Cross-Origin Resource Sharing (CORS) settings for the proxy: + +- **`origins`** (`array of strings`): List of allowed origins. +- **`headers`** (`map[string]string`): Custom headers to include in responses. + +### Additional Routes + +Define custom routes for additional flexibility: + +- **`directory`** (`string`): Directory path for serving extra routes. +- **`watch`** (`boolean`): Watch the directory for changes and update routes dynamically. + +### Routes + +Define the main routes for the Gateway, enabling routing logic for incoming requests. + +--- + +## Example Configuration ```yaml version: 1.0 @@ -72,11 +74,13 @@ gateway: # Intercept backend errors interceptErrors: - 500 + - 405 cors: origins: - http://localhost:8080 - https://example.com headers: + X-Custom-Header: "Value" Access-Control-Allow-Credentials: "true" Access-Control-Allow-Headers: Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id Access-Control-Max-Age: "1728000" diff --git a/docs/quickstart/healthcheck.md b/docs/quickstart/healthcheck.md index f92f469..3cb3cea 100644 --- a/docs/quickstart/healthcheck.md +++ b/docs/quickstart/healthcheck.md @@ -8,7 +8,9 @@ nav_order: 5 # Healthcheck -Goma comes with routes healthcheck, that can be enabled and disabled. +The proxy includes built-in health check routes, which can be easily enabled or disabled based on your requirements. + +These routes allow you to monitor the health and availability of your services. ```yaml version: 1.0 diff --git a/docs/quickstart/route.md b/docs/quickstart/route.md index a0836ea..832c020 100644 --- a/docs/quickstart/route.md +++ b/docs/quickstart/route.md @@ -10,6 +10,46 @@ nav_order: 2 The Route allows you to match on HTTP traffic and direct it to the backend. + +## Configuration Options + +This section outlines the available configuration options for defining routes in the Gateway. + +### Route Configuration + +- **`path`** (`string`): The route path (e.g., `/api/v1/resource`). +- **`name`** (`string`): A unique name for the route. +- **`hosts`** (`list of strings`): A list of allowed hostnames for the route. +- **`rewrite`** (`string`): Rewrites the incoming route path to a new path. +- **`methods`** (`array of strings`): A list of allowed HTTP methods (e.g., `GET`, `POST`). +- **`destination`** (`string`): The backend endpoint for the route. +- **`backends`** (`list of strings`): A list of backend services for load balancing. +- **`insecureSkipVerify`** (`boolean`): Disables backend TLS certificate verification. + +## Health Check Configuration + +- **`healthCheck`**: + - **`path`** (`string`): The health check path (e.g., `/health`). + - **`interval`** (`string`, default: `30s`): The interval between health checks. + - **`timeout`** (`string`, default: `10s`): The maximum time to wait for a health check response. + - **`healthyStatuses`** (`array of integers`): A list of HTTP status codes considered healthy. + +## CORS Configuration + +- **`cors`**: + - **`origins`** (`array of strings`): A list of allowed origins for Cross-Origin Resource Sharing (CORS). + - **`headers`** (`array of strings`): A list of custom headers to include in responses. + +## Additional Options + +- **`rateLimit`** (`integer`): The maximum number of requests allowed per minute. +- **`disableHostFording`** (`boolean`): Disables proxy host forwarding for improved security. +- **`interceptErrors`** (`array of integers`): A list of backend error status codes to intercept for custom handling. +- **`blockCommonExploits`** (`boolean`): Enables or disables blocking of common exploits. +- **`middlewares`** (`array of strings`): A list of middleware names applied to the route. + +--- + ### Simple route ```yaml diff --git a/examples/goma.yml b/examples/goma.yml index 06faaaf..e9e2821 100644 --- a/examples/goma.yml +++ b/examples/goma.yml @@ -16,7 +16,6 @@ gateway: logLevel: info # debug, trace, off accessLog: "/dev/Stdout" errorLog: "/dev/stderr" - ## Redis connexion for distributed rate limiting, when using multiple instances | It's optional #redis: #addr: redis:6379 # password: password diff --git a/internal/healthcheck.go b/internal/healthcheck.go index b50c237..cc38baa 100644 --- a/internal/healthcheck.go +++ b/internal/healthcheck.go @@ -71,6 +71,8 @@ func (health Health) Check() error { } return nil } + +// routesHealthCheck creates healthcheck job func routesHealthCheck(routes []Route) { for _, health := range healthCheckRoutes(routes) { go func() { @@ -84,11 +86,14 @@ func routesHealthCheck(routes []Route) { } } + +// createHealthCheckJob create healthcheck job func (health Health) createHealthCheckJob() error { interval := "30s" if len(health.Interval) > 0 { interval = health.Interval } + // create cron expression expression := fmt.Sprintf("@every %s", interval) if !util.IsValidCronExpression(expression) { logger.Error("Health check interval is invalid: %s", interval) @@ -113,3 +118,45 @@ func (health Health) createHealthCheckJob() error { defer c.Stop() select {} } + +// healthCheckRoutes creates and returns []Health +func healthCheckRoutes(routes []Route) []Health { + var healthRoutes []Health + for _, route := range routes { + if len(route.HealthCheck.Path) != 0 { + timeout, _ := util.ParseDuration("") + if len(route.HealthCheck.Timeout) > 0 { + d1, err1 := util.ParseDuration(route.HealthCheck.Timeout) + if err1 != nil { + logger.Error("Health check timeout is invalid: %s", route.HealthCheck.Timeout) + } + timeout = d1 + } + if len(route.Backends) != 0 { + for index, backend := range route.Backends { + health := Health{ + Name: fmt.Sprintf("%s - [%d]", route.Name, index), + URL: backend + route.HealthCheck.Path, + TimeOut: timeout, + HealthyStatuses: route.HealthCheck.HealthyStatuses, + InsecureSkipVerify: route.InsecureSkipVerify, + } + healthRoutes = append(healthRoutes, health) + } + + } else { + health := Health{ + Name: route.Name, + URL: route.Destination + route.HealthCheck.Path, + TimeOut: timeout, + HealthyStatuses: route.HealthCheck.HealthyStatuses, + InsecureSkipVerify: route.InsecureSkipVerify, + } + healthRoutes = append(healthRoutes, health) + } + } else { + logger.Debug("Route %s's healthCheck is undefined", route.Name) + } + } + return healthRoutes +} diff --git a/internal/helpers.go b/internal/helpers.go index 992b0f7..60e53b4 100644 --- a/internal/helpers.go +++ b/internal/helpers.go @@ -11,25 +11,20 @@ You may get a copy of the License at */ import ( "context" - "crypto/tls" "encoding/json" "fmt" - "github.com/golang-jwt/jwt" "github.com/jedib0t/go-pretty/v6/table" - "github.com/jkaninda/goma-gateway/pkg/logger" - "github.com/jkaninda/goma-gateway/util" "golang.org/x/oauth2" "io" "net/http" - "time" ) // printRoute prints routes func printRoute(routes []Route) { t := table.NewWriter() - t.AppendHeader(table.Row{"Name", "Route", "Rewrite", "Destination"}) + t.AppendHeader(table.Row{"Name", "Path", "Rewrite", "Destination"}) for _, route := range routes { - if len(route.Backends) > 0 { + if len(route.Backends) != 0 { t.AppendRow(table.Row{route.Name, route.Path, route.Rewrite, fmt.Sprintf("backends: [%d]", len(route.Backends))}) } else { @@ -50,21 +45,6 @@ func getRealIP(r *http.Request) string { return r.RemoteAddr } -// loadTLS loads TLS Certificate -func loadTLS(cert, key string) (*tls.Config, error) { - if cert == "" && key == "" { - return nil, fmt.Errorf("no certificate or key file provided") - } - serverCert, err := tls.LoadX509KeyPair(cert, key) - if err != nil { - logger.Error("Error loading server certificate: %v", err) - return nil, err - } - tlsConfig := &tls.Config{ - Certificates: []tls.Certificate{serverCert}, - } - return tlsConfig, nil -} func (oauth *OauthRulerMiddleware) getUserInfo(token *oauth2.Token) (UserInfo, error) { oauthConfig := oauth2Config(oauth) // Call the user info endpoint with the token @@ -88,64 +68,3 @@ func (oauth *OauthRulerMiddleware) getUserInfo(token *oauth2.Token) (UserInfo, e return userInfo, nil } -func createJWT(email, jwtSecret string) (string, error) { - // Define JWT claims - claims := jwt.MapClaims{ - "email": email, - "exp": jwt.TimeFunc().Add(time.Hour * 24).Unix(), // Token expiration - "iss": "Goma-Gateway", // Issuer claim - } - - // Create a new token with HS256 signing method - token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims) - - // Sign the token with a secret - signedToken, err := token.SignedString([]byte(jwtSecret)) - if err != nil { - return "", err - } - - return signedToken, nil -} - -// healthCheckRoutes creates []Health -func healthCheckRoutes(routes []Route) []Health { - var healthRoutes []Health - for _, route := range routes { - if len(route.HealthCheck.Path) > 0 { - timeout, _ := util.ParseDuration("") - if len(route.HealthCheck.Timeout) > 0 { - d1, err1 := util.ParseDuration(route.HealthCheck.Timeout) - if err1 != nil { - logger.Error("Health check timeout is invalid: %s", route.HealthCheck.Timeout) - } - timeout = d1 - } - if len(route.Backends) > 0 { - for index, backend := range route.Backends { - health := Health{ - Name: fmt.Sprintf("%s - [%d]", route.Name, index), - URL: backend + route.HealthCheck.Path, - TimeOut: timeout, - HealthyStatuses: route.HealthCheck.HealthyStatuses, - InsecureSkipVerify: route.InsecureSkipVerify, - } - healthRoutes = append(healthRoutes, health) - } - - } else { - health := Health{ - Name: route.Name, - URL: route.Destination + route.HealthCheck.Path, - TimeOut: timeout, - HealthyStatuses: route.HealthCheck.HealthyStatuses, - InsecureSkipVerify: route.InsecureSkipVerify, - } - healthRoutes = append(healthRoutes, health) - } - } else { - logger.Debug("Route %s's healthCheck is undefined", route.Name) - } - } - return healthRoutes -} diff --git a/internal/jwt.go b/internal/jwt.go new file mode 100644 index 0000000..a6d477d --- /dev/null +++ b/internal/jwt.go @@ -0,0 +1,44 @@ +/* + * Copyright 2024 Jonas Kaninda + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +package pkg + +import ( + "github.com/golang-jwt/jwt" + "time" +) + +// createJWT create JWT token +func createJWT(email, jwtSecret string) (string, error) { + // Define JWT claims + claims := jwt.MapClaims{ + "email": email, + "exp": jwt.TimeFunc().Add(time.Hour * 24).Unix(), // Token expiration + "iss": "Goma-Gateway", // Issuer claim + } + + // Create a new token with HS256 signing method + token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims) + + // Sign the token with a secret + signedToken, err := token.SignedString([]byte(jwtSecret)) + if err != nil { + return "", err + } + + return signedToken, nil +} diff --git a/internal/metrics/prometheus.go b/internal/metrics/prometheus.go index 65ec31e..5c32e27 100644 --- a/internal/metrics/prometheus.go +++ b/internal/metrics/prometheus.go @@ -52,6 +52,7 @@ var HttpDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{ Help: "Duration of HTTP requests.", }, []string{"name", "path"}) +// PrometheusMiddleware Prometheus http handler middleware, returns http.Handler func (pr PrometheusRoute) PrometheusMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { path := pr.Path diff --git a/internal/middlewares/access-middleware.go b/internal/middlewares/access_middleware.go similarity index 100% rename from internal/middlewares/access-middleware.go rename to internal/middlewares/access_middleware.go diff --git a/internal/middlewares/block-common-exploits.go b/internal/middlewares/block_common_exploits.go similarity index 100% rename from internal/middlewares/block-common-exploits.go rename to internal/middlewares/block_common_exploits.go diff --git a/internal/middlewares/error-interceptor.go b/internal/middlewares/error_interceptor.go similarity index 100% rename from internal/middlewares/error-interceptor.go rename to internal/middlewares/error_interceptor.go diff --git a/internal/middlewares/helpers.go b/internal/middlewares/helpers.go index 351f182..a308b84 100644 --- a/internal/middlewares/helpers.go +++ b/internal/middlewares/helpers.go @@ -23,6 +23,7 @@ import ( "slices" ) +// getRealIP returns user real IP func getRealIP(r *http.Request) string { if ip := r.Header.Get("X-Real-IP"); ip != "" { return ip diff --git a/internal/middlewares/oauth-middleware.go b/internal/middlewares/oauth_middleware.go similarity index 100% rename from internal/middlewares/oauth-middleware.go rename to internal/middlewares/oauth_middleware.go diff --git a/internal/middlewares/rate-limit.go b/internal/middlewares/rate_limit.go similarity index 100% rename from internal/middlewares/rate-limit.go rename to internal/middlewares/rate_limit.go diff --git a/internal/middlewares/redis.go b/internal/middlewares/redis.go index 4f1dd0e..1f199d2 100644 --- a/internal/middlewares/redis.go +++ b/internal/middlewares/redis.go @@ -24,6 +24,7 @@ import ( "github.com/redis/go-redis/v9" ) +// redisRateLimiter, handle rateLimit func redisRateLimiter(clientIP string, rate int) error { ctx := context.Background() diff --git a/internal/proxy.go b/internal/proxy.go index dac8b20..1f6a472 100644 --- a/internal/proxy.go +++ b/internal/proxy.go @@ -74,7 +74,7 @@ func (proxyRoute ProxyRoute) ProxyHandler() http.HandlerFunc { r.Host = targetURL.Host } backendURL, _ := url.Parse(proxyRoute.destination) - if len(proxyRoute.backends) > 0 { + if len(proxyRoute.backends) != 0 { // Select the next backend URL backendURL = getNextBackend(proxyRoute.backends) } @@ -87,8 +87,7 @@ func (proxyRoute ProxyRoute) ProxyHandler() http.HandlerFunc { InsecureSkipVerify: proxyRoute.insecureSkipVerify, }, } - w.Header().Set("Proxied-By", gatewayName) // Set Server name - w.Header().Del("Server") // Remove the Server header + w.Header().Set("Proxied-By", gatewayName) // Custom error handler for proxy errors proxy.ErrorHandler = ProxyErrorHandler proxy.ServeHTTP(w, r) diff --git a/internal/route.go b/internal/routes.go similarity index 99% rename from internal/route.go rename to internal/routes.go index 867bd81..084b36e 100644 --- a/internal/route.go +++ b/internal/routes.go @@ -26,6 +26,7 @@ import ( "time" ) +// init initializes prometheus metrics func init() { _ = prometheus.Register(metrics.TotalRequests) _ = prometheus.Register(metrics.ResponseStatus) @@ -88,6 +89,7 @@ func (gatewayServer GatewayServer) Initialize() *mux.Router { logger.Info("Block common exploits enabled") r.Use(middlewares.BlockExploitsMiddleware) } + // check if RateLimit is set if gateway.RateLimit != 0 { // Add rate limit middlewares to all routes, if defined rateLimit := middlewares.RateLimit{ diff --git a/internal/route_test.go b/internal/routes_test.go similarity index 100% rename from internal/route_test.go rename to internal/routes_test.go diff --git a/internal/tls.go b/internal/tls.go index 6ca0000..fda25f1 100644 --- a/internal/tls.go +++ b/internal/tls.go @@ -20,6 +20,7 @@ package pkg import ( "crypto/tls" "fmt" + "github.com/jkaninda/goma-gateway/pkg/logger" ) func (gatewayServer GatewayServer) initTLS() (*tls.Config, bool, error) { @@ -34,3 +35,19 @@ func (gatewayServer GatewayServer) initTLS() (*tls.Config, bool, error) { } return tlsConfig, true, nil } + +// loadTLS loads TLS Certificate +func loadTLS(cert, key string) (*tls.Config, error) { + if cert == "" && key == "" { + return nil, fmt.Errorf("no certificate or key file provided") + } + serverCert, err := tls.LoadX509KeyPair(cert, key) + if err != nil { + logger.Error("Error loading server certificate: %v", err) + return nil, err + } + tlsConfig := &tls.Config{ + Certificates: []tls.Certificate{serverCert}, + } + return tlsConfig, nil +}