Stratum

A high-performance, CDN-like caching layer for your databases. 🔥

---

Stratum is a highly-configurable, high-performance Go application that acts as a CDN-like layer for your databases. It allows you to expose specific data (like user avatars, configuration JSON, etc.) through custom API endpoints, with a powerful caching layer to protect your databases from excessive load.

🚀 Key Features

• ⚡ High Performance: Built with Go for speed and efficiency.
• 🔄 Dynamic Routes: Configure custom URL patterns for your data on the fly.
• 🏢 Multi-Project: Serve data for multiple, independent projects from a single Stratum instance.
• ⚙️ Environment-Driven: All configuration is managed via environment variables. No code changes needed to add or modify endpoints.
• 📦 Caching: Built-in support for Redis caching with configurable TTLs per route.
• ⚖️ Scalable: Designed to be stateless for easy horizontal scaling.
• ☁️ Cloud-Native: Ready for deployment on platforms like Docker and Google Cloud Run.

🤔 How It Works

The server reads its configuration from environment variables on startup. For each "project" it finds, it dynamically creates an HTTP endpoint. When a request hits an endpoint, Stratum performs the following steps:

Request ➡️ [Stratum Endpoint] ➡️ Cache Check ❓
                                    |
                                    ├─ Hit 🎯 ➡️ Serve from Cache ⚡
                                    |
                                    └─ Miss 🤷 ➡️ Query Database 💾 ➡️ Store in Cache 📦 ➡️ Serve Data 🚀

🏁 Getting Started

Prerequisites

• Go (version 1.21+ recommended)
• Redis
• A running database instance (e.g., PostgreSQL, MySQL)

Installation

1. Clone the repository:

   git clone https://github.com/PythonicVarun/Stratum.git
   cd Stratum

2. Install dependencies:

   go mod tidy

3. Create a configuration file: Copy the example .env file. This file will store your environment variables for local development.

   cp .env.example .env

☁️ Deployment

Stratum is designed for modern cloud environments. You can deploy it using Docker or directly to serverless platforms like Google Cloud Run.

Docker

A Dockerfile is included for easy containerization.

1. Build the image:

   docker build -t stratum-app .

2. Run the container: Make sure to pass your environment variables. You can do this with a .env file and the --env-file flag.

   docker run --env-file ./.env -p 8080:8080 stratum-app

Google Cloud Run

For a scalable, serverless deployment, you can use Google Cloud Run.

See the detailed deployment guide in google-cloud-deployment.md.

🛠️ Configuration

Configuration is managed entirely via environment variables, following the principles of a 12-factor app. For local development, you can set these in your .env file.

Server Configuration

Variable	Description	Default
SERVER_PORT	The port on which the server will run.	8080
REDIS_URL	The connection URL for Redis.	redis://localhost:6379/0
API_CLIENT_USER_AGENT	The User-Agent header for API sources.	Pythonic-Stratum-Client

Project Configuration

To add a new endpoint, you define a set of PROJECT_n_* variables, where n is a unique number for each project. Each project must have a PROJECT_n_SOURCE_TYPE, which can be either db or api.

Source Type: db

This is the default source type. It queries a database table to fetch the data.

Variable	Description	Example
PROJECT_n_SOURCE_TYPE	The source type for the project.	db
PROJECT_n_ROUTE	The URL pattern. Must contain a placeholder in curly braces, like {id}.	/users/{id}/profile
PROJECT_n_DB_DSN	The Data Source Name for the database connection.	user:pass@tcp(127.0.0.1:3306)/db
PROJECT_n_TABLE	The database table to query.	user_profiles
PROJECT_n_ID_COLUMN	The column for the WHERE clause. Must match the placeholder in ROUTE.	id
PROJECT_n_SERVE_COLUMN	The column whose data should be returned in the response body.	profile_json
PROJECT_n_CONTENT_TYPE	The Content-Type HTTP header for the response.	application/json
PROJECT_n_CACHE_TTL_SECONDS	The number of seconds to cache the response. Set to 0 to disable caching.	3600

Source Type: api

This source type fetches data from an external API endpoint.

Variable	Description	Example
PROJECT_n_SOURCE_TYPE	The source type for the project.	api
PROJECT_n_ROUTE	The URL pattern. Must contain a placeholder.	/users/{user_id}/avatar
PROJECT_n_API_ENDPOINT	The external API endpoint to call. The placeholder must match ROUTE.	http://example.com/api/avatars/{user_id}
PROJECT_n_ID_COLUMN	The name of the placeholder in ROUTE and API_ENDPOINT.	user_id
PROJECT_n_CONTENT_TYPE	The Content-Type HTTP header for the response.	image/png
PROJECT_n_CACHE_TTL_SECONDS	The number of seconds to cache the response. Set to 0 to disable caching.	300

API Authentication

Stratum supports authenticating with the external API. This is configured with the following variables:

Variable	Description	Example
PROJECT_n_API_AUTH_TYPE	The authentication type. Can be none, bearer, or header. Defaults to none.	bearer
PROJECT_n_API_AUTH_SECRET	The secret to use for authentication (e.g., an API key or Bearer token).	your-secret-api-key
PROJECT_n_API_AUTH_HEADER_NAME	The name of the HTTP header to use when API_AUTH_TYPE is header.	X-Api-Key

▶️ Running the Application

Once your .env file is configured, you can run the server:

go run ./cmd/Stratum

The server will start on the port specified by the SERVER_PORT environment variable.

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please read our CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

Made with ❤️ by Varun Agnihotri