fix: initial checkin

Author: sattvikc

.github/workflows/go-test.yml

@@ -0,0 +1,57 @@
+name: Go Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: Run Coverage Tests and update badge
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
+          fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
+
+      - name: Setup go
+        uses: actions/setup-go@v4
+        with:
+          go-version-file: "go.mod"
+
+      - name: Run Test
+        run: |
+          go test -coverpkg ./... -cover -coverprofile=coverage.out -v ./...
+          go tool cover -func=coverage.out -o=coverage.out
+
+      - name: Go Coverage Badge # Pass the `coverage.out` output to this action
+        uses: tj-actions/coverage-badge-go@v2
+        with:
+          filename: coverage.out
+
+      - name: Verify Changed files
+        uses: tj-actions/verify-changed-files@v16
+        id: verify-changed-files
+        with:
+          files: README.md
+
+      - name: Commit changes
+        if: steps.verify-changed-files.outputs.files_changed == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add README.md
+          git commit -m "chore: Updated coverage badge."
+
+      - name: Push changes
+        if: steps.verify-changed-files.outputs.files_changed == 'true'
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ github.token }}
+          branch: ${{ github.head_ref }}

.gitignore

@@ -0,0 +1,22 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+tmp/

CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+## [Unreleased]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sattvik Chakravarthy
+
+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.

Makefile

@@ -0,0 +1,6 @@
+test:
+	go test -v ./...
+
+test-coverage:
+	go test -coverpkg ./... -cover -coverprofile=coverage.out -v ./...
+	go tool cover -html=coverage.out

README.md

