thedate

Version 0.5.0

A fast, lightweight HTTP service that returns the current date and time in 61+ different formats via a simple JSON API.

Inspired by now.httpbin.org - thanks to the original creators!

What's New in 0.5.0

🐛 iso_year fix: it now reports the ISO week-year (%G), not the calendar year, so it agrees with iso_year_full across year boundaries
🪝 prek hooks: gitleaks on commit, the slow checks on push
🧹 Leaner Makefile: 13 targets, make alone prints help
🐳 Docker under docker/: Alpine 3.22, pinned toolchain, 6.9MB image
⚙️ Release profile: thin LTO, codegen-units = 1, stripped binary
🔄 Faster CI: one job for fmt/lint/test, plus a container smoke test

Features

🚀 Fast & Lightweight: Built with Rust, Actix-web, and chrono
📅 61+ Formats: ISO 8601, RFC 2822, RFC 3339, Unix timestamp, week numbers, and more
🏥 Health Checks: Built-in /health endpoint for orchestration
🐳 Docker Ready: Optimized multi-stage Dockerfile with health checks
🔧 Configurable: Environment variable configuration
📊 Well Tested: 64 tests (45 unit + 16 integration + 3 doc)

Quick Start

Using Docker

docker run -p 8080:8080 thedate
curl http://localhost:8080/

Using Docker Compose

docker compose -f docker/docker-compose.yml up -d
curl http://localhost:8080/

From Source

# Build and run
cargo build --release
cargo run --release

# Or use Make
make release
make run

API Documentation

GET `/`

Returns the current timestamp in 61+ different formats.

Example Request:

curl http://localhost:8080/

Example Response:

{
  "yyyy_mm_dd": "2024_03_15",
  "mm_dd_yyyy": "03_15_2024",
  "dd_mm_yyyy": "15_03_2024",
  "yyyymmdd": "20240315",
  "unix_timestamp": 1710504045,
  "rfc2822_date_format": "Fri, 15 Mar 2024 12:30:45 +0000",
  "rfc3339_date_format": "2024-03-15T12:30:45+00:00",
  "iso_week_date_format": "2024-W11-5",
  "quarter_of_the_year": 1,
  "military_time": "12:30",
  "am_pm_notation": "pm",
  ...
}

GET `/health`

Health check endpoint for monitoring and orchestration.

Example Request:

curl http://localhost:8080/health

Example Response:

{
  "status": "healthy"
}

Available Timestamp Formats

The API returns 61+ fields in each response:

Date Formats

Underscore-separated: yyyy_mm_dd, mm_dd_yyyy, dd_mm_yyyy
No separator: yyyymmdd, mmddyyyy, ddmmyyyy
Hyphen-separated: yyyymmdd_hyphenated, mmddyyyy_hyphenated, ddmmyyyy_hyphenated
ISO 8601: full_iso, iso_week_date_format, iso_year_week_format
Locale: locale_date, mdy_format, verbose_date

Time Formats

Military time: military_time (HH:MM)
Underscore time: hh_mm_ss (HH_MM_SS)
AM/PM: am_pm_notation

RFC Formats

RFC 2822: rfc2822_date_format
RFC 3339: Multiple variants with different precision levels (millis, secs, micros, nanos, autosi) and timezone formats

Components

Numeric: unix_timestamp, day_of_the_year, month_of_the_year, hour_of_the_day, minute_of_the_hour, second_of_the_minute
Year: year_quad, century_duo, year_duo, iso_year, iso_year_full, iso_year_duo
Month: month_number, short_month (Jan), long_month (January)
Day: day_duo, easy_day, julian_day
Week: week_number_of_the_year, us_week_num, work_week_num, iso_week, iso_week_num, week
Weekday: weekday (Friday), weekday_short, abbrev_weekday (Fri), weekday_index, iso_weekday
Other: quarter_of_the_year, timezone_name

Configuration

Configure via environment variables:

Variable	Description	Default
`HOST`	Server bind address	`0.0.0.0`
`PORT`	Server bind port	`8080`
`RUST_LOG`	Log level (error, warn, info, debug, trace)	`info`

Example:

export HOST=127.0.0.1
export PORT=3000
export RUST_LOG=debug
cargo run

Development

Prerequisites

Rust 1.85+ (or use Docker)
cargo

Building

# Debug build
cargo build
make build

# Release build
cargo build --release
make release

Testing

# Run all tests
cargo test
make test

# Run all quality checks (format, lint, test)
make check

Code Quality

# Format code
cargo fmt
make fmt

# Run linter
cargo clippy --all-targets --all-features -- -D warnings
make lint

Git Hooks

Hooks are managed with prek (prek.toml):

