If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/httpswift/swifter shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 18 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live httpswift/swifter repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/httpswift/swifter.

What it runs against: a local clone of httpswift/swifter — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in httpswift/swifter | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch stable exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 813 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of httpswift/swifter. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/httpswift/swifter.git
#   cd swifter
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of httpswift/swifter and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "httpswift/swifter(\\.git)?\\b" \\
  && ok "origin remote is httpswift/swifter" \\
  || miss "origin remote is not httpswift/swifter (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify stable >/dev/null 2>&1 \\
  && ok "default branch stable exists" \\
  || miss "default branch stable no longer exists"

# 4. Critical files exist
test -f "Xcode/Sources/HttpServer.swift" \\
  && ok "Xcode/Sources/HttpServer.swift" \\
  || miss "missing critical file: Xcode/Sources/HttpServer.swift"
test -f "Xcode/Sources/HttpRouter.swift" \\
  && ok "Xcode/Sources/HttpRouter.swift" \\
  || miss "missing critical file: Xcode/Sources/HttpRouter.swift"
test -f "Xcode/Sources/HttpParser.swift" \\
  && ok "Xcode/Sources/HttpParser.swift" \\
  || miss "missing critical file: Xcode/Sources/HttpParser.swift"
test -f "Xcode/Sources/Socket+Server.swift" \\
  && ok "Xcode/Sources/Socket+Server.swift" \\
  || miss "missing critical file: Xcode/Sources/Socket+Server.swift"
test -f "Xcode/Sources/HttpResponse.swift" \\
  && ok "Xcode/Sources/HttpResponse.swift" \\
  || miss "missing critical file: Xcode/Sources/HttpResponse.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 813 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~783d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/httpswift/swifter"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Swifter is a minimal HTTP server engine written in pure Swift that enables developers to build lightweight web servers and REST APIs without heavy frameworks. It supports HTTP 1.1, WebSockets, static file serving, and routing with a fluent API, and runs on macOS, Linux, and tvOS. Flat modular structure under Xcode/Sources/ with core HTTP engine (HttpServer.swift, HttpServerIO.swift) using low-level Socket operations (Socket.swift, Socket+Server.swift). Routing handled by HttpRouter.swift, parsing by HttpParser.swift, WebSocket support via WebSockets.swift. Static file serving via String+File.swift extensions. Scopes.swift provides DSL for HTML generation. Example demo in SwifterExample/main.swift and Xcode/Sources/DemoServer.swift.

Swift developers building embedded web servers, IoT applications, or microservices who need a low-dependency HTTP server without the overhead of frameworks like Vapor or Kitura. Also used by developers integrating HTTP capabilities into Swift desktop and mobile apps.

Actively maintained but lightweight in scope. The stable branch (supporting Swift 4.x, 5.0+) is production-ready with CocoaPods/Carthage/SPM support. CI runs on macOS and Linux via GitHub Actions (macos-tests.yml, linux-tests.yml). The 2.0 branch pursuing async I/O is experimental. Modest commit velocity suggests a stable, feature-complete project rather than rapidly evolving.

Very low risk: single-language codebase (170K+ Swift lines) with minimal external dependencies, enabling easy auditing. Maintained single-maintainer repo (typical for small utilities). No large dependency tree visible in Package.swift reduces supply-chain risk. Main risk is architectural: synchronous I/O design (note 2.0 experimental async branch) may bottleneck under high concurrency, and small team means slower security patch turnaround than enterprise frameworks.

Stable branch is in maintenance mode. Active development on 2.0 branch targeting async I/O refactor (visible in branch list). GitHub Actions workflows (danger.yml, linux-tests.yml, macos-tests.yml) indicate CI is enforced. SwiftLint rules (swiftlint.yml) suggest ongoing code quality checks. CHANGELOG.md tracks releases for CocoaPods/Carthage.

Clone and build via Swift Package Manager: git clone https://github.com/httpswift/swifter.git && cd swifter && swift build. Or in Docker: docker run -d -p 9080:9080 -v $(pwd):/Swifter -w /Swifter --name Swifter swift bash -c 'swift run'. Run the example: swift run (executes SwifterExample/main.swift or Xcode/Sources/DemoServer.swift).

Daily commands: swift build compiles the library. swift run executes the example server (listens on default port, likely 8080 based on tiny http server conventions). For Xcode: open Xcode/Swifter.xcodeproj, select SwifterMac or SwifteriOS scheme, build and run. Tests run via swift test (invokes Xcode/LinuxMain.swift on Linux via GitHub Actions).

