photon

README

Photon

Photon is a lightweight and extensible backend framework for Go. Built with a modular, adapter-based architecture, Photon enables developers to create robust HTTP and WebSocket applications with clarity and flexibility.

---

✨ Features

• Modular Adapters: Seamlessly switch between HTTP and WebSocket backends (e.g., Echo, Melody).
• Plug-and-Play Architecture: Easy integration of custom adapters.
• Minimalistic Core: No hidden magic — full transparency and maintainability.

---

🚀 Installation

go get github.com/smtdfc/photon
go install github.com/smtdfc/photon-cli

---

⚙️ Getting Started

1. Create a new Echo-based Photon app

go mod init example.com/hello
photon gen app hello

2. Generate a module

photon gen module hello

3. Define your module routes

In internal/hello/init.go:

package hello

func (m *HelloModule) InitRoute() {
    m.Module.Route("GET", "/hello", m.Handler.Hello)
}

In internal/hello/handler.go:

package hello

import "github.com/smtdfc/photon"

type HelloModuleHandler struct{}

func (h *HelloModuleHandler) Hello(req photon.Request, res photon.Response) {
    res.JSON(200, map[string]any{
        "message": "Hello World 🚀",
    })
}

Register the module in your app:

package app

import (
    "github.com/smtdfc/photon"
    "example.com/hello/internal/hello"
)

func InitModule(app *photon.App) {
    hello.Init(app)
}

4. Run the app

go run .

Access it at: http://127.0.0.1:3000/hello

---

🔌 Custom Adapter Development

Photon adapters must implement the following interfaces:

BaseHTTPAdapter

type BaseHTTPAdapter interface {
    GetName() string
    Init() error
    Start() error
    Listen(port string) error
    UseSocket(path string, socketAdapter BaseSocketAdapter) error
    Route(method string, path string, handler RouteHandler)
}

BaseSocketAdapter

type BaseSocketAdapter interface {
    GetName() string
    Init() error
    Start() error
    On(event string, handler SocketEventHandler)
    Emit(event string, data []byte) error
    Stop() error
    HTTPHandler() func(http.ResponseWriter, *http.Request)
}

---

📆 Ecosystem

• 🔗 Echo Adapter
• 🔗 Melody Adapter
• 🛠️ Photon CLI

---

📜 License

Photon is licensed under the MIT License. © 2025 smtdfc

Documentation

Index

• type AdapterManager
  • func (m *AdapterManager) EsureAdapter(adapterType string)
  • func (m *AdapterManager) UseHttpAdapter(adapter BaseHTTPAdapter)
  • func (m *AdapterManager) UseSocketAdapter(adapter BaseSocketAdapter)
• type App
  • func NewApp() *App
  • func (a *App) Start(port string) error
• type BaseHTTPAdapter
• type BaseSocketAdapter
• type HttpController
  • func InitHttpController(app *App, module *Module) *HttpController
  • func (m *HttpController) Route(method string, path string, handler RouteHandler) *Route
  • func (m *HttpController) RouteSocket(path string) error
• type Module
  • func NewModule(name string, app *App) *Module
• type Request
• type Response
• type Route
• type RouteHandler
• type SocketController
  • func InitSocketController(app *App, module *Module) *SocketController
  • func (c *SocketController) On(event string, handler SocketEventHandler)
• type SocketEventHandler
• type SocketEventMessage
• type SocketRoom
  • func (r *SocketRoom) Emit(client *SocketSession, msg *SocketEventMessage) error
  • func (r *SocketRoom) EmitAll(msg *SocketEventMessage) error
  • func (r *SocketRoom) HasClient(clientID string) bool
• type SocketSession

Types

type AdapterManager

type AdapterManager struct {
	App           *App
	HttpAdapter   BaseHTTPAdapter
	SocketAdapter BaseSocketAdapter
}

func (*AdapterManager) EsureAdapter

func (m *AdapterManager) EsureAdapter(adapterType string)

func (*AdapterManager) UseHttpAdapter

