{"id":49559217,"url":"https://github.com/jhanvi857/corehttp","last_synced_at":"2026-05-03T07:08:45.326Z","repository":{"id":339331448,"uuid":"1155376781","full_name":"jhanvi857/coreHTTP","owner":"jhanvi857","description":"A lightweight Java 17 HTTP micro-framework with explicit routing, middleware composition, and production-focused runtime controls.","archived":false,"fork":false,"pushed_at":"2026-04-26T11:31:28.000Z","size":679,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T13:20:11.545Z","etag":null,"topics":["backend-engineering","concurrency","framework","http-server","java","socket-programming","tcp-ip"],"latest_commit_sha":null,"homepage":"https://core-http.vercel.app","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhanvi857.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T12:52:21.000Z","updated_at":"2026-04-26T11:31:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jhanvi857/coreHTTP","commit_stats":null,"previous_names":["jhanvi857/corehttp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jhanvi857/coreHTTP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2FcoreHTTP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2FcoreHTTP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2FcoreHTTP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2FcoreHTTP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhanvi857","download_url":"https://codeload.github.com/jhanvi857/coreHTTP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2FcoreHTTP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32560943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend-engineering","concurrency","framework","http-server","java","socket-programming","tcp-ip"],"created_at":"2026-05-03T07:08:44.482Z","updated_at":"2026-05-03T07:08:45.318Z","avatar_url":"https://github.com/jhanvi857.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NioFlow\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"image.png\" alt=\"NioFlow Logo\" width=\"600\"\u003e\n\u003c/p\u003e\nA lightweight Java 17 HTTP micro-framework with explicit routing, middleware composition, and production-focused runtime controls.\n\n[![Java](https://img.shields.io/badge/Java-17+-orange.svg)](https://openjdk.org/projects/jdk/17/)\n[![Maven](https://img.shields.io/badge/Maven-3.9+-blue.svg)](https://maven.apache.org/)\n[![Coverage](https://img.shields.io/badge/Coverage-Pending-yellow)](#)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/jhanvi857/nioflow)](https://github.com/jhanvi857/coreHTTP/releases/tag/v1.3.0)\n[![NPM Version](https://img.shields.io/npm/v/@jhanvi857/nioflow-cli)](https://www.npmjs.com/package/@jhanvi857/nioflow-cli)\n\nNioFlow is designed around one principle: make HTTP internals understandable without sacrificing production behavior. Instead of hiding complexity behind annotations and reflection-heavy bootstrapping, NioFlow keeps transport, parsing, routing, middleware, and error handling explicit and testable.\n\n---\n\n## Table of Contents\n\n- [What NioFlow Is](#what-nioflow-is)\n- [Key Capabilities](#key-capabilities)\n- [Quick Start](#quick-start)\n- [Documentation Site](#documentation-site)\n- [Framework Programming Model](#framework-programming-model)\n- [Advanced Feature Pack](#advanced-feature-pack)\n- [Architecture Deep Dive](#architecture-deep-dive)\n- [Security Model](#security-model)\n- [Configuration Matrix](#configuration-matrix)\n- [Deployment Guide](#deployment-guide)\n- [Repository Structure](#repository-structure)\n- [Roadmap for Production Hardening](#roadmap-for-production-hardening)\n\n---\n\n## What NioFlow Is\n\nNioFlow is a two-part system:\n\n1. `nioflow-framework`: reusable HTTP framework module.\n2. `task-planner-app`: reference application that demonstrates how to use the framework in a real service.\n\nIt sits between \"build a server from scratch\" and \"adopt a massive framework\":\n\n| Concern | NioFlow Approach | Why It Matters |\n|:---|:---|:---|\n| Connection accept | NIO selector loop | High connection scalability with low idle overhead |\n| Request handling | Bounded worker pool | Predictable behavior under load |\n| Routing | Explicit code-based routes | Easy debugging and refactoring |\n| Middleware | Global + route-group scoped | Clear policy layering (auth, rate limits, CORS) |\n| Errors | Per-type handlers + global fallback | No stack trace leakage |\n| Shutdown | Graceful draining via `drainAndStop` | Safer rolling restarts |\n\n---\n\n## Key Capabilities\n\n### 1. Explicit Route Registration\n\n```java\nNioFlowApp app = new NioFlowApp();\n\napp.get(\"/\", ctx -\u003e ctx.send(\"Hello\"));\napp.get(\"/api/tasks/:id\", taskController::get);\n\napp.group(\"/api/admin\", group -\u003e {\n    group.use(new AuthMiddleware());\n    group.get(\"/stats\", adminController::stats);\n});\n```\n\n### 2. Middleware Pipeline\n\n```java\napp.use(new LoggerMiddleware());\napp.use(new CorsMiddleware(\"https://yourdomain.com\"));\napp.use(new RateLimitMiddleware(100, 10_000));\n```\n\nMiddleware executes in registration order and is wrapped around each resolved route handler.\n\n### 3. Global Error Control\n\n```java\napp.exception(IllegalArgumentException.class, (e, ctx) -\u003e {\n    ctx.status(400).json(Map.of(\"error\", \"Bad Request\", \"details\", e.getMessage()));\n});\n\napp.onError((err, ctx) -\u003e {\n    ctx.status(500).json(Map.of(\"error\", \"Internal Server Error\"));\n});\n```\n\n### 4. TLS Entry Point + Graceful Stop\n\n```java\napp.listenSecure(443, \"keystore.jks\", \"changeit\");\n\nRuntime.getRuntime().addShutdownHook(\n    new Thread(() -\u003e app.drainAndStop(30, TimeUnit.SECONDS))\n);\n```\n\n---\n\n### Install CLI (Recommended)\n\nThe NioFlow CLI handles scaffolding, environment setup, and hot-reloading for you. Requires Node.js (for the installer) and JDK 17+.\n\n```bash\nnpm install -g @jhanvi857/nioflow-cli\n\n# Create a project\nnioflow new my-app\ncd my-app\n\n# Start with hot-reload\nnioflow dev\n```\n\n\u003e **Note:** Node.js is only used to distribute the CLI. Your application runs purely on Java.\n\n### Manual Setup (Without CLI)\n\n#### Prerequisites\n\n- JDK 17+\n- Maven 3.9+\n\n### 0. Configure environment\n\nCreate a local `.env` from the example and set a strong JWT secret:\n\n```bash\ncp .env.example .env\n```\n\nWindows PowerShell alternative:\n\n```powershell\nCopy-Item .env.example .env\n```\n\nAt minimum, set:\n\n- `JWT_SECRET` (32+ characters)\n- `NIOFLOW_CORS_ORIGIN` (frontend origin)\n- `DB_PASS` (if `NIOFLOW_ENABLE_DB=true`)\n\n### 1. Build all modules\n\n```bash\n# From repository root\n./mvnw clean test\n```\n\nWindows PowerShell alternative:\n\n```powershell\n.\\mvn.ps1 clean test\n```\n\n### 2. Run the reference app\n\n```bash\n./mvnw exec:java -pl task-planner-app \\\n  -Dexec.mainClass=io.github.jhanvi857.taskplanner.DemoApplication \\\n  -Dnioflow.jwtSecret=your-very-long-secret-at-least-32-chars\n```\n\n### 3. Verify endpoints\n\n```bash\ncurl http://localhost:8080/_health\ncurl http://localhost:8080/_ready\ncurl http://localhost:8080/metrics\ncurl http://localhost:8080/api/tasks/\n```\n\nExpected behavior:\n\n- `/_health` returns `200` with JSON payload.\n- `/_ready` returns `200` when dependencies are ready (`503` if DB mode is enabled but DB is unavailable).\n- `/metrics` returns `200` with metrics report.\n- `/api/tasks/` returns `401` without bearer token.\n\n---\n\n## Documentation Site\n\nThe repository also includes a dedicated Next.js documentation portal in:\n\n```text\ndocumentation/nioflow\n```\n\nRun it locally:\n\n```bash\ncd documentation/nioflow\nnpm install\nnpm run dev\n```\n\nThen open `http://localhost:3000`.\n\n---\n\n## Framework Programming Model\n\n### App Bootstrap Pattern\n\n```java\npublic class MyService {\n    public static void main(String[] args) {\n        NioFlowApp app = new NioFlowApp();\n\n        app.use(new LoggerMiddleware());\n        app.use(new CorsMiddleware(\"https://yourdomain.com\"));\n\n        app.get(\"/\", ctx -\u003e ctx.send(\"Service up\"));\n\n        app.group(\"/api/private\", group -\u003e {\n            group.use(new AuthMiddleware());\n            group.get(\"/profile\", profileController::getProfile);\n        });\n\n        app.onError((err, ctx) -\u003e {\n            ctx.status(500).json(Map.of(\"error\", \"Internal Server Error\"));\n        });\n\n        Runtime.getRuntime().addShutdownHook(\n            new Thread(() -\u003e app.drainAndStop(30, TimeUnit.SECONDS))\n        );\n\n        app.listen(8080);\n    }\n}\n```\n\n### Route Parameters and Context API\n\n```java\napp.get(\"/api/tasks/:id\", ctx -\u003e {\n    String id = ctx.pathParam(\"id\");\n    String auth = ctx.header(\"Authorization\");\n\n    ctx.status(200).json(Map.of(\n        \"taskId\", id,\n        \"authorized\", auth != null\n    ));\n});\n```\n\n### Async Repository Pattern (JDBC Offload)\n\n```java\npublic CompletableFuture\u003cOptional\u003cTask\u003e\u003e findById(Long id) {\n    return CompletableFuture.supplyAsync(() -\u003e {\n        // Blocking JDBC work isolated in dedicated DB executor\n        // so request workers are not permanently blocked by DB I/O.\n    }, dbExecutor);\n}\n```\n\n---\n\n## Advanced Feature Pack\n\nNioFlow now includes five opt-in features designed for small teams operating production services without heavy platform infrastructure.\n\n### 1. ChaosMiddleware (controlled fault injection)\n\n```java\napp.use(\n    new ChaosMiddleware()\n        .latency(200, 0.10)\n        .error(500, 0.05)\n        .drop(0.01)\n);\n```\n\n- Guarded by `NIOFLOW_CHAOS_ENABLED=true`.\n- Logs each injected fault with route and path.\n- Supports composable latency, error, and drop behavior.\n\n### 2. Per-route observability and protection (fluent API)\n\n```java\napp.get(\"/api/orders\", ordersController::list)\n   .timeout(2000)\n   .rateLimit(50, 10_000);\n```\n\n- Per-route request/error counters.\n- Per-route p50/p95/p99 latency (sliding in-memory window).\n- Route-scoped timeout and route-scoped rate limit.\n\n### 3. Request hedging for tail-latency reduction\n\n```java\napp.get(\"/api/search\", searchController::search)\n   .hedge(100);\n```\n\n- Fires a backup execution when primary crosses threshold.\n- Returns first successful completion.\n- Hedge trigger count appears in route-level metrics.\n\n### 4. Route-group scoped circuit breaker middleware\n\n```java\napp.group(\"/api/downstream\", group -\u003e {\n    group.use(new CircuitBreakerMiddleware()\n        .threshold(0.5)\n        .windowSize(20)\n        .cooldown(10_000));\n\n    group.get(\"/inventory\", inventoryController::read);\n});\n```\n\n- CLOSED / OPEN / HALF_OPEN states.\n- OPEN returns `503` and `Retry-After` header.\n- Circuit state is exposed per route-group in `/metrics` output.\n\n### 5. Request replay for fast debugging\n\n```java\napp.enableReplay(50);\n```\n\n- Guarded by `NIOFLOW_REPLAY_ENABLED=true`.\n- Captures recent requests in circular memory buffer.\n- `GET /_replay` lists recorded requests.\n- `POST /_replay/:index` replays through current live pipeline and returns original vs current response.\n- Sensitive headers (`Authorization`, `Cookie`, `X-API-Key`) are stripped automatically.\n- **SECURITY WARNING**: The replay buffer endpoints are exposed without authentication by default. In production, you must either disable replay (`NIOFLOW_REPLAY_ENABLED=false`) or secure the `/_replay` routes behind your own authentication middleware to prevent leaking request paths and payloads to unauthorized users.\n\n### 6. Hot Reload (Watch Mode)\n\n```java\nNioFlowApp.enableHotReload(DemoApplication.class, args);\n```\n\n- Guarded by `NIOFLOW_WATCH=true`.\n- Monitors source directory for changes.\n- Automatically recompiles using Maven (`mvn`, `mvnw`, or `mvn.ps1`).\n- Restarts the application in a child process for near-instant developer feedback.\n\n---\n\n## Architecture Deep Dive\n\n### Runtime Topology\n\n```mermaid\ngraph TD\n    C[Client] --\u003e SEL[Selector Accept Loop]\n    SEL --\u003e ACC[Accept SocketChannel]\n    ACC --\u003e BLK[Configure blocking mode for worker parsing]\n    BLK --\u003e WP[Bounded Worker Pool]\n    WP --\u003e HP[HttpParser]\n    HP --\u003e RT[Router]\n    RT --\u003e MW[Middleware Chain: Logger, Tracing, CORS]\n    MW --\u003e CB{Circuit Breaker?}\n    CB -- OPEN --\u003e 503[503 Service Unavailable]\n    CB -- CLOSED --\u003e H[Route Handler]\n    H --\u003e RESP[HttpResponse]\n    RESP --\u003e C\n\n    H --\u003e DB[(PostgreSQL / Mongo / Redis)]\n    H --\u003e OT[OpenTelemetry Exporter]\n    RT --\u003e PLG[Plugins: HealthCheck, StaticFiles, Replay]\n```\n\n---\n\n### Request Lifecycle Sequence\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant Worker\n    participant Router\n    participant Middleware\n    participant Handler\n\n    Client-\u003e\u003eWorker: TCP Connection\n    Worker-\u003e\u003eWorker: Parse HTTP Request\n    Worker-\u003e\u003eRouter: Resolve Route\n    alt Route Not Found\n        Router--\u003e\u003eClient: 404 Not Found\n    else Method Not Allowed\n        Router--\u003e\u003eClient: 405 Method Not Allowed\n    else Success\n        Router-\u003e\u003eMiddleware: Execute Global + Group Hooks\n        Middleware-\u003e\u003eHandler: Execute Handler (wrapped in CB/Hedge)\n        Handler--\u003e\u003eClient: 200/201/204 Response\n    end\n```\n\n### Threading Model\n\n- Accept path: NIO selector thread.\n- Request work path: bounded worker pool.\n- Database path: dedicated DB executor pool.\n\nThis split protects the server from unbounded queue growth and improves backpressure behavior under load.\n\n---\n\n## Security Model\n\n### Authentication\n\n- Protected route groups use `AuthMiddleware`.\n- Token format: `Authorization: Bearer \u003cjwt\u003e`.\n- JWT key source: `JWT_SECRET` (env) or `-Dnioflow.jwtSecret=...`.\n- Startup behavior in reference app: exits if JWT secret is missing or too short.\n\n### Request Hardening\n\n| Control | Current Behavior |\n|:---|:---|\n| Header size cap | 8 KB maximum |\n| Body size cap | 10 MB maximum |\n| Unsupported framing | Rejects invalid Transfer-Encoding/Content-Length combos |\n| Rate limiting | Per client key with sliding window |\n| Error responses | Sanitized with explicit exception handlers |\n\n### CORS Strategy\n\n```java\nString corsOrigin = System.getenv(\"NIOFLOW_CORS_ORIGIN\");\nif (corsOrigin == null || corsOrigin.isBlank()) {\n    corsOrigin = \"http://localhost:3000\";\n}\napp.use(new CorsMiddleware(corsOrigin));\n```\n\nFor production, always set `NIOFLOW_CORS_ORIGIN` to your exact frontend origin.\n\n---\n\n## Configuration Matrix\n\n| Variable / Property | Required | Default | Purpose |\n|:---|:---|:---|:---|\n| `PORT` | No | `8080` | Server port |\n| `JWT_SECRET` | Yes unless auth disabled | None | JWT secret used by `AuthMiddleware` |\n| `NIOFLOW_DISABLE_AUTH` | No | `false` | Disable JWT checks for protected groups (dev only) |\n| `NIOFLOW_CORS_ORIGIN` | Recommended | `http://localhost:3000` | CORS allow-origin value |\n| `NIOFLOW_ENABLE_DB` | No | `false` | Enables DB-backed readiness checks and repository behavior |\n| `JDBC_URL` | If DB enabled | `jdbc:postgresql://localhost:5432/nioflow` | PostgreSQL URL |\n| `DB_USER` | If DB enabled | `postgres` | PostgreSQL user |\n| `DB_PASS` | If DB enabled | None | PostgreSQL password |\n| `MONGO_URI` | No | None | Optional MongoDB URI (enables `initMongo`) |\n| `NIOFLOW_THREADS` / `nioflow.threads` | No | `64` | Worker pool size in `HttpServer` |\n| `NIOFLOW_QUEUE_CAPACITY` / `nioflow.queueCapacity` | No | `1000` | Worker queue capacity for backpressure |\n| `NIOFLOW_SOCKET_TIMEOUT_MS` / `nioflow.socketTimeoutMs` | No | `30000` | Socket read timeout per connection |\n| `NIOFLOW_TLS_ENABLED` | No | `false` | Enable native TLS listener |\n| `NIOFLOW_TLS_KEYSTORE_PATH` | If TLS enabled | None | JKS keystore path |\n| `NIOFLOW_TLS_KEYSTORE_PASSWORD` | If TLS enabled | None | Keystore password |\n| `NIOFLOW_TLS_PORT` | No | `8443` | Native TLS listener port |\n| `NIOFLOW_EXPOSE_ERROR_DETAILS` | No | `false` | Include exception details in error payloads |\n| `NIOFLOW_STATIC_DIR` / `nioflow.staticDir` | No | Auto-resolve | Static files directory |\n| `NIOFLOW_CHAOS_ENABLED` | No | `false` | Enables `ChaosMiddleware` fault injection |\n| `NIOFLOW_REPLAY_ENABLED` | No | `false` | Enables `enableReplay(...)` endpoints |\n| `NIOFLOW_WATCH` | No | `false` | Enables nodemon-like hot reload (Watch Mode) |\n| `NIOFLOW_LOG_FORMAT` | No | `plain` | Set to `json` for structured logging |\n| `NIOFLOW_REDIS_URL` | No | None | Redis connection string for distributed rate limiting |\n| `NIOFLOW_TRACING_ENABLED` | No | `false` | Enables OpenTelemetry tracing |\n| `OTEL_EXPORTER_OTLP_ENDPOINT`| No | `http://localhost:4317` | OTLP gRPC collector endpoint |\n\n---\n\n## Database Integration\n\nNioFlow provides a centralized `Database` utility to manage your persistence layers with zero boilerplate.\n\n### 1. PostgreSQL (Supabase / Local)\nInitialize and get connections directly:\n```java\nNioFlowApp app = new NioFlowApp();\n// Reads JDBC_URL from .env\napp.initPostgres(); \n\ntry (Connection conn = Database.getPostgresConnection()) {\n    // Standard JDBC logic\n}\n```\n\n### 2. MongoDB (Atlas / Local, optional)\nInitialize and access the document store:\n```java\n// Reads MONGO_URI from .env\napp.initMongo(); \n\nMongoClient mongo = Database.getMongoClient();\nMongoDatabase db = mongo.getDatabase(\"nioflow\");\n```\n\n---\n\n## Environment Variable Management\n\nNioFlow includes a built-in `Env` utility that automatically loads configuration from a `.env` file in your project root. This ensures that sensitive keys (like Supabase secrets) remain safe and are not passed via command line arguments.\n\n**Example `.env` file:**\n```env\nJDBC_URL=jdbc:postgresql://your-db.supabase.co:5432/postgres\nDB_USER=postgres\nDB_PASS=your-password\nJWT_SECRET=your-32-char-secret\nPORT=8080\n```\n\n---\n\n## Deployment Guide\n\n### Build Artifacts\n\n```bash\n./mvnw package -DskipTests -pl task-planner-app -am\n```\n\nPrimary runnable artifact:\n\n```text\ntask-planner-app/target/task-planner-app-1.0-SNAPSHOT-jar-with-dependencies.jar\n```\n\n### Run as Plain JVM Service (non-Docker)\n\nWith the new `.env` support, you no longer need complex `-D` flags:\n\n```bash\njava -jar task-planner-app/target/task-planner-app-1.0-SNAPSHOT-jar-with-dependencies.jar\n```\n\n### Production Checklist\n\n- [x] Global `onError` handler registered.\n- [x] Graceful shutdown hook registered.\n- [x] Protected routes gated by `AuthMiddleware`.\n- [x] JWT secret validated at startup.\n- [x] Integration tests assert auth enforcement and observability endpoints.\n- [x] Integration tests assert 404 vs 405 distinction.\n- [x] Integration tests assert middleware ordering and header preservation.\n- [x] Integration tests assert circuit breaker state transitions (CLOSED → OPEN → HALF_OPEN → CLOSED).\n- [x] TLS plan finalized (`listenSecure` or reverse proxy termination).\n- [x] Runtime sizing validated with reproducible load testing script (`scripts/k6-load-test.js`).\n- [x] Vulnerability scanning is enforced in CI for push/PR (`OWASP Dependency Check`).\n\n---\n\n## Performance Benchmarks\n\nNioFlow is designed for high-performance NIO-based request handling. Below are the results of a standardized load test conducted against the `task-planner-app` reference implementation.\n\n### Test Environment \u0026 Setup\n- **Tooling:** k6 v1.7.1\n- **Endpoint:** `GET /_health` (unauthenticated)\n- **Profile:** Graduated ramp-up from 0 to 100 Virtual Users (VUs) over 2 minutes.\n- **Hardware:** Local execution on Windows (Consumer-grade CPU/RAM).\n\n### Key Metrics\n| Metric | Result |\n| :--- | :--- |\n| **Throughput** | **501.12 requests/second** |\n| **Median Latency (p50)** | **1.52 ms** |\n| **p95 Latency** | **47.75 ms** |\n| **p99 Latency** | **74.62 ms** |\n| **Success Rate** | **99.84%** (0.16% error rate at peak 100 VUs) |\n\n### Analysis\nThe results demonstrate excellent efficiency in the median case, with a tiny **1.52ms overhead** for request parsing and routing. At peak load (100 concurrent VUs), the server reached its configured worker pool limit (64 threads), resulting in queuing delays (reflected in the p99 latency) and a negligible number of connection refusals (0.16%) once the OS listen backlog was fully saturated.\n\n---\n\n## Repository Structure\n\n```text\n.\n├── nioflow-framework/\n│   └── src/main/java/io/github/jhanvi857/nioflow/\n│       ├── auth/            # JWT provider and auth primitives\n│       ├── exception/       # Exception handlers and mapping\n│       ├── middleware/      # Logger, CORS, auth, rate limit, metrics\n│       ├── observability/   # Health handlers\n│       ├── plugin/          # Plugin registration points\n│       ├── protocol/        # Parser, request, response models\n│       ├── routing/         # Route, router, groups, context\n│       └── server/          # NIO accept loop and connection handlers\n│\n├── task-planner-app/\n│   └── src/main/java/io/github/jhanvi857/taskplanner/\n│       ├── controller/      # HTTP-facing handlers\n│       ├── repository/      # JDBC access wrapped in futures\n│       ├── db/              # Hikari and DB bootstrap\n│       └── DemoApplication.java\n│\n├── documentation/nioflow/   # Next.js documentation portal\n├── .github/workflows/       # CI build/test/security checks\n├── Dockerfile               # Multi-stage image build\n├── docker-compose.yml       # App + Postgres local stack\n└── runbook.md               # Operational procedures\n```\n\n---\n\n## Roadmap for Production Hardening\n\n1. ✅ CLI Tooling (npm)\n2. ✅ Structured JSON Logging\n3. ✅ OpenTelemetry Integration\n4. 🏗️ Automated OpenAPI/Swagger generation from explicit routes.\n5. 🏗️ Configurable auth claim mapping for RBAC.\n\n---\n\n## Credits \u0026 Attribution\n\nThis project is authored and maintained by **Jhanvi Patel** (jhanvi857). \n\n### Dependencies \u0026 Third-Party Code\n- **Environment Management**: Powered by [dotenv-java](https://github.com/cdimascio/dotenv-java) by **io.github.cdimascio**. Licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). \n- **Networking**: Core architectural patterns for the NIO engine were derived from industry-standard high-performance Java server implementations. We honor all original authors and adhere to open-source compliance.\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhanvi857%2Fcorehttp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhanvi857%2Fcorehttp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhanvi857%2Fcorehttp/lists"}