Initial commit

Author: slhmy

.github/workflows/deploy-mdbook.yml

@@ -0,0 +1,31 @@
+name: Deploy mdBook
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  pages: write
+  id-token: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust (rustup)
+        run: rustup update stable --no-self-update && rustup default stable
+      - name: Install mdBook
+        run: cargo install mdbook
+      - name: Build doc
+        run: mdbook build doc
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/book
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.github/workflows/lint.yml

@@ -0,0 +1,16 @@
+name: Lint
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@v8

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "go.testFlags": ["-v", "-count=1"],
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.formatOnPaste": true
+  }
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 slhmy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,27 @@
+# GWM (Golang Web Modules)
+
+Solution collection for quickly setting up
+Golang web applications (Currently especially for Gin framework).
+
+## Why GWM?
+
+GWM maintains the best practices and patterns for building web applications in Go.
+If painlessly building a web application in Go is your goal, GWM is the solution.
+It provides a solid foundation for your application,
+allowing you to focus on building features rather than boilerplate code.
+
+### Application Core
+
+- **Configuration Store** depends on [viper](https://github.com/spf13/viper) for managing application configuration.
+- **Slog Logger** with contextual logging and support (using [tint](github.com/lmittmann/tint) for colorized output).
+
+### Clients
+
+- **MongoDB Driver** for MongoDB database operations.
+- **Redis Clients** for Redis operations and other Redis-based services (For example, distributed locks & caching).
+
+### Modules
+
+- **Gin** for Gin framework, including middleware and helpers.
+
+See more in [documentation](https://slhmy.github.io/go-webmods).

app/config.go

@@ -0,0 +1,52 @@
+package gwm_app
+
+import (
+	"os"
+	"path"
+	"strings"
+
+	"github.com/spf13/viper"
+)
+
+const (
+	envRelativeConfigPath = "GWM_RELATIVE_CONFIG_PATH"
+	envOverrideConfigName = "GWM_OVERRIDE_CONFIG_NAME"
+
+	defaultConfigName         = "config"
+	defaultOverrideConfigName = "override"
+)
+
+var (
+	config *viper.Viper
+)
+
+func Config() *viper.Viper {
+	return config
+}
+
+func init() {
+	cwd, _ := os.Getwd()
+	relativeConfigPath := os.Getenv(envRelativeConfigPath)
+	viper.AddConfigPath(path.Join(cwd, relativeConfigPath))
+	viper.SetConfigName(defaultConfigName)
+	err := viper.ReadInConfig()
+	if err != nil {
+		if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+			panic(err)
+		}
+	}
+	overrideConfigName := os.Getenv(envOverrideConfigName)
+	if len(overrideConfigName) == 0 {
+		overrideConfigName = defaultOverrideConfigName
+	}
+	viper.SetConfigName(overrideConfigName)
+	err = viper.MergeInConfig()
+	if err != nil {
+		if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+			panic(err)
+		}
+	}
+	viper.AutomaticEnv()
+	viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+	config = viper.GetViper()
+}

app/error.go

@@ -0,0 +1,65 @@
+package gwm_app
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+const ErrorMetaFieldHttpStatus = "httpStatus"
+
+type Error struct {
+	Err  error
+	Meta map[string]any
+}
+
+func (e Error) Error() string {
+	return e.Err.Error()
+}
+
+func (e Error) GinError() *gin.Error {
+	return &gin.Error{
+		Err:  e.Err,
+		Type: gin.ErrorTypePublic,
+		Meta: e.Meta,
+	}
+}
+
+func NewError(err error, httpStatus int, meta map[string]any) Error {
+	if meta == nil {
+		meta = make(map[string]any)
+	}
+	meta[ErrorMetaFieldHttpStatus] = httpStatus
+	return Error{
+		Err:  err,
+		Meta: meta,
+	}
+}
+
+var ErrUnauthorized = NewError(errors.New("unauthorized"), http.StatusUnauthorized, nil)
+
+func NewNotFoundError(target, by string) Error {
+	meta := map[string]any{}
+	if target != "" {
+		meta["target"] = target
+	}
+	if by != "" {
+		meta["by"] = by
+	}
+	return NewError(errors.New("not found"), http.StatusNotFound, meta)
+}
+
+func NewForbiddenError(reason string) Error {
+	meta := map[string]any{
+		"reason": reason,
+	}
+	return NewError(errors.New("forbidden"), http.StatusForbidden, meta)
+}
+
+func NewBadRequestError(reason string) Error {
+	meta := map[string]any{
+		"reason": reason,
+	}
+	return NewError(errors.New("bad request"), http.StatusBadRequest, meta)
+}

clients/gorm/db.go