• Xcode/Sources/HttpServer.swift — Core server engine and request dispatcher; the main entry point that initializes and manages the HTTP server lifecycle.
• Xcode/Sources/HttpRouter.swift — Route matching and handler registration logic; defines how incoming requests are mapped to user-defined handlers.
• Xcode/Sources/HttpParser.swift — Raw HTTP request parsing from socket bytes; critical for correctly interpreting HTTP method, headers, body, and WebSocket upgrades.
• Xcode/Sources/Socket+Server.swift — Low-level socket server implementation and connection handling; manages TCP listening and connection lifecycle.
• Xcode/Sources/HttpResponse.swift — HTTP response builder and serializer; constructs valid HTTP/1.1 responses with headers and body encoding.
• Xcode/Sources/WebSockets.swift — WebSocket protocol upgrade and frame handling; enables persistent bidirectional communication beyond HTTP.
• Package.swift — Swift Package Manager manifest; defines build configuration, platforms, and dependencies for the entire project.

Add a new HTTP route handler

1. Create an HttpServer instance and define a route using subscript syntax (Xcode/Sources/HttpServer.swift)
2. Return an HttpResponse from your handler closure, choosing a status code and body type (e.g., .ok(.text(…)), .notFound(.htmlBody(…))) (Xcode/Sources/HttpResponse.swift)
3. The router automatically matches incoming requests by path pattern and dispatches to your handler (Xcode/Sources/HttpRouter.swift)

Serve static files and directories

1. Use the .serveDirectory(path:options:) response builder to map a route to a local filesystem path (Xcode/Sources/Files.swift)
2. MimeTypes.swift automatically determines Content-Type headers based on file extension (Xcode/Sources/MimeTypes.swift)
3. The server will handle directory listing and range requests if configured (Xcode/Sources/HttpServerIO.swift)

Implement a WebSocket endpoint

1. Register a route handler that checks for WebSocket upgrade headers in the HttpRequest (Xcode/Sources/HttpRequest.swift)
2. Call socket.upgradeToWebSocket() to perform the HTTP Upgrade handshake (SHA-1 key acceptance in WebSockets.swift) (Xcode/Sources/WebSockets.swift)
3. Implement frame reading/writing loop using socket.readWebSocketFrame() and writeWebSocketFrame() for bidirectional messaging (Xcode/Sources/Socket.swift)

Customize request parsing or response serialization

1. Modify HttpParser.swift to handle custom HTTP extensions or protocol variants in the state machine (Xcode/Sources/HttpParser.swift)
2. Extend HttpResponse to add new body encoding builders (e.g., custom serializers) if needed (Xcode/Sources/HttpResponse.swift)
3. Test your changes against the parser test suite (SwifterTestsHttpParser.swift) to ensure backward compatibility (Xcode/Tests/SwifterTestsHttpParser.swift)

• Swift language & standard library — Native type safety, zero-cost abstractions, and seamless compilation to Linux/macOS/iOS binaries
• POSIX sockets (Darwin/Linux) — Provides direct access to TCP/IP stack without external dependencies; minimal overhead
• HTTP/1.1 with WebSocket upgrades (RFC 6455) — Covers both stateless request/response and persistent bidirectional messaging in a single engine
• Synchronous socket I/O with GCD (libdispatch) — Balances simplicity with concurrency via thread pools; no async/await complexity (as of stable branch)

• No external dependencies in core; rely only on Foundation and POSIX

  • Why: Simplifies embedding in iOS/tvOS apps and reduces supply-chain risk
  • Consequence: Must implement HTTP parsing, socket multiplexing, and WebSocket framing manually

• Synchronous request handlers block thread per connection

  • Why: Easier mental model for developers; direct control flow
  • Consequence: Throughput limited by thread pool size; not optimal for high-concurrency I/O (addressed in 2.0 branch with async)

• Streaming HTTP parsing (state machine) rather than buffering entire requests

  • Why: Lower memory footprint and earlier header inspection for routing
  • Consequence: More complex parser logic; potential for partial-state bugs if not careful

• Router matches on path strings with prefix/pattern matching, not compiled trie

  • Why: Flexibility and simplicity for small to medium route counts
  • Consequence: O(n) lookup worst-case; not optimized for thousands of routes

• Does not provide built-in session management, cookies, or authentication—left to handlers
• Does not include TLS/HTTPS support in the stable branch (no HTTPS server)
• Does not implement HTTP/2.0 or multiplexing (HTTP/1.1 only)
• Does not provide ORM, database abstraction, or data persistence
• Does not include a web framework layer (master branch has experimental features)
• Does not support CGI, FastCGI, or reverse proxying

No required environment variables. POSIX socket API differs slightly between Darwin (macOS) and Linux—Socket.swift handles this with conditional compilation (import Darwin vs import Glibc), but custom socket code may break on new platforms. Synchronous blocking I/O means each request ties up a thread; high concurrency (100+ simultaneous requests) requires thread pool tuning via DispatchQueue. File serving (String+File.swift, Socket+File.swift) does not guard against path traversal attacks like '../../../etc/passwd'—users must validate paths. WebSocket parser (WebSockets.swift) assumes well-formed frames; malformed clients may crash. No built-in rate limiting or request size limits visible—large POST bodies or slowloris attacks can exhaust memory.