func (m *AdapterManager) UseHttpAdapter(adapter BaseHTTPAdapter)

func (*AdapterManager) UseSocketAdapter

func (m *AdapterManager) UseSocketAdapter(adapter BaseSocketAdapter)

type App

type App struct {
	Adapter       *AdapterManager
	HttpAdapter   BaseHTTPAdapter
	SocketAdapter BaseSocketAdapter
}

func NewApp

func NewApp() *App

func (*App) Start

func (a *App) Start(port string) error

type BaseHTTPAdapter

type BaseHTTPAdapter interface {
	GetInstance() any
	SetApp(app *App) error
	GetName() string
	Init() error
	Start() error
	Listen(port string) error
	UseSocket(path string) error
	Route(method string, path string, handler RouteHandler)
}

type BaseSocketAdapter

type BaseSocketAdapter interface {
	GetName() string
	Init() error
	Start() error
	GetRoom(id string) *SocketRoom
	CreateRoom(id string) (*SocketRoom, error)
	JoinRoom(id string, client *SocketSession) error
	On(event string, handler SocketEventHandler)
	Emit(client *SocketSession, message *SocketEventMessage) error
	Stop() error
	HTTPHandler() func(http.ResponseWriter, *http.Request)
}

type HttpController

type HttpController struct {
	App    *App
	Module *Module
	Routes map[string]*Route
}

func InitHttpController

func InitHttpController(app *App, module *Module) *HttpController

func (*HttpController) Route

func (m *HttpController) Route(method string, path string, handler RouteHandler) *Route

func (*HttpController) RouteSocket

func (m *HttpController) RouteSocket(path string) error

type Module

type Module struct {
	Name    string
	Prefix  string
	App     *App
	Adapter *AdapterManager
}

func NewModule

func NewModule(name string, app *App) *Module

type Request

type Request interface {
	GetHeader(name string) string
	GetCookie(name string) (string, error)
	GetIP() string

	GetQuery(key string) string
	GetParam(key string) string
	GetFormValue(key string) string
	GetBody() ([]byte, error)

	Method() string
	Path() string
	Host() string
	URL() string
	ContentType() string

	BindJSON(obj interface{}) error
	BindForm(obj interface{}) error
	BindQuery(obj interface{}) error

	Context() any
	FormFile(name string) (any, error)
}

type Response

type Response interface {
	SetHeader(name string, value string)
	SetStatus(code int)
	SetCookie(name string, value string, path string, maxAge int)

	JSON(code int, obj interface{}) error
	Text(code int, msg string) error
	HTML(code int, html string) error
	Blob(code int, contentType string, data []byte) error

	Redirect(code int, url string) error
	SendFile(filePath string) error

	Writer() any
}

type Route

type Route struct {
	Module  *Module
	Path    string
	Method  string
	Handler RouteHandler
}

type RouteHandler

type RouteHandler func(req Request, res Response)

type SocketController

type SocketController struct {
	App           *App
	Module        *Module
	SocketAdapter BaseSocketAdapter
}

func InitSocketController

func InitSocketController(app *App, module *Module) *SocketController

func (*SocketController) On

func (c *SocketController) On(event string, handler SocketEventHandler)

type SocketEventHandler

type SocketEventHandler func(client *SocketSession, msg *SocketEventMessage)

type SocketEventMessage

type SocketEventMessage struct {
	Event string      `json:"event"`
	Data  interface{} `json:"data"`
}

type SocketRoom

type SocketRoom struct {
	Adapter BaseSocketAdapter
	RoomID  string
	Data    map[string]any
	Clients map[string]*SocketSession
}

func (*SocketRoom) Emit

func (r *SocketRoom) Emit(client *SocketSession, msg *SocketEventMessage) error

func (*SocketRoom) EmitAll

func (r *SocketRoom) EmitAll(msg *SocketEventMessage) error

func (*SocketRoom) HasClient

func (r *SocketRoom) HasClient(clientID string) bool

type SocketSession

type SocketSession struct {
	ClientID string
	Data     map[string]any
	Instance any
}