Ambassador
Super lightweight web framework in Swift based on SWSGI
Features
- Super lightweight
- Easy to use, designed for UI automatic testing API mocking
- Based on SWSGI, can run with HTTP server other than Embassy
- Response handlers designed as middlewares, easy to composite
- Async friendly
Example
Here's an example how to mock API endpoints with Ambassador and Embassy as the HTTP server.
import Embassy
import EnvoyAmbassador
let loop = try! SelectorEventLoop(selector: try! KqueueSelector())
let router = Router()
let server = DefaultHTTPServer(eventLoop: loop, port: 8080, app: router.app)
router["/api/v2/users"] = DelayResponse(JSONResponse(handler: { _ -> Any in
return [
["id": "01", "name": "john"],
["id": "02", "name": "tom"]
]
}))
// Start HTTP server to listen on the port
try! server.start()
// Run event loop
loop.runForever()
Then you can visit http://[::1]:8080/api/v2/users in the browser, or use HTTP client to GET the URL and see
[
{
"id" : "01",
"name" : "john"
},
{
"id" : "02",
"name" : "tom"
}
]
Router
Router
allows you to map different path to different WebApp
. Like what you saw in the previous example, to route path /api/v2/users
to our response handler, you simply set the desired path with the WebApp
as the value
let router = Router()
router["/api/v2/users"] = DelayResponse(JSONResponse(handler: { _ -> Any in
return [
["id": "01", "name": "john"],
["id": "02", "name": "tom"]
]
}))
and pass router.app
as the SWSGI interface to the HTTP server. When the visit path is not found, router.notFoundResponse
will be used, it simply returns 404. You can overwrite the notFoundResponse
to customize the not found behavior.
You can also map URL with regular expression. For example, you can write this
let router = Router()
router["/api/v2/users/([0-9]+)"] = DelayResponse(JSONResponse(handler: { environ -> Any in
let captures = environ["ambassador.router_captures"] as! [String]
return ["id": captures[0], "name": "john"]
}))
Then all requests with URL matching /api/v2/users/([0-9]+)
regular expression will be routed here. For all match groups, they will be passed into environment with key ambassador.router_captures
as an array of string.
DataResponse
DataResponse
is a helper for sending back data. For example, say if you want to make an endpoint to return status code 500, you can do
router["/api/v2/return-error"] = DataResponse(statusCode: 500, statusMessage: "server error")
Status is 200 OK
, and content type is application/octet-stream
by default, they all can be overwritten via init parameters. You can also provide custom headers and a handler for returning the data. For example:
router["/api/v2/xml"] = DataResponse(
statusCode: 201,
statusMessage: "created",
contentType: "application/xml",
headers: [("X-Foo-Bar", "My header")]
) { environ -> Data in
return Data("<xml>who uses xml nowadays?</xml>".utf8)
}
If you prefer to send body back in async manner, you can also use another init that comes with extra sendData
function as parameter
router["/api/v2/xml"] = DataResponse(
statusCode: 201,
statusMessage: "created",
contentType: "application/xml",
headers: [("X-Foo-Bar", "My header")]
) { (environ, sendData) in
sendData(Data("<xml>who uses xml nowadays?</xml>".utf8))
}
Please notice, unlike sendBody
for SWSGI, sendData
only expects to be called once with the whole chunk of data.
JSONResponse
Almost identical to DataResponse
, except it takes Any
instead of bytes and dump the object as JSON format and response it for you. For example:
router["/api/v2/users"] = JSONResponse() { _ -> Any in
return [
["id": "01", "name": "john"],
["id": "02", "name": "tom"]
]
}
DelayResponse
DelayResponse
is a decorator response that delays given response for a while. In real-world, there will always be network latency, to simulte the latency, DelayResponse
is very helpful. To delay a response, just do
router["/api/v2/users"] = DelayResponse(JSONResponse(handler: { _ -> Any in
return [
["id": "01", "name": "john"],
["id": "02", "name": "tom"]
]
}))
By default, it delays the response randomly. You can modify it by passing delay
parameter. Like, say if you want to delay it for 10 seconds, then here you do
router["/api/v2/users"] = DelayResponse(JSONResponse(handler: { _ -> Any in
return [
["id": "01", "name": "john"],
["id": "02", "name": "tom"]
]
}), delay: .delay(10))
The available delay options are
- .random(min: TimeInterval, max: TimeInterval) delay random, it's also the default one as .random(min: 0.1, max: 3)
- .delay(seconds: TimeInterval) delay specific period of time
- .never delay forever, the response will never be returned
- .none no delay, i.e. the response will be returned immediately
DataReader
To read POST body or any other HTTP body from the request, you need to use swsgi.input
function provided in the environ
parameter of SWSGI. For example, you can do it like this
router["/api/v2/users"] = JSONResponse() { environ -> Any in
let input = environ["swsgi.input"] as! SWSGIInput
input { data in
// handle the data stream here
}
}
It's not too hard to do so, however, the data comes in as stream, like
- "first chunk"
- "second chunk"
- ....
- "" (empty data array indicates EOF)
In most cases, you won't like to handle the data stream manually. To wait all data received and process them at once, you can use DataReader
. For instance
router["/api/v2/users"] = JSONResponse() { environ -> Any in
let input = environ["swsgi.input"] as! SWSGIInput
DataReader.read(input) { data in
// handle the whole data here
}
}
JSONReader
Like DataReader
, besides reading the whole chunk of data, JSONReader
also parses it as JSON format. Herer's how you do
router["/api/v2/users"] = JSONResponse() { environ -> Any in
let input = environ["swsgi.input"] as! SWSGIInput
JSONReader.read(input) { json in
// handle the json object here
}
}
URLParametersReader
URLParametersReader
waits all data to be received and parses them all at once as URL encoding parameters, like foo=bar&eggs=spam
. The parameters will be passed as an array key value pairs as (String, String)
.
router["/api/v2/users"] = JSONResponse() { environ -> Any in
let input = environ["swsgi.input"] as! SWSGIInput
URLParametersReader.read(input) { params in
// handle the params object here
}
}
You can also use URLParametersReader.parseURLParameters
to parse the URL encoded parameter string if you want. Just do it like
let params = URLParametersReader.parseURLParameters("foo=bar&eggs=spam")
Install
CocoaPods
To install with CocoaPod, add Embassy to your Podfile:
pod 'EnvoyAmbassador', '~> 4.0'
Carthage
To install with Carthage, add Ambassador to your Cartfile:
github "envoy/Ambassador" ~> 4.0
Please notice that you should import Ambassador
instead of EnvoyAmbassador
. We use EnvoyAmbassador
for Cocoapods simply because the name Ambassador
was already taken.
Package Manager
To do this, add the repo to Package.swift
, like this:
import PackageDescription
let package = Package(
name: "AmbassadorExample",
dependencies: [
.package(url: "https://github.com/tlk/Ambassador", from: "4.0.5"),
]
)