Embassy
Super lightweight async HTTP server in pure Swift.
Please read: Embedded web server for iOS UI testing.
See also: Our lightweight web framework Ambassador based on Embassy
Features
- Swift 4 & 5
- iOS / tvOS / MacOS / Linux
- Super lightweight, only 1.5 K of lines
- Zero third-party dependency
- Async event loop based HTTP server, makes long-polling, delay and bandwidth throttling all possible
- HTTP Application based on SWSGI, super flexible
- IPV6 ready, also supports IPV4 (dual stack)
- Automatic testing covered
Example
Here's a simple example shows how Embassy works.
let loop = try! SelectorEventLoop(selector: try! KqueueSelector())
let server = DefaultHTTPServer(eventLoop: loop, port: 8080) {
(
environ: [String: Any],
startResponse: ((String, [(String, String)]) -> Void),
sendBody: ((Data) -> Void)
) in
// Start HTTP response
startResponse("200 OK", [])
let pathInfo = environ["PATH_INFO"]! as! String
sendBody(Data("the path you're visiting is \(pathInfo.debugDescription)".utf8))
// send EOF
sendBody(Data())
}
// Start HTTP server to listen on the port
try! server.start()
// Run event loop
loop.runForever()
Then you can visit http://[::1]:8080/foo-bar in the browser and see
the path you're visiting is "/foo-bar"
By default, the server will be bound only to the localhost interface (::1) for security reasons. If you want to access your server over an external network, you'll need to change the bind interface to all addresses:
let server = DefaultHTTPServer(eventLoop: loop, interface: "::", port: 8080)
Async Event Loop
To use the async event loop, you can get it via key embassy.event_loop in environ dictionary and cast it to EventLoop. For example, you can create an SWSGI app which delays sendBody call like this
let app = { (
environ: [String: Any],
startResponse: ((String, [(String, String)]) -> Void),
sendBody: @escaping ((Data) -> Void)
) in
startResponse("200 OK", [])
let loop = environ["embassy.event_loop"] as! EventLoop
loop.call(withDelay: 1) {
sendBody(Data("hello ".utf8))
}
loop.call(withDelay: 2) {
sendBody(Data("baby ".utf8))
}
loop.call(withDelay: 3) {
sendBody(Data("fin".utf8))
sendBody(Data())
}
}
Please notice that functions passed into SWSGI should be only called within the same thread for running the EventLoop, they are all not threadsafe, therefore, you should not use GCD for delaying any call. Instead, there are some methods from EventLoop you can use, and they are all threadsafe
call(callback: (Void) -> Void)
Call given callback as soon as possible in the event loop
call(withDelay: TimeInterval, callback: (Void) -> Void)
Schedule given callback to withDelay seconds then call it in the event loop.
call(atTime: Date, callback: (Void) -> Void)
Schedule given callback to be called at atTime in the event loop. If the given time is in the past or zero, this methods works exactly like call with only callback parameter.
What's SWSGI (Swift Web Server Gateway Interface)?
SWSGI is a hat tip to Python's WSGI (Web Server Gateway Interface). It's a gateway interface enables web applications to talk to HTTP clients without knowing HTTP server implementation details.
It's defined as
public typealias SWSGI = (
[String: Any],
@escaping ((String, [(String, String)]) -> Void),
@escaping ((Data) -> Void)
) -> Void
environ
It's a dictionary contains all necessary information about the request. It basically follows WSGI standard, except wsgi.* keys will be swsgi.* instead. For example:
[
"SERVER_NAME": "[::1]",
"SERVER_PROTOCOL" : "HTTP/1.1",
"SERVER_PORT" : "53479",
"REQUEST_METHOD": "GET",
"SCRIPT_NAME" : "",
"PATH_INFO" : "/",
"HTTP_HOST": "[::1]:8889",
"HTTP_USER_AGENT" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36",
"HTTP_ACCEPT_LANGUAGE" : "en-US,en;q=0.8,zh-TW;q=0.6,zh;q=0.4,zh-CN;q=0.2",
"HTTP_CONNECTION" : "keep-alive",
"HTTP_ACCEPT" : "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"HTTP_ACCEPT_ENCODING" : "gzip, deflate, sdch",
"swsgi.version" : "0.1",
"swsgi.input" : (Function),
"swsgi.error" : "",
"swsgi.multiprocess" : false,
"swsgi.multithread" : false,
"swsgi.url_scheme" : "http",
"swsgi.run_once" : false
]
To read request from body, you can use swsgi.input, for example
let input = environ["swsgi.input"] as! SWSGIInput
input { data in
// handle the body data here
}
An empty Data will be passed into the input data handler when EOF reached. Also please notice that, request body won't be read if swsgi.input is not set or set to nil. You can use swsgi.input as bandwidth control, set it to nil when you don't want to receive any data from client.
Some extra Embassy server specific keys are
embassy.connection-HTTPConnectionobject for the requestembassy.event_loop-EventLoopobjectembassy.version- Version of embassy as a String, e.g.3.0.0
startResponse
Function for starting to send HTTP response header to client, the first argument is status code with message, e.g. "200 OK". The second argument is headers, as a list of key value tuple.
To response HTTP header, you can do
startResponse("200 OK", [("Set-Cookie", "foo=bar")])
startResponse can only be called once per request, extra call will be simply ignored.
sendBody
Function for sending body data to client. You need to call startResponse first in order to call sendBody. If you don't call startResponse first, all calls to sendBody will be ignored. To send data, here you can do
sendBody(Data("hello".utf8))
To end the response data stream simply call sendBody with an empty Data.
sendBody(Data())
Install
CocoaPods
To install with CocoaPod, add Embassy to your Podfile:
pod 'Embassy', '~> 4.1'
Carthage
To install with Carthage, add Embassy to your Cartfile:
github "envoy/Embassy" ~> 4.1
Package Manager
Add it this Embassy repo in Package.swift, like this
import PackageDescription
let package = Package(
name: "EmbassyExample",
dependencies: [
.package(url: "https://github.com/envoy/Embassy.git",
from: "4.1.1"),
]
)
You can read this example project here.
![[Bugfix] Crashes when reading the body in Release configurations](https://avatars.githubusercontent.com/u/17322573?v=4)
![[Bugfix] Fix SIGABRT in KqueueSelector](https://avatars.githubusercontent.com/u/12351004?v=4)
2k Dec 5, 2022
258 Oct 6, 2022
6.3k Dec 27, 2022
5.5k Jan 7, 2023
451 Jul 28, 2022
416 Dec 16, 2022
3.6k Dec 31, 2022
397 Oct 30, 2022
22.4k Jan 3, 2023
46 Jan 29, 2022
7.6k Dec 27, 2022
925 Nov 17, 2022
13.9k Dec 29, 2022
850 Dec 2, 2022
8 May 16, 2022
4 Apr 25, 2022
68 Jul 25, 2022
174 Oct 22, 2022