README.md

   1 # Swift Server Project HTTP APIs
   2
   3 :warning: This project is unmaintained experimental legacy code. It has been obsoleted by [SwiftNIO](https://github.com/apple/swift-nio) which contains the recommended HTTP API of the [Swift Server Work Group](https://swift.org/server/).
   4
   5 It remains here for historical interest only.
   6
   7 ## Getting Started
   8
   9
  10 ### Hello World
  11 The following code implements a very simple "Hello World!" server:
  12
  13 ```swift
  14 import Foundation
  15 import HTTP
  16
  17 func hello(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
  18     response.writeHeader(status: .ok)
  19     response.writeBody("Hello, World!")
  20     response.done()
  21     return .discardBody
  22 }
  23
  24 let server = HTTPServer()
  25 try! server.start(port: 8080, handler: hello)
  26
  27 RunLoop.current.run()
  28 ```
  29
  30 The `hello()` function receives a `HTTPRequest` that describes the request and a `HTTPResponseWriter` used to write a response.
  31
  32 Data that is received as part of the request body is made available to the closure that is returned by the `hello()` function. In the "Hello World!" example the request body is not used, so `.discardBody` is returned.
  33
  34 ### Echo Server
  35 The following code implements a very simple Echo server that responds with the contents of the incoming request:
  36
  37 ```swift
  38 import Foundation
  39 import HTTP
  40
  41 func echo(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
  42     response.writeHeader(status: .ok)
  43     return .processBody { (chunk, stop) in
  44         switch chunk {
  45         case .chunk(let data, let finishedProcessing):
  46             response.writeBody(data) { _ in
  47                 finishedProcessing()
  48             }
  49         case .end:
  50             response.done()
  51         default:
  52             stop = true
  53             response.abort()
  54         }
  55     }
  56 }
  57
  58 let server = HTTPServer()
  59 try! server.start(port: 8080, handler: echo)
  60
  61 RunLoop.current.run()
  62 ```
  63 As the Echo server needs to process the request body data and return it in the reponse, the `echo()` function returns a `.processBody` closure. This closure is called with `.chunk` when data is available for processing from the request, and `.end` when no more data is available.
  64
  65 Once any data chunk has been processed, `finishedProcessing()` should be called to signify that it has been handled.
  66
  67 When the response is complete, `response.done()` should be called.
  68
  69 ## API Documentation
  70 Full Jazzy documentation of the API is available here:
  71 <https://swift-server.github.io/http/>
  72
  73 ## Contributing
  74
  75 ### Feedback
  76 We are actively seeking feedback on this prototype and your comments are extremely valuable. If you have any comments on the API design, the implementation, or any other aspects of this project, please email the [`swift-server-dev`](https://lists.swift.org/mailman/listinfo/swift-server-dev) mailing list.
  77
  78 ### Writing Code
  79 We also welcome code contributions.  If you are developing on macOS, you may want to work within Xcode.  This project uses the [Swift Package Manager](https://swift.org/package-manager/).  To work on this project within Xcode you can run the Swift Package Manager command `swift package generate-xcodeproj` to generate an `.xcodeproj` to work on within Xcode.
  80
  81 ## Acknowledgements
  82 This project is based on an inital proposal from @weissi on the swift-server-dev mailing list:
  83 <https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170403/000422.html>