• Stars
    star
    176
  • Rank 216,987 (Top 5 %)
  • Language
    Swift
  • License
    MIT License
  • Created over 8 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Super lightweight web framework in Swift based on SWSGI

Ambassador

Build Status CocoaPods Code Climate Issue Count GitHub license

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"),
    ]
)

More Repositories

1

Embassy

Super lightweight async HTTP server library in pure Swift runs in iOS / MacOS / Linux
Swift
576
star
2

Engineering

Repo for principles, job bands, coding challenges, and anything else we're ok sharing w/ the world.
102
star
3

eventbrite

eventbrite ruby gem for v3 API.
Ruby
31
star
4

polarwind

Envoy's product component library
JavaScript
21
star
5

gongpi

Rings the gong in the Envoy office every time we make a sale.
Shell
18
star
6

react-native-key-commands

iOS UIKeyCommand native component for React Native
Objective-C
13
star
7

ReactiveAlamofire

Alamofire 3 integration for ReactiveCocoa 4
Swift
11
star
8

BRPtouchPrinterKit

Brother Print SDK for iPhone/iPad
Objective-C
11
star
9

lambda-convert

AWS Lambda powered drop-in replacement for ImageMagick convert command line tool
Ruby
10
star
10

ember-route-constraints

Route navigation constraints for Ember apps.
JavaScript
8
star
11

JSONAPIModel

Simple JSONAPI parser / serializer and data model
Swift
7
star
12

ENVLicenseParser

A library for parsing PDF417 strings
Objective-C
5
star
13

ready-to-reopen

Our employee portal for returning to the office
HTML
5
star
14

tap-clubhouse

Singer tap for Clubhouse
Python
5
star
15

react-native-signature-pad

Signature pad component for React Native
Objective-C
4
star
16

loglevel-file-logger

File logger for loglevel
TypeScript
4
star
17

example-embassy

Embassy example app for Linux
Swift
3
star
18

doorkeeper-device_flow

Ruby
3
star
19

historedis

Create Histograms in Redis
Ruby
2
star
20

react-native-transform-view

TypeScript
2
star
21

express-envoy-auth

Middleware to authenticate an Express application with Envoy
JavaScript
2
star
22

ember-cli-deploy-gcs-index

An ember-cli-deploy plugin to deploy ember-cli's bootstrap index file to Google Cloud Storage.
JavaScript
2
star
23

tap-chargebee

Singer.io tap for extracting data from the Chargebee API
Python
2
star
24

homebrew-tools

Ruby
2
star
25

install-helm-docs

Github Action to install helm docs in CI flow
2
star
26

DoorPi

Ding Dong! Someone is at the front door.
Python
2
star
27

ibeacon-experiment-iphone

Simple iPhone app for ibeacon experiments and investigations
Swift
1
star
28

dd-java-agent-buildpack

Heroku Datadog Java Agent Buildpack
Shell
1
star
29

kt-proj-presetup

The project is a Heroku Custom Buildpack to do the required tasks for Kotlin projects.
Shell
1
star
30

envoy-plugin-example-access-control

This is an example Access Control integration with Envoy's integration builder.
JavaScript
1
star
31

envoy.css

Envoy's custom CSS library
CSS
1
star
32

tap-slack

Singer.io tap for extracting data from the Slack Web API
Python
1
star
33

react-native-ibeacon

React Native iOS native module for iBeacon (only support advertising for now)
Objective-C
1
star
34

LaserDisc

Swift
1
star