Random

A tiny Go web service that generates secure random strings via HTML and JSON endpoints. The service runs locally, in Docker, or on AWS Lambda via the aws-lambda-go-api-proxy adapters.

Table of Contents

• Overview
• Features
• Quick Start
• Deployment
• Configuration
• API Endpoints
• Development
• Build Metadata
• Links

Overview

random ships a minimal UI at / and a JSON API at /json. Both endpoints generate two strings on every request:

• Printable String: Alphanumeric with 1–3 substitutions from !#$%*+-=?@^_
• Alphanumeric String: Letters and digits only

Query parameters let callers control the length of each string while the server clamps values to the safe range of 1–99 characters.

✨ Features

• 🚀 Live Web UI – Interactive page updates strings instantly as you tweak lengths
• 🎯 JSON API – Simple GET /json endpoint for programmatic clients
• 📏 Length Clamping – Prevents invalid values and enforces 1–99 character range
• 🔄 Cache Busting – Build metadata injected into static assets for fresh browser loads
• ☁️ Lambda Ready – Auto-detects AWS_LAMBDA_FUNCTION_NAME and runs behind API Gateway with zero code changes
• 🔬 Tested – Unit tests cover string generation, HTML rendering, and Lambda adapters

🚀 Quick Start

Run with Go

Requires Go 1.23+.

git clone https://github.com/johnwmail/random.git
cd random
go run ./...
# or build a binary
go build -o random .
./random

Visit http://localhost:8080 for the UI or call http://localhost:8080/json?p=20&a=25 for JSON.

Quick API Examples

# Printable=33, Alphanumeric=22
curl -fsS "http://localhost:8080/json?p=33&a=22"

# Open the UI (macOS)
open http://localhost:8080/

☁️ Deployment

Docker

docker build -t random:local -f docker/Dockerfile .
docker run --rm -p 8080:8080 --name random random:local

Using Compose:

docker compose -f docker/docker-compose.yml up --build

AWS Lambda

The app switches to Lambda mode when AWS_LAMBDA_FUNCTION_NAME is present. The deploy-lambda.yml workflow builds a bootstrap binary and deploys it via the custom runtime.

Key environment values for deployment:

Secret/Var	Purpose
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	Authentication for CI deployments
AWS_REGION	Target region
LAMBDA_FUNCTION_NAME	Lambda function to update

The workflow produces a zip archive in lambda-artifacts/ and publishes a new version.

⚙️ Configuration

The service intentionally keeps configuration surface area small. Important knobs:

Option	Description
Query p	Printable string length (default random 12–30)
Query a	Alphanumeric string length (default random 12–30)
Env PORT	Port for the web server to listen on (default 8080)
Env AWS_LAMBDA_FUNCTION_NAME	Enables Lambda adapter mode

Values outside 1–99 are clamped automatically.

📋 API Endpoints

Method	Path	Description
GET	/	HTML UI with live length controls
GET	/json	JSON payload describing both strings

Note on CLI clients

By default the service will return JSON to programmatic or CLI clients (for example curl, wget, powershell, httpie, language HTTP libraries, etc.). This is detected using the User-Agent header. If you need to force HTML from a CLI client, request the / endpoint with an explicit Accept: text/html header or use a browser; to force JSON use /json or Accept: application/json.

Sample JSON response:

{
  "printable": {
    "length": 33,
    "string": "P7d*93g1..."
  },
  "alphanumeric": {
    "length": 22,
    "string": "dN7Z0tXy4Kq1..."
  }
}

🔧 Development

# Format, lint, and test
go fmt ./...
go vet ./...
golangci-lint run
go test ./...

# Run the service locally during development
go run ./...

The CI pipeline in .github/workflows/test.yml enforces the formatting, linting, and testing steps above.

🏷️ Build Metadata

main.go exposes three variables injected at build time:

Variable	Default	Purpose
Version	dev	Semantic version or git tag
BuildTime	unknown	Build timestamp (ISO 8601 recommended)
CommitHash	none	Git commit SHA

Inject values with Go build flags:

go build \
  -ldflags "-X main.Version=v1.2.3 -X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.CommitHash=$(git rev-parse --short HEAD)" \
  -o random .

The values are printed on startup and wired into the HTML template for cache busting of static assets.

🔗 Links

• GitHub: https://github.com/johnwmail/random
• Issues: https://github.com/johnwmail/random/issues
• Actions: https://github.com/johnwmail/random/actions

---

⭐ Star the project if this random string generator helps you out!