• POSIX Socket API — Swifter is built on raw POSIX sockets (Socket.swift wraps socket(), bind(), listen(), accept()). Understanding BSD socket semantics is critical to debugging I/O issues and platform-specific behavior.
• HTTP/1.1 Request-Response Parsing — HttpParser.swift manually tokenizes raw bytes into request/response structs. Understanding chunked transfer encoding, keepalive semantics, and header folding is essential to extending protocol support.
• WebSocket Frame Format (RFC 6455) — WebSockets.swift implements frame masking, opcode parsing, and payload length encoding. Modifying WebSocket support requires deep knowledge of the framing layer.
• Swift Property Builders (Result Builders) — Scopes.swift uses @resultBuilder pattern (available in Swift 5.1+) to enable fluent DSL syntax for HTML generation. Key to understanding how the HTML API works without explicit function calls.
• Thread Pool and GCD (Grand Central Dispatch) — HttpServer.swift likely uses DispatchQueue to handle concurrent requests without blocking the main thread. Understanding DispatchQueue semantics is crucial for tuning concurrency under load.
• URL Path Parameter Extraction — HttpRouter.swift parses paths like '/users/:id' and extracts ':id' into request parameters. Understanding pattern matching and regex (if used) is needed to extend routing.
• Base64 and SHA-1 Hashing — String+BASE64.swift and String+SHA1.swift implement WebSocket handshake cryptography (Sec-WebSocket-Key hashing). These are critical for WebSocket upgrades and must match RFC 6455 exactly.

• vapor/vapor — Full-featured Swift web framework building on similar HTTP primitives but with middleware, ORM, and templating—compare if you need features beyond Swifter
• kylef/Curassow — Lightweight Swift HTTP server (similar scope to Swifter) using Nest, demonstrates alternative socket handling patterns
• apple/swift-nio — Apple's async I/O foundation (used by Vapor 4+)—relevant since Swifter 2.0 experimental branch targets async, good reference for modern Swift concurrency
• Alamofire/Alamofire — Complementary HTTP client library often paired with Swifter servers for testing or consuming other APIs from Swift apps
• httpswift/swifter-examples — Community examples repo (if it exists) showing real-world Swifter deployments and recipes beyond the single DemoServer

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for WebSockets.swift

The repo claims WebSocket protocol support in its README but the file structure shows no dedicated test files for WebSockets.swift. Given that WebSockets is a critical protocol feature alongside HTTP 1.1, this represents a significant testing gap. New contributors could add unit tests covering WebSocket handshake, frame parsing, connection lifecycle, and error handling.

• [ ] Create Xcode/SwifteriOSTests/WebSocketsTests.swift with test cases for WebSocket handshake validation
• [ ] Add tests for WebSocket frame parsing in Xcode/SwiftermacOSTests (mirror iOS tests)
• [ ] Test WebSocket connection upgrade from HTTP requests
• [ ] Add edge cases: malformed frames, connection drops, binary vs text frames
• [ ] Verify tests run in both linux-tests.yml and macos-tests.yml workflows

Add unit tests for HttpRouter.swift request routing logic

HttpRouter.swift is a core component for routing HTTP requests, but no dedicated router tests are visible in the test directories. Contributors could add tests covering path matching, route parameters, wildcard patterns, and method-based routing to ensure reliability of the routing layer.

• [ ] Create Xcode/SwifteriOSTests/HttpRouterTests.swift with test cases for route matching
• [ ] Test exact path matching, wildcard routes, and parameterized routes (if supported)
• [ ] Add tests for HTTP method filtering (GET, POST, PUT, DELETE, etc.)
• [ ] Test route precedence and conflict resolution
• [ ] Add performance tests for large route tables

Add integration tests for HttpServer.swift with real socket connections

HttpServer.swift is the main entry point but lacks visible integration tests that verify end-to-end server behavior with actual HTTP requests. Contributors could add integration tests that start a real server and make HTTP requests to verify routing, response handling, and error cases work together correctly.

• [ ] Create Xcode/SwifteriOSTests/HttpServerIntegrationTests.swift
• [ ] Implement tests that start HttpServer on a test port and make real HTTP requests
• [ ] Test basic GET/POST requests with various response types (htmlBody, jsonBody, etc.)
• [ ] Test error responses and status codes (404, 500, etc.)
• [ ] Test WebSocket upgrade requests alongside regular HTTP requests
• [ ] Ensure tests clean up server resources and don't interfere with CI workflows

• Add unit tests for Xcode/Sources/HttpParser.swift covering edge cases like malformed headers, missing Host header, and HTTP/1.0 vs 1.1 differences. Currently no test files visible for core parser logic despite CI setup.
• Implement path traversal sanitization in Xcode/Sources/String+File.swift and Xcode/Sources/Socket+File.swift to block requests like GET /../../etc/passwd when using shareFilesFromDirectory(). Add tests in a new FileSecurity.swift test file.
• Document the Scopes.swift HTML DSL with example code and generated HTML output in README or new doc file. Currently only a brief 'How to HTML' snippet exists; newcomers don't understand property builder syntax or available tags.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.