Confetti Framework

About Confetti

Confetti is a lightweight web application framework that can be used in both monolithic and microservice environments. It has no external dependencies, making it perfect for microservices. On the other hand, it includes the core features you expect from a framework, so if you're familiar with monolithic frameworks like Laravel, you'll feel right at home. However, Confetti follows idiomatic Go principles and encourages best practices in Go development.

Get Started

To start your Confetti application, use the following command:

go run cmd/api/main.go api:serve

This will start the API server and make your routes available.

File Structure

• cmd: Contains application commands.
• internal: Includes files used only within the directory.
• external: Can be used throughout the entire application.
• config: Stores configuration files.
• test: Contains feature and HTTP tests. Unit tests are located next to the tested files.

Features

Confetti provides multiple features to serve as the foundation of your application:

• App Server with Web Routing
• Middlewares
• Error Handling
• Custom Commands
• Configuration

App Server with Web Routing

You can define routes in cmd/api/command/api_serve_command.go:

var ApiRoutes = []handler.Route{
	handler.New("GET /ping", ping.Index),
	handler.New("GET /status", status.Index).AppendMiddleware(middleware.AuthMiddleware{Permission: "Show status"}),
}

Example Controller:

package status

import (
	"net/http"
	"src/internal/pkg/handler"
)

// Index returns the status of the application
func Index(response http.ResponseWriter, req *http.Request) error {
	data := make(map[string]any)
	data["status"] = "active"

	return handler.ToJson(response, data, http.StatusOK)
}

Middlewares

You can register middlewares like this:

handler.New("GET /status", status.Index).AppendMiddleware(middleware.AuthMiddleware{Permission: "Show status"})

In this example, middleware.AuthMiddleware with the Permission parameter is just an example. You can modify it according to your needs.

Middleware Example:

package middleware

import (
	"net/http"
	"src/internal/pkg/handler"
)

type AuthMiddleware struct {
	Permission string
}

func (a AuthMiddleware) Handle(next handler.Controller) handler.Controller {
	return func(w http.ResponseWriter, req *http.Request) error {
		// Perform actions before the request, e.g., checking user permissions
		err := next(w, req)
		// Perform actions after the request, e.g., logging the response status
		return err
	}
}

Error Handling

In internal/pkg/handler/error.go, you can define a uniform error response.

For system errors:

err := handler.NewSystemError(err, "psp_connection")

This returns only a reference to the error report instead of exposing detailed error information.

For user errors:

err := handler.NewUserError("Field name is required", 422)

This provides a structured response containing the error message.

You can modify handler.apiErrorHandler to, for example, send system errors to an external error-tracking provider instead of stderr.

Custom Commands

You can create your own commands. Two commands already exist. The easiest way is to copy cmd/api/command/route_list_command.go and modify it.

Register your command in cmd/api/main.go:

var commands = []Command{
	command.ApiRouteList{},
	command.AppServe{},
	// Add your custom commands here
}

Command Example:

package command

import (
	"fmt"
	"src/internal/pkg/handler"
)

type ApiRouteList struct {}

func (s ApiRouteList) Name() string {
	return "api:route_list"
}

func (s ApiRouteList) Description() string {
	return "Show a list of all API HTTP endpoints"
}

func (s ApiRouteList) Handle() error {
	fmt.Printf("\u001B[32mAll API endpoints:\u001B[0m\n")

	endpoints := handler.AppendApiByPath(ApiRoutes)
	for _, endpoint := range endpoints {
		fmt.Printf("%s\n", endpoint.Pattern)
	}

	return nil
}

Configuration

package config

var Features = struct {
	ShowHeader bool
}{
	ShowHeader: true,
}

Set the ShowHeader config by environment

package config

var Features = struct {
	ShowHeader bool
}{
	ShowHeader: os.Getenv("SHOW_HEADER") == "true",
}

You can use it like this:

if config.Features.ShowTest {
	// Your logic here
}

Contributing

We welcome contributions! However, to keep Confetti simple and lightweight, small features should be minimal in complexity. Large feature additions are welcome but may not be merged into the core framework. Instead, we will link to your pull request or external repository in the Features section.

How to Contribute

1. Fork the repository.
2. Create a new branch: git checkout -b feature-name.
3. Implement your feature or fix.
4. Write tests if necessary.
5. Run tests to ensure everything works: go test ./...
6. Submit a pull request with a clear description.

Thank you for helping improve Confetti!

License

Confetti Framework is open-source software licensed under the MIT License.