{"id":29132064,"url":"https://github.com/yuvrajprashar/http-server-scratch","last_synced_at":"2025-06-30T06:12:20.785Z","repository":{"id":301932052,"uuid":"1010226177","full_name":"YuvrajPrashar/http-server-scratch","owner":"YuvrajPrashar","description":"created my own http server from scratch along side an echo socket in node js","archived":false,"fork":false,"pushed_at":"2025-06-29T20:51:55.000Z","size":493,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-29T21:33:05.025Z","etag":null,"topics":["built-from-scratch","http","http-server","http-server-from-scratch","javascript","js","node","node-js","nodejs","server","socket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YuvrajPrashar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-06-28T16:10:09.000Z","updated_at":"2025-06-29T20:51:58.000Z","dependencies_parsed_at":"2025-06-29T21:33:05.595Z","dependency_job_id":null,"html_url":"https://github.com/YuvrajPrashar/http-server-scratch","commit_stats":null,"previous_names":["yuvrajprashar/create-web-server-node","yuvrajprashar/http-server-scratch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/YuvrajPrashar/http-server-scratch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuvrajPrashar%2Fhttp-server-scratch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuvrajPrashar%2Fhttp-server-scratch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuvrajPrashar%2Fhttp-server-scratch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuvrajPrashar%2Fhttp-server-scratch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YuvrajPrashar","download_url":"https://codeload.github.com/YuvrajPrashar/http-server-scratch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuvrajPrashar%2Fhttp-server-scratch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262720721,"owners_count":23353456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["built-from-scratch","http","http-server","http-server-from-scratch","javascript","js","node","node-js","nodejs","server","socket"],"created_at":"2025-06-30T06:12:19.366Z","updated_at":"2025-06-30T06:12:20.730Z","avatar_url":"https://github.com/YuvrajPrashar.png","language":"TypeScript","readme":"# HTTP Server from Scratch\n\nA complete HTTP/1.1 server implementation built from scratch using Node.js TCP sockets, demonstrating low-level network programming and HTTP protocol implementation.\n\n## Project Overview\n\nThis project contains two implementations:\n\n1. **`socket.ts`** - A simple TCP echo server (foundation)\n2. **`http-server-clean.ts`** - A complete HTTP/1.1 server implementation\n3. **`HTTP_SERVER_GUIDE.md`** - Detailed step-by-step explanation\n\n## Features\n\n### HTTP Server Features\n\n- ✅ HTTP/1.1 protocol implementation\n- ✅ GET and POST method support\n- ✅ Keep-alive connections\n- ✅ Content-Length handling\n- ✅ Header parsing and validation\n- ✅ Error handling with proper HTTP status codes\n- ✅ Echo server functionality\n- ✅ Dynamic buffer management\n- ✅ Promise-based socket API\n- ✅ Streaming request body reading\n\n### What Makes This Special\n\n- **From Scratch**: No HTTP frameworks used - built directly on TCP sockets\n- **Educational**: Every line is explained with comments and documentation\n- **Production Concepts**: Implements real-world concerns like buffer management, error handling, and HTTP compliance\n- **Modern TypeScript**: Uses async/await and proper typing throughout\n\n## Quick Start\n\n### Prerequisites\n\n```bash\nnpm install typescript @types/node ts-node\n```\n\n### Running the HTTP Server\n\n```bash\n# Start the server\nnpx ts-node http-server-clean.ts\n\n# In another terminal, test it\ncurl http://127.0.0.1:3000/\ncurl http://127.0.0.1:3000/echo -d \"Hello World\"\n\n# Or run the test suite\n./test-server.sh\n```\n\n### Running the TCP Echo Server\n\n```bash\n# Start the echo server\nnpx ts-node socket.ts\n\n# In another terminal, test with netcat\necho \"hello\" | nc 127.0.0.1 1234\n```\n\n## API Examples\n\n### Basic Request\n\n```bash\ncurl http://127.0.0.1:3000/\n# Response: hello world.\n```\n\n### Echo Server\n\n```bash\ncurl http://127.0.0.1:3000/echo -d \"Your message here\"\n# Response: Your message here\n```\n\n### JSON Echo\n\n```bash\ncurl http://127.0.0.1:3000/echo \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"test\", \"value\": 123}'\n# Response: {\"name\": \"test\", \"value\": 123}\n```\n\n### With Custom Headers\n\n```bash\ncurl -H \"X-Custom-Header: value\" http://127.0.0.1:3000/echo -d \"data\"\n# The server will echo back: data\n```\n\n## Architecture\n\n### Layer Structure\n\n```\n┌─────────────────────────────────┐\n│     Application Layer           │  ← handleReq() - Business logic\n├─────────────────────────────────┤\n│     HTTP Protocol Layer         │  ← HTTP parsing, response generation\n├─────────────────────────────────┤\n│     Buffer Management Layer     │  ← Dynamic buffers, message framing\n├─────────────────────────────────┤\n│     Promise Socket Layer        │  ← soRead(), soWrite() - Promise API\n├─────────────────────────────────┤\n│     TCP Socket Layer            │  ← Raw Node.js net.Socket\n└─────────────────────────────────┘\n```\n\n### Key Components\n\n#### 1. **HTTPError Class**\n\nCustom error handling with HTTP status codes\n\n#### 2. **Dynamic Buffer (DynBuf)**\n\n- Grows automatically as needed\n- Efficient append/remove operations\n- Handles variable-length HTTP messages\n\n#### 3. **TCP Connection Wrapper (TCPConn)**\n\n- Converts event-based sockets to Promise-based API\n- Handles errors, EOF, and data events\n- Enables clean async/await usage\n\n#### 4. **Body Reader Interface**\n\n- Streaming interface for large request bodies\n- Memory-efficient for file uploads\n- Supports both Content-Length and chunked encoding\n\n#### 5. **HTTP Parser**\n\n- Parses request line, headers, and body\n- Validates HTTP format compliance\n- Generates proper HTTP responses\n\n## File Structure\n\n```\nweb-server/\n├── socket.ts              # TCP echo server (foundation)\n├── http-server-clean.ts   # Complete HTTP server implementation\n├── HTTP_SERVER_GUIDE.md   # Detailed implementation guide\n├── test-server.sh         # Test script\n├── package.json           # Node.js dependencies\n├── tsconfig.json          # TypeScript configuration\n└── README.md             # This file\n```\n\n## Implementation Highlights\n\n### 1. **Promise-Based Socket API**\n\n```typescript\n// Convert callback-based socket to Promise-based\nasync function soRead(conn: TCPConn): Promise\u003cBuffer\u003e {\n  return new Promise((resolve, reject) =\u003e {\n    conn.reader = { resolve, reject };\n    conn.socket.resume();\n  });\n}\n```\n\n### 2. **Dynamic Buffer Management**\n\n```typescript\n// Efficient buffer that grows by powers of 2\nfunction bufPush(buf: DynBuf, data: Buffer): void {\n  let cap = Math.max(buf.data.length, 32);\n  while (cap \u003c newLen) {\n    cap *= 2; // Double capacity when needed\n  }\n}\n```\n\n### 3. **HTTP Message Parsing**\n\n```typescript\n// Parse complete HTTP requests from byte stream\nfunction cutMessage(buf: DynBuf): null | HTTPReq {\n  const indx = buf.data.indexOf(\"\\r\\n\\r\\n\");\n  if (indx \u003c 0) return null; // Incomplete message\n  // Parse and remove from buffer\n}\n```\n\n### 4. **Streaming Body Reading**\n\n```typescript\n// Handle large request bodies without loading into memory\ntype BodyReader = {\n  length: number;\n  read: () =\u003e Promise\u003cBuffer\u003e;\n};\n```\n\n## Learning Objectives\n\nThis implementation teaches:\n\n1. **Network Programming**: TCP sockets, event handling, buffers\n2. **HTTP Protocol**: Request/response format, headers, status codes\n3. **Async Programming**: Converting callbacks to Promises, async/await\n4. **Buffer Management**: Dynamic sizing, efficient memory usage\n5. **Error Handling**: Network errors, protocol errors, graceful degradation\n6. **TypeScript**: Advanced types, interfaces, error handling\n\n## Testing\n\nThe project includes comprehensive tests:\n\n```bash\n# Run all tests\n./test-server.sh\n\n# Manual testing\ncurl -v http://127.0.0.1:3000/\ncurl -X POST http://127.0.0.1:3000/echo -d \"test data\"\ncurl -H \"Content-Type: application/json\" http://127.0.0.1:3000/echo -d '{\"test\": true}'\n```\n\n## Limitations \u0026 Future Work\n\n### Current Limitations\n\n- No HTTPS/TLS support\n- No chunked transfer encoding\n- No compression (gzip)\n- No file serving\n- Basic routing only\n\n### Potential Extensions\n\n- **TLS/HTTPS**: Add encryption layer\n- **HTTP/2**: Binary protocol, multiplexing\n- **Chunked Encoding**: Unknown content length support\n- **Compression**: Response compression\n- **Static Files**: File serving with proper MIME types\n- **Routing**: Pattern matching, middleware system\n- **Authentication**: Basic auth, JWT support\n- **WebSocket**: Upgrade from HTTP\n\n## Performance Considerations\n\n- **Memory Efficient**: Streaming body processing\n- **Connection Reuse**: HTTP/1.1 keep-alive support\n- **Buffer Management**: Power-of-2 growth prevents fragmentation\n- **Error Handling**: Proper cleanup prevents memory leaks\n\n## Educational Value\n\nThis implementation is designed for learning:\n\n- **Complete**: Every aspect of HTTP is implemented\n- **Documented**: Extensive comments explain the \"why\"\n- **Testable**: Includes test scripts and examples\n- **Extensible**: Clean architecture allows easy additions\n- **Real-world**: Handles edge cases and error conditions\n\n## License\n\nMIT License - Feel free to use this for learning and educational purposes.\n\n## Contributing\n\nThis is an educational project. If you find bugs or have suggestions for better explanations, please open an issue!\n\n---\n\nBuilt with ❤️ for understanding how HTTP really works under the hood.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuvrajprashar%2Fhttp-server-scratch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuvrajprashar%2Fhttp-server-scratch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuvrajprashar%2Fhttp-server-scratch/lists"}