prek install          # one-time setup
prek run --all-files  # run the pre-commit stage manually
prek run --all-files --hook-stage pre-push

Commits stay fast because only secret scanning runs then:

Stage	Hooks
pre-commit	`gitleaks` (staged secrets)
pre-push	`cargo fmt --check`, `cargo clippy`, `cargo test`, `checkmake`, `hadolint`, file hygiene

Docker

# Build Docker image
docker build -f docker/Dockerfile -t thedate .
make docker

# Run Docker container
docker run -p 8080:8080 thedate

Docker Compose

# Start all services
make compose-up

# Stop all services
make compose-down

# View logs
docker compose -f docker/docker-compose.yml logs -f thedate

Project Structure

thedate/
├── src/
│   ├── main.rs           # Application entry point & server setup
│   ├── lib.rs            # Library exports & module declarations
│   ├── config.rs         # Configuration from environment variables
│   ├── handlers.rs       # HTTP request handlers
│   └── timestamp.rs      # Timestamp data structure & formatting
├── tests/
│   └── integration_test.rs  # Integration tests (16 tests)
├── docker/
│   ├── Dockerfile        # Multi-stage build (Alpine 3.22)
│   └── docker-compose.yml   # Traefik + Watchtower stack
├── Cargo.toml            # Rust dependencies & metadata
├── Makefile              # Development commands
├── prek.toml             # Git hook configuration
└── README.md             # This file

Architecture

Actix-web: High-performance async web framework
chrono: Comprehensive date/time library
serde: Fast JSON serialization
env_logger: Flexible logging with RUST_LOG support

The service is stateless and can be horizontally scaled. Each request generates a fresh timestamp - no caching or state management required.

Performance

Binary Size: ~4MB (stripped release build)
Docker Image: ~7MB (Alpine 3.22 multi-stage build)
Response Time: sub-millisecond; every field is derived from one DateTime<Utc> with no I/O or allocation beyond the response body

Deployment

Docker (Recommended)

docker build -f docker/Dockerfile -t thedate .
docker run -d -p 8080:8080 --name thedate thedate

The Docker image includes:

Non-root user for security
Health check endpoint
Optimized binary (stripped)
Minimal Alpine Linux base

Docker Compose with Traefik

The included docker/docker-compose.yml provides:

Automatic HTTPS with Let's Encrypt
Traefik reverse proxy
Watchtower for auto-updates
Health checks

Configure your domain in a .env file:

DOMAIN=thedate.yourdomain.com
CF_API_EMAIL=your@email.com
CF_API_KEY=your_cloudflare_api_key

Then deploy:

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

Bare Metal / VM

# Build release binary
cargo build --release

# Copy binary to target system
cp target/release/thedate /usr/local/bin/

# Create systemd service (example)
sudo tee /etc/systemd/system/thedate.service <<EOF
[Unit]
Description=thedate HTTP service
After=network.target

[Service]
Type=simple
User=thedate
Environment=RUST_LOG=info
Environment=HOST=0.0.0.0
Environment=PORT=8080
ExecStart=/usr/local/bin/thedate
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable thedate
sudo systemctl start thedate

Testing

The project includes comprehensive test coverage:

45 Unit Tests: Individual formats and edge cases (leap years, ISO week 53, year boundaries, quarter transitions)
16 Integration Tests: HTTP endpoints and the 61-field API contract
3 Doc Tests: Rustdoc examples stay runnable
Total: 64 tests with 90%+ code coverage

Run tests:

make check  # Runs fmt, lint, and all tests

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (make check)
Commit with semantic messages (git commit -m 'feat: add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Message Format

Use semantic commit messages:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions or changes
refactor: Code refactoring
chore: Maintenance tasks

License

[Add your license here]

Acknowledgments

Inspired by now.httpbin.org
Built with Actix-web
Date/time handling by chrono

Support

Issues: GitHub Issues
Documentation: Run cargo doc --open for API docs

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docker		docker
src		src
tests		tests
.claudeignore		.claudeignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Makefile		Makefile
README.md		README.md
prek.toml		prek.toml

Latest commit

History

Folders and files

Repository files navigation

thedate

What's New in 0.5.0

Features

Quick Start

Using Docker

Using Docker Compose

From Source

API Documentation

GET /

GET /health

Available Timestamp Formats

Date Formats

Time Formats

RFC Formats

Components

Configuration

Development

Prerequisites

Building

Testing

Code Quality

Git Hooks

Docker

Docker Compose

Project Structure

Architecture

Performance

Deployment

Docker (Recommended)

Docker Compose with Traefik

Bare Metal / VM

Testing

Contributing

Commit Message Format

License

Acknowledgments

Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

GET `/`

GET `/health`