@@ -0,0 +1,56 @@
+package gwm_gorm
+
+import (
+	"fmt"
+	"sync"
+
+	gwm_app "github.com/slhmy/go-webmods/app"
+	"github.com/slhmy/go-webmods/internal"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+var (
+	initMutx sync.Mutex
+	db       *gorm.DB
+)
+
+func GetDB() *gorm.DB {
+	if db == nil {
+		initMutx.Lock()
+		defer initMutx.Unlock()
+		if db != nil {
+			return db
+		}
+
+		driver := gwm_app.Config().GetString(internal.ConfigKeyDatabaseDriver)
+		switch driver {
+		case "postgres":
+			db, err := openPostgres()
+			if err != nil {
+				panic(err)
+			}
+			return db
+		default:
+			panic(fmt.Sprintf("unsupported database driver: %s", driver))
+		}
+	}
+	return db
+}
+
+func openPostgres() (db *gorm.DB, err error) {
+	dsn := fmt.Sprintf(
+		"host=%s port=%s user=%s dbname=%s password=%s sslmode=%s",
+		gwm_app.Config().GetString(internal.ConfigKeyDatabaseHost),
+		gwm_app.Config().GetString(internal.ConfigKeyDatabasePort),
+		gwm_app.Config().GetString(internal.ConfigKeyDatabaseUsername),
+		gwm_app.Config().GetString(internal.ConfigKeyDatabaseName),
+		gwm_app.Config().GetString(internal.ConfigKeyDatabasePassword),
+		gwm_app.Config().GetString(internal.ConfigKeyDatabaseSSLMode),
+	)
+	db, err = gorm.Open(postgres.Open(dsn))
+	if err != nil {
+		return nil, err
+	}
+	return db, nil
+}

clients/redis/rdb.go

@@ -0,0 +1,43 @@
+package gwm_redis
+
+import (
+	"sync"
+
+	"github.com/redis/go-redis/v9"
+	gwm_app "github.com/slhmy/go-webmods/app"
+	"github.com/slhmy/go-webmods/internal"
+)
+
+var (
+	rdbInitMutex sync.Mutex
+	rdbClient    redis.UniversalClient
+)
+
+func GetRDB() redis.UniversalClient {
+	if rdbClient == nil {
+		rdbInitMutex.Lock()
+		defer rdbInitMutex.Unlock()
+		if rdbClient != nil {
+			return rdbClient
+		}
+
+		addrs := gwm_app.Config().GetStringSlice(internal.ConfigKeyRedisAddrs)
+		password := gwm_app.Config().GetString(internal.ConfigKeyRedisPassword)
+		if len(addrs) == 0 {
+			panic("No redis hosts configured")
+		}
+		if len(addrs) == 1 {
+			rdbClient = redis.NewClient(&redis.Options{
+				Addr:     addrs[0],
+				Password: password,
+			})
+		}
+		if len(addrs) > 1 {
+			rdbClient = redis.NewClusterClient(&redis.ClusterOptions{
+				Addrs:    addrs,
+				Password: password,
+			})
+		}
+	}
+	return rdbClient
+}

doc/.gitignore

@@ -0,0 +1 @@
+book

doc/book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["slhmy"]
+language = "en"
+src = "src"
+title = "Golang Web Modules"

doc/src/SUMMARY.md

@@ -0,0 +1,12 @@
+<!-- markdownlint-enable MD025 -->
+
+# Summary
+
+# Application Core
+
+- [Config](app/config.md)
+- [Service Error](app/service_error.md)
+
+# Utilities
+
+- [Gin Error Handler](utils/gin/error_handler.md)

doc/src/app/config.md

@@ -0,0 +1,28 @@
+# Config
+
+Read configuration from config files or environment variables.
+
+Config namings are recommended to be in snake_case and separated by dots.
+
+You can set configs in `conifg` file and override them in `override` file
+(multiple file extensions are supported, such as `.yaml`, `.toml`, `.json`, etc.).
+
+In some cases, using environment variables is more convenient.
+You can override the final config by making every character uppercase and replacing `.` with `_`
+(e.g. `server.port` becomes `SERVER_PORT`),
+environment variables have the highest priority.
+
+## Example
+
+```go
+os.Setenv("SERVER_PORT", "443")
+port = gwm_app.Config().GetInt("server.port")
+// port = 443
+```
+
+## Customize
+
+Customize the config file path by setting the `GWM_RELATIVE_CONFIG_PATH` environment variable.
+Set the override config file name by setting the `GWM_OVERRIDE_CONFIG_NAME` environment variable.
+
+The following environment variables should be set before running the application.

doc/src/app/service_error.md

@@ -0,0 +1 @@
+# Service Error

doc/src/utils/gin/error_handler.md

@@ -0,0 +1 @@
+# Gin Error Handler