photon

Photon

Photon is a lightweight Go service toolkit for building production backends without rebuilding the same infrastructure plumbing in every service.

It gives teams a common foundation for HTTP and gRPC services, configuration, logging, telemetry, storage clients, cloud integrations, middleware, background workers, caching, and resilience utilities. The goal is not to hide Go behind a heavy framework. The goal is to keep normal Go code simple, observable, and consistent across services.

What Photon Is Good For

• Standardizing how Go services start, validate config, expose APIs, shut down, and emit telemetry.
• Reusing proven wrappers for storage, cache, cloud, notification, auth, and session concerns.
• Building services that need request middleware, retries, rate limits, background workers, and operational guardrails.
• Keeping business logic free from repeated setup code while still allowing direct use of normal Go libraries.

Capability Map

Install

Photon targets modern Go and currently declares:

go 1.27.1

Install it with:

go get github.com/cshekharsharma/photon

If the repository is private, configure GOPRIVATE for your environment before running go get.

go env -w GOPRIVATE=github.com/cshekharsharma/*

Quick Start

package main

import (
	"net/http"
	"time"

	"github.com/cshekharsharma/photon/core/router"
	server "github.com/cshekharsharma/photon/server/http"
)

func main() {
	server.StartHttpServer(&server.ServerConfig{
		ServerPort:    8080,
		ReadTimeout:   5 * time.Second,
		WriteTimeout:  10 * time.Second,
		IdleTimeout:   120 * time.Second,
		RouteProvider: router.RouterCHI,
		HttpRoutes: []*server.HttpRoute{
			{
				UrlRoute:      "/health",
				RequestMethod: http.MethodGet,
				HttpHandler: func(w http.ResponseWriter, r *http.Request) {
					w.WriteHeader(http.StatusOK)
				},
			},
		},
	})
}

For more examples, see docs/examples.

License

Photon is released under the Apache License 2.0.

Production Defaults

Photon is designed around explicit validation and safe defaults:

• Config, HTTP server, Mongo, Postgres, notifier, and worker options validate early.
• Default HTTP timeouts are applied when unset.
• CORS rejects wildcard origins when credentials are enabled.
• Mongo and Postgres wrappers avoid mutating caller-owned config while normalizing defaults.
• Worker overseer supports context shutdown, bounded restart policy, lifecycle hooks, and status snapshots.
• Notification publishing supports validation, audit hooks, and FIFO dedupe when the queue client supports it.

See Production Readiness for the release checklist.

Development

make tools
make configure
make test
make testcoverage

Useful checks before a release:

go test ./...
go vet ./...
staticcheck ./...
golangci-lint run ./...
govulncheck ./...
go test -race ./cloud ./cloud/providers ./cloud/service/aws ./core/logger ./telemetry ./coordination/network/discovery ./coordination/network/watcher ./middleware ./server/grpc/server ./server/http ./storage/aerospike ./storage/memcached ./storage/elasticsearch ./storage/mongo ./storage/mysql ./storage/redis ./utils/rest ./notifier/notifyrclient ./workers

Contributing

Contributions should be small, tested, and easy to review.

• Branch from main.
• Keep public APIs backward-compatible unless the change is intentionally breaking.
• Add focused tests for new behavior and failure paths.
• Run formatting, linting, tests, race tests where relevant, and vulnerability checks.
• Update docs when behavior, configuration, or operational expectations change.

Security

Please do not open public issues for suspected vulnerabilities. Follow the process in SECURITY.md.