https://github.com/alexfalkowski/status
An alternative to https://httpstat.us/.
https://github.com/alexfalkowski/status
cucumber golang make ruby
Last synced: 12 days ago
JSON representation
An alternative to https://httpstat.us/.
- Host: GitHub
- URL: https://github.com/alexfalkowski/status
- Owner: alexfalkowski
- License: mit
- Created: 2023-11-02T11:34:11.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2026-06-08T18:21:08.000Z (17 days ago)
- Last Synced: 2026-06-08T20:13:52.194Z (17 days ago)
- Topics: cucumber, golang, make, ruby
- Language: Go
- Homepage: https://alexfalkowski.github.io/status
- Size: 2.34 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://circleci.com/gh/alexfalkowski/status)
[](https://codecov.io/gh/alexfalkowski/status)
[](https://goreportcard.com/report/github.com/alexfalkowski/status)
[](https://pkg.go.dev/github.com/alexfalkowski/status)
[](https://masterminds.github.io/stability/active.html)
# 🩺 Status
`status` is a small Go service for testing HTTP status-code handling and health endpoints.
It is intended as a local, controllable alternative to depending on
from automated tests.
> [!NOTE]
> This service is built for test fixtures, smoke tests, and client behavior checks. It is not a general-purpose public status-code proxy.
## 🧭 Background
External status-code services are useful, but their availability can make an
otherwise deterministic test suite fail for reasons outside the project under
test. Running this service locally keeps status-code and observability checks
under your control.
## ⚡ Quick Start
After cloning the repository, initialize the shared `bin` submodule and install
dependencies:
```sh
git submodule update --init
make dep
```
Build and run the service with the local test configuration:
```sh
make build
./status server -i file:test/.config/server.yml
```
The local configuration binds the HTTP server to `localhost:11000`, so you can
try it with:
```sh
curl -i http://localhost:11000/v1/status/200
curl -i "http://localhost:11000/v1/status/503?sleep=50ms"
```
> [!IMPORTANT]
> The root `Makefile` includes files from the `bin` submodule. Run `git submodule update --init` before using `make` in a fresh checkout.
> [!TIP]
> If you have `air` installed, `make dev` builds and runs the server in watch mode with `test/.config/server.yml`.
## 🖥️ Server
### 🔢 Status Code
Returns the requested HTTP status code.
#### 📥 Request
```http
GET /v1/status/{code}
GET /v1/status/{code}?sleep=50ms
```
> [!NOTE]
> `code` must parse as an integer from `200` through `999`. Values below `200`, values above `999`, and non-numeric values return `400 Bad Request`.
| Parameter | Location | Required | Description |
| --------- | -------- | -------- | ----------- |
| `code` | Path | Yes | Status code to return. Named codes include their standard reason phrase, such as `200 OK`. |
| `sleep` | Query | No | Delay before returning the response. Parsed with Go's [`time.ParseDuration`](https://pkg.go.dev/time#ParseDuration), for example `50ms`, `1s`, or `2m`. Must be less than or equal to the effective `max_sleep`. |
> [!CAUTION]
> `sleep` intentionally delays the response. Keep durations short in tests so client timeouts and CI jobs do not wait longer than expected.
#### 📤 Response
The response status is the requested code and the body is plain text:
```http
200 OK
```
For codes without a standard reason phrase, the body contains the numeric code:
```http
999
```
Invalid status codes or invalid `sleep` values return `400 Bad Request`.
The maximum accepted sleep duration defaults to `5m`. Configure a lower maximum with:
```yaml
max_sleep: 2m
```
When set, `max_sleep` must be greater than `0` and less than or equal to `5m`.
## 💓 Health
The shared health module exposes health, liveness, readiness, and metrics
endpoints over HTTP:
| Endpoint | Check | Healthy response |
| -------- | ----- | ---------------- |
| `/healthz` | Online connectivity | `SERVING` |
| `/livez` | No-op liveness check | `SERVING` |
| `/readyz` | No-op readiness check | `SERVING` |
| `/metrics` | Prometheus metrics | Metrics including `go_info` |
> [!WARNING]
> `/healthz` uses the shared online health registration, which checks external internet connectivity by default. In an offline environment, prefer `/livez` or `/readyz` for local process checks.
Configure health check timing with:
```yaml
health:
duration: 1s
timeout: 1s
```
The repository's local configuration is in `test/.config/server.yml`.
## 🚢 Deployment
The service builds as a single binary and can also be built into a Docker image
through the shared make targets. In production-like environments, run it behind
your normal container orchestration and health-check configuration.
## 🛠️ Development
### 🧱 Structure
The project follows the common Go service layout:
| Path | Purpose |
| ---- | ------- |
| `main.go` | CLI bootstrap. |
| `internal/cmd/` | Server command registration and module wiring. |
| `internal/config/` | Application config layered on `github.com/alexfalkowski/go-service/v2/config`. |
| `internal/api/v1/transport/http/` | HTTP route registration for `/v1/status/{code}`. |
| `internal/health/` | Health registration and HTTP observers. |
| `test/` | Ruby nonnative/cucumber integration tests and benchmark harness. |
### 📦 Dependencies
Install these before running the full local workflow:
- Go `1.26.0`, as declared in `go.mod`.
- Ruby and Bundler for the `test/` harness.
- The `bin` submodule, initialized with `git submodule update --init`.
### 🧰 Commands
Prefer the exposed `make` targets from the repository root:
| Command | Purpose |
| ------- | ------- |
| `make help` | Show available commands. |
| `make dep` | Install Go and Ruby test dependencies. |
| `make build` | Build the release binary named `status`. |
| `make build-test` | Build the test binary with feature tags and coverage instrumentation. |
| `make lint` | Lint Go and the Ruby test harness. |
| `make specs` | Run Go tests with race and coverage reporting. |
| `make features` | Run cucumber features against the local service. |
| `make benchmarks` | Run cucumber benchmarks. |
| `make coverage` | Generate HTML and function coverage reports. |
| `make sec` | Run configured security checks. |
| `make dev` | Run the server in watch mode with `air`. |
> [!CAUTION]
> Some shared git helper targets are intentionally destructive, including `make reset`, `make purge`, and branch deletion helpers. Use `make help` and inspect the target before running shared git workflow commands.
### ✅ Validation
The main CircleCI `build-service` job runs:
```sh
make clean
make dep
make lint
make sec
make features
make benchmarks
make analyse
make coverage
```
For a local documentation-only change, `make help` is a useful smoke check that
the documented command surface is still available.