bash-web-server

A production-grade, highly scalable HTTP/1.1 REST web server and task management engine built entirely in GNU Bash with zero external programming languages, powered by PostgreSQL 17, Linux kernel SO_REUSEPORT, and HMAC-SHA256 JWT authentication.

---

🌟 Highlights

• Zero Programming Languages: No Python, Go, Node.js, C, Rust, or Java. Everything is executed via GNU Bash, Linux kernel socket primitives, and standard Unix utilities.
• Engineered for High Concurrency:
  • Linux Kernel SO_REUSEPORT: Preforked worker cluster with kernel-level lockless connection distribution.
  • HTTP/1.1 Keep-Alive: Persistent connection reuse eliminates per-request process forks.
  • Zero-Subshell Parser: Native parameter expansion replaces subshell pipes (cut, awk, sed) on the request path.
  • PostgreSQL 17 JSON Engine: Queries format JSON directly in-database (json_build_object, row_to_json), minimizing string processing overhead.
• Complete Feature Set:
  • Authentication: SHA-512 password hashing + stateless HMAC-SHA256 JWT Bearer tokens.
  • RBAC: Multi-tier role permissions (admin, manager, member).
  • Task Management: Projects, tasks, workflow status transitions, comments, and tags.
  • Observability: Real-time /healthz probe and Prometheus-compatible /metrics generated from /proc.
  • Dual Distribution: Clean modular architecture in src/ AND compiled standalone single-script server.sh.

---

📁 Repository Structure

bash-web-server/
├── bin/
│   ├── server                  # Main executable launcher
│   └── cli                     # Administrative management CLI
├── config/
│   ├── server.conf             # Network, worker, and token configuration
│   └── database.conf           # PostgreSQL 17 connection parameters
├── docs/
│   ├── ARCHITECTURE.md         # In-depth architectural whitepaper
│   ├── API_SPEC.md             # Complete OpenAPI / REST specification
│   ├── BENCHMARKS.md           # k6 load testing methodology and results
│   ├── KERNEL_TUNING.md        # sysctl settings & socket optimization guide
│   └── RBAC_MATRIX.md          # Role permission matrix
├── migrations/
│   ├── 001_init_schema.sql     # Users, sessions, audit tables
│   ├── 002_projects_tasks.sql  # Projects, tasks, tags, comments
│   ├── 003_rbac_indexes.sql    # Performance indexes and summary views
│   └── migrate.sh              # Migration engine (up / status / reset)
├── src/
│   ├── core/                   # Kernel sockets, HTTP parser, router, worker pool
│   ├── db/                     # PostgreSQL client & SQL injection defense
│   ├── security/               # Password crypt & HMAC JWT token minting
│   ├── controllers/            # System, Auth, Project, and Task controllers
│   └── utils/                  # JSON parser, logger, HTTP response builder
├── tests/
│   ├── unit/                   # Unit test suite for auth, router, HTTP parser
│   ├── integration/            # End-to-end integration test suite
│   └── load/                   # k6 smoke and stress test scenarios
├── scripts/
│   ├── bundle.sh               # Bundles src/ into standalone server.sh
│   ├── seed.sh                 # Database seeder with realistic test data
│   └── sysctl_tune.sh          # Linux kernel sysctl optimization script
├── docker-compose.yml          # PostgreSQL 17 container
├── server.sh                   # Standalone self-contained single script
├── Makefile                    # Developer automation targets
└── README.md                   # Project documentation

---

🚀 Quick Start

1. Start PostgreSQL 17

# Using Docker Compose
make docker-up

# Or run migrations on existing PostgreSQL 17
make migrate
make seed

2. Start the Server

# Modular development mode
make dev

# Or run the compiled standalone single script
make run

3. Verify

curl http://localhost:8080/healthz
curl http://localhost:8080/metrics

---

🧪 Testing & Benchmarks

# Run unit tests
make test-unit

# Run full integration test suite
make test-integration

# Run k6 load test suite
make bench

---

📄 License

This project is open-source software licensed under the MIT License.