feat: implement secure file upload API with strict size limits and tests

- Add a Gin-based file upload server with strict 1MB upload limit enforced by http.MaxBytesReader and custom error responses
- Include unit and integration tests for valid upload, oversized file rejection, and missing file cases
- Provide documentation explaining setup, API usage, error handling, testing, and how to modify the upload size limit

Signed-off-by: appleboy <[email protected]>

Author: appleboy

upload-limit-bytes/README.md

@@ -0,0 +1,74 @@
+# Gin Example: Restrict File Upload Size with http.MaxBytesReader
+
+This example demonstrates how to use [Gin](https://github.com/gin-gonic/gin) and Go's `http.MaxBytesReader` to strictly limit uploaded file size and return custom error messages when the size limit is exceeded.
+
+## Features
+
+- REST API - POST `/upload` endpoint for file upload.
+- Server-side enforcement of maximum file size (default: **1MB**).
+- Immediate error response (`413 Request Entity Too Large` with custom JSON) when file is too large.
+- Well-commented code for clarity.
+- Unit + integration tests verifying successful uploads, oversized file rejection, and edge cases.
+
+## How It Works
+
+- The core implementation wraps the incoming request body using Go's [`http.MaxBytesReader`](https://pkg.go.dev/net/http#MaxBytesReader), which limits how many bytes the server will read.
+- If a client uploads a file exceeding this limit, parsing fails and Gin responds with a **custom error message**.
+- See [`main.go`](./main.go) for details and comments.
+
+## API Usage
+
+### Start the server
+
+```bash
+go run main.go
+```
+
+Server listens on port **8080**.
+
+### Upload a file
+
+**cURL valid file (within 1MB):**
+
+```bash
+curl -F "[email protected]" http://localhost:8080/upload
+# Response: {"message":"upload successful"}
+```
+
+**cURL oversized file (e.g., 2MB):**
+
+```bash
+curl -F "[email protected]" http://localhost:8080/upload
+# Response: {"error":"file too large (max: 1048576 bytes)"}
+```
+
+### Error cases
+
+- Missing file: `{"error":"file form required"}` (status 400)  
+- File too large: `{"error":"file too large (max: 1048576 bytes)"}` (status 413)
+
+## Testing
+
+This example includes unit/integration tests in [`main_test.go`](./main_test.go):
+
+```bash
+go test
+```
+
+- **TestUploadWithinLimit**: uploads a file under the limit, expects success.
+- **TestUploadOverLimit**: uploads a file over the limit, expects a custom error.
+- **TestUploadMissingFile**: no file uploaded, expects validation error.
+
+## Code Reference
+
+- [`main.go`](./main.go): Gin server setup, upload handler with file size enforcement.
+- [`main_test.go`](./main_test.go): Contains all unit and integration tests.
+
+## Modify the Limit
+
+Change `MaxUploadSize` constant in [`main.go`](./main.go) and [`main_test.go`](./main_test.go) to test other limits.
+
+---
+
+**License:** MIT  
+**Author:** Gin Example Contributors

upload-limit-bytes/main.go

@@ -0,0 +1,65 @@
+// upload-limit-bytes/main.go
+// Example: Restrict file upload size using Gin + http.MaxBytesReader
+//
+// This example shows how to use Gin together with http.MaxBytesReader to safely and *strictly*
+// limit the maximum size of uploaded files. It returns a custom error message if the file is too large.
+
+package main
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	MaxUploadSize = 1 << 20 // 1MB (can set to other sizes; used for tests and demos)
+)
+
+func uploadHandler(c *gin.Context) {
+	// Wrap the body reader so only MaxUploadSize bytes are allowed
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, MaxUploadSize)
+
+	// Parse multipart form (limit maxMemory for demonstration, not for size restriction)
+	if err := c.Request.ParseMultipartForm(MaxUploadSize); err != nil {
+		// Check for *http.MaxBytesError for upload size limit exceeded (portable way)
+		if _, ok := err.(*http.MaxBytesError); ok {
+			c.JSON(http.StatusRequestEntityTooLarge, gin.H{
+				"error": fmt.Sprintf("file too large (max: %d bytes)", MaxUploadSize),
+			})
+			return
+		}
+		// Other form errors
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Get uploaded file; parameter name is "file"
+	file, _, err := c.Request.FormFile("file")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "file form required"})
+		return
+	}
+
+	defer file.Close()
+	// For demonstration we ignore saving the file, but could copy to disk or buffer
+	// _, err = io.Copy(io.Discard, file) // Uncomment if you want to read all bytes
+
+	c.JSON(http.StatusOK, gin.H{
+		"message": "upload successful",
+	})
+}
+
+// setupRouter creates and returns the Gin router
+func setupRouter() *gin.Engine {
+	r := gin.Default()
+	r.POST("/upload", uploadHandler)
+	return r
+}
+
+func main() {
+	r := setupRouter()
+	// Run Gin server on :8080
+	r.Run(":8080")
+}

upload-limit-bytes/main_test.go

@@ -0,0 +1,81 @@
+// upload-limit-bytes/main_test.go
+// Unit & integration tests for Gin file upload with http.MaxBytesReader limit
+
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// Use setupRouter and uploadHandler from the main package.
+// (Removed local setupRouter to avoid redeclaration; tests use main's setupRouter().)
+
+// Helper: create multipart body with given size
+func createMultipartBody(fieldName string, size int) (contentType string, bodyBytes []byte) {
+	var b bytes.Buffer
+	w := multipart.NewWriter(&b)
+	fw, _ := w.CreateFormFile(fieldName, "test.bin")
+	io.CopyN(fw, bytes.NewReader(make([]byte, size)), int64(size)) // Write 'size' bytes
+	w.Close()
+	return w.FormDataContentType(), b.Bytes()
+}
+
+func TestUploadWithinLimit(t *testing.T) {
+	router := setupRouter()
+	// Prepare file just under max size
+	// Reduce file size so the total request (including multipart headers/overhead) is safely below the limit.
+	contentType, body := createMultipartBody("file", MaxUploadSize-10*1024)
+	req, _ := http.NewRequest("POST", "/upload", bytes.NewReader(body))
+	req.Header.Set("Content-Type", contentType)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	require.Equal(t, http.StatusOK, resp.Code)
+	var result map[string]string
+	err := json.Unmarshal(resp.Body.Bytes(), &result)
+	require.NoError(t, err)
+	require.Equal(t, "upload successful", result["message"])
+}
+
+func TestUploadOverLimit(t *testing.T) {
+	router := setupRouter()
+	contentType, body := createMultipartBody("file", MaxUploadSize+100)
+	req, _ := http.NewRequest("POST", "/upload", bytes.NewReader(body))
+	req.Header.Set("Content-Type", contentType)
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	require.Equal(t, http.StatusRequestEntityTooLarge, resp.Code)
+	var result map[string]string
+	err := json.Unmarshal(resp.Body.Bytes(), &result)
+	require.NoError(t, err)
+	require.Contains(t, result["error"], "file too large")
+}
+
+func TestUploadMissingFile(t *testing.T) {
+	router := setupRouter()
+	var b bytes.Buffer
+	w := multipart.NewWriter(&b)
+	w.Close()
+	req, _ := http.NewRequest("POST", "/upload", &b)
+	req.Header.Set("Content-Type", w.FormDataContentType())
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+
+	require.Equal(t, http.StatusBadRequest, resp.Code)
+	var result map[string]string
+	err := json.Unmarshal(resp.Body.Bytes(), &result)
+	require.NoError(t, err)
+	require.Contains(t, result["error"], "file form required")
+}