petname

A lightweight HTTP service that generates human-readable random names for hosts, containers, and temporary resources. The service runs on Google Cloud Run and serves names generated by dustinkirkland/golang-petname.

A live instance is available at https://petname.proto-hype.net.

API Usage

Send an HTTP GET request to the root endpoint (/). The service responds with a plaintext string formatted with Content-Type: text/plain.

Query Parameters

Parameter	Type	Default	Description
words	integer	2	Number of words to include in the generated name. Must be greater than 0.
separator	string	-	Delimiter placed between generated words.

Examples

Generate a default two-word hyphen-separated name:

curl -s https://petname.proto-hype.net

Example response:

super-ferret

Generate a four-word name:

curl -s "https://petname.proto-hype.net?words=4"

Example response:

wildly-pro-super-ferret

Generate a name using an underscore delimiter:

curl -s "https://petname.proto-hype.net?separator=_"

Example response:

super_ferret

Combine word count and delimiter overrides:

curl -s "https://petname.proto-hype.net?words=3&separator=."

Example response:

pro.super.ferret

Local Development

Prerequisites:

• Go 1.25 or newer
• Docker (optional, for container builds)
• Task (optional, for task automation)

Running Locally

Run the server directly with the Go toolchain:

go run main.go

The server binds to port 8080 by default. Override the listen port by setting the PORT environment variable:

PORT=9090 go run main.go

Building the Container

Build the container image using the multi-stage Dockerfile:

docker build -t petname .
docker run -p 8080:8080 petname

Deployment

The project configures deployment to Google Cloud Run via Taskfile.yaml.

Configuration

Create a .env file in the project root with your Google Cloud deployment values:

PROJECT_ID=your-gcp-project-id
REGION=us-east4
DOMAIN=proto-hype.net

Available Tasks

Run task --list to view all defined commands:

• task login: Authenticates Google Cloud CLI (gcloud) and configures default project and compute regions.
• task setup: Enables the required Google Cloud APIs (run.googleapis.com, cloudbuild.googleapis.com, artifactregistry.googleapis.com).
• task deploy: Builds the source code with Google Cloud Build and deploys an unauthenticated Cloud Run service.
• task map-domain: Creates a custom domain mapping for <SERVICE_NAME>.<DOMAIN>.
• task logs: Streams real-time service logs from Cloud Run.
• task test: Executes test requests against the mapped domain endpoint.

License

This project is licensed under the MIT License. See LICENSE for details.