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/envoy/Ambassador.git",
from: "4.0.0"),
]
)
770 Jan 8, 2023
1.9k Dec 22, 2022
925 Nov 17, 2022
22.4k Jan 2, 2023
7.6k Jan 6, 2023
2k Dec 5, 2022
908 Dec 2, 2022
316 Oct 6, 2022
46 Jan 29, 2022
35 Apr 18, 2022
10.2k Dec 29, 2022
246 Sep 9, 2022
981 Dec 29, 2022
850 Dec 2, 2022
245 Dec 30, 2022
52 Oct 26, 2022
377 Jun 29, 2022
68 Jul 25, 2022
745 Jan 3, 2023