@@ -0,0 +1,126 @@
+# Kha - Simple yet powerful API framework for GO (with swagger spec generation)
+![Coverage](https://img.shields.io/badge/Coverage-91.6%25-brightgreen)
+
+A simplapie, developer-friendly API framework for Go, featuring automatic Swagger (OpenAPI) spec generation.
+
+## 🚀 Features
+
+- **Intuitive handler definitions** using Go structs
+- **Automatic request parsing** (JSON, form, multipart, etc.)
+- **Zero-boilerplate route registration** for all HTTP methods
+- **Instant Swagger docs** generated from your handlers
+
+## 🛠️ Quick Start
+
+**Create a new app**
+
+```go
+import "github.com/go-simpl/simplapi"
+
+func main() {
+    app := simplapi.New()
+
+    // Add routes
+
+    app.ListenAndServe(":8000")
+}
+```
+
+Swagger UI will be instantly available on `http://localhost:8000/try` and the swagger (OpenAPI) spec on `http://localhost:8000/openapi.json`
+
+**Adding routes**
+
+To add routes, call the appropriate methods on the app.
+
+```go
+app.GET(path, tags, handlers...)
+app.POST(path, tags, handlers...)
+app.PUT(path, tags, handlers...)
+// and so on
+```
+
+path: `string` - path to handle
+
+tags: `[]string` - swagger tags
+
+handlers: `[]interface{}` - functions that handle the request
+
+### Handler
+
+Handler function is the important building block that controls how the endpoints are processed and the specs are generated. The function should be of the following format:
+
+```go
+func HandlerFunc(input InputType) (*OutputType1, *OutputType2, error) {
+    // Handler code
+}
+```
+
+The function must return one of the output types or error. The function must, at the least, return error.
+
+Output type will be returned as `JSON` response by marshalling the struct.
+
+Additionally, if the Output type defines GetStatusCode function, that will be used to set the status of the response.
+
+If you provide multiple handler functions for a route, they are called one after another in the order you specify. Each handler is executed until one of them returns a non-nil output or an error. As soon as a handler returns a result (any non-nil output or error), the chain stops and no further handlers are called. If a handler returns only nil values, the next handler in the list will be executed.
+
+#### InputType definition
+
+Input for the API can be defined by struct field tags.
+
+**Query Params**
+
+```go
+type InputType struct {
+    PageNum int `query:"page_num"`
+    PageSize int `query:"page_size"`
+}
+```
+
+**Path Params**
+
+```go
+// Assuming path is `/books/:book_id`
+type InputType struct {
+    BookId string `path:"book_id"`
+}
+```
+
+**Headers**
+
+```go
+type InputType struct {
+    ApiKey string `header:"X-API-Key"`
+}
+```
+
+**JSON Body**
+
+```go
+type InputType struct {
+    Body struct {
+        Title string `json:"title"`
+        // ... JSON fields here
+    } `body:"json"`
+}
+```
+
+**URL Encoded from**
+
+```go
+type InputType struct {
+    Form struct {
+        Email    string `form:"email"`
+        Password string `form:"password"`
+    } `body:"urlencoded"`
+}
+```
+
+**Multipart form**
+
+```go
+type InputType struct {
+    Form struct {
+        UploadedFile *multipart.FileHeader `form:"file"`
+    }
+}
+```

ROADMAP.md

@@ -0,0 +1,32 @@
+# Roadmap
+
+## Features
+
+- [ ] Shared context
+- [ ] Response Headers
+- [ ] Non-json responses
+- [ ] Middleware
+- [ ] Cookie as param injection
+- [ ] Response Cookies
+- [ ] Streaming responses
+
+## Framework support
+
+- [ ] Gin - https://github.com/gin-gonic/gin - 83k
+- [-] Fiber - https://github.com/gofiber/fiber - 37k
+- [ ] Beego - https://github.com/beego/beego - 32k
+- [ ] Echo - https://github.com/labstack/echo - 31k
+- [ ] go-zero - https://github.com/zeromicro/go-zero - 31k
+- [ ] go-kit - https://github.com/go-kit/kit - 27k
+- [ ] kratos - https://github.com/go-kratos/kratos - 24k
+- [ ] fasthttp - https://github.com/valyala/fasthttp - 22k
+- [ ] gorilla/mux - https://github.com/gorilla/mux - 21.5k
+- [ ] chi - https://github.com/go-chi/chi - 20k
+- [ ] httprouter - https://github.com/julienschmidt/httprouter - 17k
+- [ ] http (built-in)
+
+Reference: https://github.com/mingrammer/go-web-framework-stars
+
+## Performance Benchmark
+
+- Refer: https://github.com/julienschmidt/go-http-routing-benchmark

app.go

@@ -0,0 +1,110 @@
+package simplapi
+
+import (
+	"github.com/go-simpl/simplapi/pkg/framework"
+	"github.com/go-simpl/simplapi/pkg/handler"
+	"github.com/go-simpl/simplapi/pkg/swagger"
+)
+
+type App struct {
+	framework   framework.Framework
+	swaggerJson map[string]interface{}
+}
+
+func New(frameworkName ...string) *App {
+	frameworkName = append(frameworkName, "fiber")
+
+	s := &App{
+		framework: framework.GetFramework(frameworkName[0]),
+		swaggerJson: map[string]interface{}{
+			"openapi": "3.0.0",
+			"info": map[string]interface{}{
+				"title":   "SimpleAPI",
+				"version": "1.0.0",
+			},
+			"paths": map[string]interface{}{},
+		},
+	}
+	addSwaggerRoutes(s)
+	return s
+}
+
+func (s *App) GetApp() framework.Framework {
+	return s.framework
+}
+
+func (s *App) ListenAndServe(addr string) error {
+	return s.framework.ListenAndServe(addr)
+}
+
+func (s *App) createHandler(handlers ...interface{}) framework.FrameworkHandler {
+	// Reverse the handlers slice
+	for i, j := 0, len(handlers)-1; i < j; i, j = i+1, j-1 {
+		handlers[i], handlers[j] = handlers[j], handlers[i]
+	}
+
+	var nextHandler framework.FrameworkHandler = nil
+	for _, h := range handlers {
+		nextHandler = handler.WrapHandler(h, nextHandler)
+	}
+
+	return nextHandler
+}
+
+func (s *App) GET(path string, tags []string, handlers ...interface{}) {
+	s.framework.GET(path, s.createHandler(handlers...))
+	s.addToSwagger(path, "get", handlers, tags)
+}
+
+func (s *App) POST(path string, tags []string, handlers ...interface{}) {
+	s.framework.POST(path, s.createHandler(handlers...))
+	s.addToSwagger(path, "post", handlers, tags)
+}
+
+func (s *App) PUT(path string, tags []string, handlers ...interface{}) {
+	s.framework.PUT(path, s.createHandler(handlers...))
+	s.addToSwagger(path, "put", handlers, tags)
+}
+
+func (s *App) PATCH(path string, tags []string, handlers ...interface{}) {
+	s.framework.PATCH(path, s.createHandler(handlers...))
+	s.addToSwagger(path, "patch", handlers, tags)
+}
+
+func (s *App) DELETE(path string, tags []string, handlers ...interface{}) {
+	s.framework.DELETE(path, s.createHandler(handlers...))
+	s.addToSwagger(path, "delete", handlers, tags)
+}
+
+func (s *App) addToSwagger(path string, method string, handlers []interface{}, tags []string) {
+	if path == "/try" || path == "/openapi.json" {
+		return
+	}
+
+	definition := map[string]interface{}{
+		"parameters": []interface{}{},
+		"responses":  map[string]interface{}{},
+		"tags":       tags,
+	}
+
+	if method != "get" {
+		definition["requestBody"] = map[string]interface{}{}
+	}
+
+	for _, handler := range handlers {
+		swagger.UpdateDefinitionUsingHandler(definition, handler)
+	}
+
+	if _, ok := s.swaggerJson["paths"].(map[string]interface{})[path]; !ok {
+		s.swaggerJson["paths"].(map[string]interface{})[path] = map[string]interface{}{}
+	}
+
+	if _, ok := s.swaggerJson["paths"].(map[string]interface{})[path].(map[string]interface{})[method]; !ok {
+		s.swaggerJson["paths"].(map[string]interface{})[path].(map[string]interface{})[method] = definition
+	}
+
+	responses := definition["responses"].(map[string]interface{})
+	for _, handler := range handlers {
+		swagger.UpdateResponseDefinitionUsingHandler(responses, handler)
+	}
+}