CocoaHTTPServer

CocoaHTTPServer is a lightweight, embeddable HTTP server designed for Mac OS X and iOS applications. It is suitable for use cases such as remote monitoring for server applications, desktop applications using HTTP as a communication backend, or iOS apps providing over-the-air document access.

Key features include:

• Bonjour broadcasting support
• IPv4 and IPv6 support
• Asynchronous networking via GCD (Grand Central Dispatch) and standard sockets
• Password protection
• SSL/TLS encryption
• WebDAV support
• High performance and scalability

CocoaHTTPServer is an embedded HTTP server built using standard networking sockets and streams. It is designed to be integrated into macOS/iOS applications and provides the following features:

• Bonjour Broadcasting: Built-in support for service discovery.
• IP Support: Automatic support for both IPv4 and IPv6.
• Performance: Asynchronous networking and multithreading support.
• Security: Password protection via Digest or Basic authentication, and TLS/SSL encryption support.
• File Handling: Support for Range requests (partial downloads/pause/resume) and extremely large files (up to 16 exabytes).
• Extensibility: Designed to be customized by extending core classes.

To run the demonstration of dynamic file responses:

1. Open the provided Xcode project.
2. Build and run the project.
3. Monitor the Xcode console to find the port number (e.g., Started HTTP server on port 59123).
4. Open a web browser and navigate to http://localhost:<PORT>, replacing <PORT> with the port displayed in the console.

http://localhost:59123

To run the SecureHTTPServer demonstration, open the provided Xcode project, build the project, and run it. The server will output its listening port to the Xcode console (e.g., Started HTTP server on port 59123).

Access the server in your browser using the https protocol at https://localhost:[PORT], replacing [PORT] with the port number displayed in the console.

https://localhost:59123

To demonstrate WebSocket support, use the SimpleWebSocketServer sample project. This sample sets up an HTTP server with a Web folder as its document root, containing an index.html file and client-side WebSocket code.

1. Open the Xcode project.
2. Build and run the project.
3. Check the Xcode console for the server startup message (e.g., "Started HTTP server on port 59123").
4. Open a WebSocket-compatible browser (such as Google Chrome or Safari).
5. Navigate to http://localhost:<PORT>, replacing <PORT> with the port number displayed in the Xcode console.

http://localhost:59123

The SimpleHTTPServer sample demonstrates how to embed CocoaHTTPServer into a macOS desktop application. In this specific example, the server's document root is configured to point to the ~/Sites folder.

To run the sample:

1. Open the Xcode project.
2. Build and run the project.
3. Check the Xcode console to identify the port number (e.g., Started HTTP server on port 59123).
4. Access the server via a web browser using http://localhost:<PORT>.

http://localhost:59123

The PostHTTPServer sample demonstrates how to accept and process HTTP POST requests. It uses a Web folder as the document root and the MyHTTPConnection class to dynamically generate responses based on user input (e.g., a math question submitted via POST).

To run the sample:

1. Open the Xcode project.
2. Build and run the application.
3. Check the Xcode console to identify the port number (e.g., Started HTTP server on port 59123).
4. Open a web browser and navigate to http://localhost:<PORT>, replacing <PORT> with the actual port from the console.

http://localhost:59123

To run the SecureWebSocketServer demonstration, open the provided Xcode project, build it, and run it.

Once running, monitor the Xcode console for a message indicating the port, such as: Started HTTP server on port 59123

To view the application, open a WebSocket-compatible browser (like Google Chrome or Safari) and navigate to the HTTPS URL using the port reported in the console: https://localhost:59123

Note: You must use https instead of http for this secure server.

The SecureWebSocketServer sample uses a self-signed certificate. This triggers specific behaviors in macOS and browsers that you should manage during development:

Browser Warnings

When accessing the server via Safari, you may see an "untrusted certificate" warning. To proceed:

1. Click the "show certificate" button.
2. Click "always trust this certificate".

Keychain Access Prompts

On the first run, the server automatically creates a self-signed certificate named SecureHTTPServer and adds it to your Keychain. If you switch between debug/release builds or change the binary, macOS may prompt you for Keychain access.

To prevent repeated prompts, you can modify the access control:

1. Open the Keychain Access application.
2. Find the SecureHTTPServer private key.
3. Change its Access Control to "Allow all applications to access this item".

To implement custom server logic (such as serving dynamic content, handling user uploads, or adding security layers), you should extend the HTTPServer and/or HTTPConnection classes. The library provides several methods designed to be overridden to add specific features.

Example: Adding Password Protection To implement password protection for resources, override the following methods:

• isPasswordProtected
• passwordForUser

After starting the WebDAV server in Xcode, follow these steps to mount the ~/Sites directory as a network volume in Finder:

1. Open Finder.
2. In the menu bar, select Go -> Connect to Server... (or press Command + K).
3. Enter the server address: http://localhost:8080.
4. Click Connect.
5. When prompted for credentials, select Guest (this sample does not enforce username or password restrictions).

The Finder will then mount the DAV volume.

The SecureHTTPServer example uses a self-signed certificate. When accessing the server via Safari, you will likely see a warning that the certificate is untrusted. To proceed with testing:

1. Click the show certificate button in the warning dialog.
2. Click the always trust this certificate button.