kitura / kitura

A Swift web framework and HTTP server.

A Swift Web Framework and HTTP Server

Summary

Kitura is a web framework and web server that is created for web services written in Swift. For more information, visit www.kitura.dev.

Table of Contents

• Summary
• Features
• Getting Started
• Contributing to Kitura
• Community

Features

• URL routing (e.g., GET, POST, PUT, DELETE, PATCH)
• Codable routing
• URL parameters
• Static file serving
• FastCGI support
• SSL/TLS support
• Pluggable middleware

Getting Started

Visit https://www.kitura.dev for a Getting Started guide, tutorials, and API reference documentation.

Contributing to Kitura

All improvements to Kitura are very welcome! Here's how to get started with developing Kitura itself.

1. Clone this repository.

$ git clone https://github.com/Kitura/Kitura

2. Build and run tests.

$ swift test

You can find more info on contributing to Kitura in our contributing guidelines.

Notes

• Swift-NIO is now the default network engine via the Kitura-NIO package. If for some reason you require the old Kitura-net package, you can still enable it by setting an environment variable KITURA_NIO=0 during build.
• Most Kitura packages have been updated to require at least Swift 5.2 in order to maintain backward compatibility.

Community

We love to talk server-side Swift, and Kitura. Join our Slack to meet the team!

kitura's Issues

[CLOSED] Create sample code for Phoenix inside the Phoenix repo

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 23:03 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/5

---

[CLOSED] Create a wrapper around libdispatch to produce pre-processing flags dynamically

Issue by ricardo-olivieri
Monday Jan 11, 2016 at 15:55 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/29

---

Make sure to remove the custom libdispatch.

Add to the Kitura-router the ability to add error handlers

Add to the Kitura router the ability to add error handlers which can be invoked when a handler or middleware indicates that it encountered an error. This error handler could be the part of a server application that creates and returns the error page.

[CLOSED] Switch over to start using ETSockets.

Issue by rfdickerson
Thursday Jan 14, 2016 at 01:44 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/43

---

Phoenix server under Linux does not always gracefully close the socket: Since the socket is not closed always when Ctrl-C is pressed, it causes subsequent runs to not be able to bind to port 8090. We should investigate ways to ensure the socket is closed on termination.

Add to the ContentType "helper" in Kitura-router more content types by integrating SwiftyJSON

The Kitura-router has a helper class that deals with Content-Type headers and mime types.

Currently it supports a small set of hard coded content types.

This list needs to be externalized, akin to what is done in similar functionality in Express. In fact it would be good to adopt their external file of content types and file extensions.

A major issue is where to place this file and how does it stay with the executable if one moves it

[CLOSED] Update travis.yml file to use docker

Issue by ricardo-olivieri
Tuesday Jan 12, 2016 at 18:42 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/38

---

File has been updated accordingly but docker command cannot be found. I just opened a Travis CI issue to track this: https://github.ibm.com/Whitewater/TravisCI/issues/7

Start creating an easy to use Redis API

Issue by KALLNER
Thursday Jan 07, 2016 at 10:16 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/12

---

This is the start of an easy to use Swift based API for Redis, with type safe parameters and callbacks.

[CLOSED] rework net and router modules to get them to compile in linux

Issue by dfirsht
Friday Jan 08, 2016 at 22:25 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/26

---

[CLOSED] Compile custom libdispatch library on OS X

Issue by dfirsht
Friday Jan 15, 2016 at 19:32 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/49

---

While attempting to compile Chris' custom libdispatch, I ran into an issue with following the install instructions. I don't know what to fill in for the options that end with source=/path/to/10.11.0/... The code that depends on the custom library has been commented out for now

Determine how to only import Kitura in the sample code instead of importing the individual modules

Issue by ricardo-olivieri
Monday Jan 11, 2016 at 16:10 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/30

---

Cleanup or remove xcproj file

Issue by dfirsht
Wednesday Jan 13, 2016 at 17:00 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/40

---

Currently Phoenix does not conform to the xcode project structure and will not compile in Xcode. We should make it compilable or remove the xcproj file entirely

[CLOSED] Create docker image for CI builds

Issue by ricardo-olivieri
Tuesday Jan 12, 2016 at 06:00 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/36

---

Convert HTTP protocol implementation from libcurl to NSURLSession and other native networking classes

Issue by rfdickerson
Thursday Jan 14, 2016 at 19:35 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/48

---

Just a reminder to convert this code over when NSURLSession and others are implemented.

Add support for path pattern matching (multiplicity)

Issue by ricardo-olivieri
Monday Jan 11, 2016 at 16:43 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/32

---

Samuel will add a link to this work item with further details.

Determine if NSOperationQueue could be used for executing async functions in a predefined order

Issue by ricardo-olivieri
Wednesday Jan 13, 2016 at 20:55 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/42

---

This is an exploratory task (dependent on the libdispatch library) The following is just pseudocode for reference:

backgroundQueue.addOperationWithBlock(clousure1);
backgroundQueue.addOperationWithBlock(clousure2);

Where closure1 is the handler in the router code for processing the http request and http response (code provided at the app level) and closure2 is the next() closure that is used internally by the middleware router layer (not the app).

See the following links for further details:
https://tetontech.wordpress.com/2014/06/30/swift-nsoperationqueues-and-threading/
https://thatthinginswift.com/background-threads/
https://developer.apple.com/library/mac/documentation/Cocoa/Reference/NSOperationQueue_class/#//apple_ref/occ/instm/NSOperationQueue/addOperationWithBlock

[CLOSED] Get libcurl and libhttpParser helpers to compile (a and dylib) using a build script. (interim solution)

Issue by rfdickerson
Wednesday Jan 13, 2016 at 00:25 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/39

---

Previously, we had httpParserHelper.dylib checked into the repository. However, since it might be bad practice to check in the build dylib into the repository, and we will need a .so file in that directory as well, we should consider how to build this with Swift Package Manager.

We can compile the httpParserHelper "shim" using:

clang -c utils.c -shared -o libhttpParserHelper.so

So that the modulemap can find and link httpParserHelper.so. I think we have 3 options:

1. Check in to the repository the Darwin dylib and the Linux shared object file.
2. Figure out how to get Swift Package Manager to build the C code
3. Move the utils.c and utils.h to another repository and have it use a Makefile to build the shim.

Convert regular expression matching from pcre2 to NSRegularExpression

Issue by rfdickerson
Thursday Jan 14, 2016 at 19:17 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/47

---

This is just to remind us that once Foundation has been finished, we can use NSRegularExpression for native regex matching instead of using an external C library.

Here is the current unimplemented NSRegularExpression

Create a Kitura-router middleware for session management

Issue by KALLNER
Thursday Jan 07, 2016 at 10:15 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/11

---

Create a Kitura-router middleware for session management.

The method used for session storage should be pluggable.

The initial one, which is probably the only built-in one, is for in-memory storage.

A nice session storage to have would be around Redis and some No-SQL DB

[CLOSED] Automate build process for Phoenix for continuous integration (CI)

Issue by ricardo-olivieri
Thursday Jan 07, 2016 at 20:08 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/17

---

More than likely we can use Travis for this: https://travis.innovate.ibm.com/auth

Move from the forked version of libdispatch (maintained by Chris) and use the official one from apple

Issue by rfdickerson
Thursday Jan 07, 2016 at 21:48 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/19

---

Currently, the swiftc cannot interpret the proprocessing macros inside of header files such as #define's. For example, I can build my program and builds and can execute,

import CDispatch

let q = dispatch_get_main_queue()
let t = dispatch_time(DISPATCH_TIME_NOW, Int64(5*NSEC_PER_SEC))

dispatch_after(t, q, {
    print("hello")
})

dispatch_main()

The Makefile is:

DISPATCH_LIBRARY=-Xcc -fblocks -ldispatch -lpthread -Xlinker -lBlocksRuntime -I Packages/CDispatch-1.0.2

all: main.o

main.o: main.swift
    swiftc main.swift ${DISPATCH_LIBRARY}


clean:
    rm *.o

The executable runs, waits 5 seconds, and prints hello.

However, if I try to use

DISPATCH_QUEUE_CONCURRENT

The Swift compiler cannot resolve that symbol. This symbol is really a #define, and I suspect the Swift frontend compiler cannot resolve the identifier in any typesafe way since it's just a simple code-replacement.

#define DISPATCH_QUEUE_CONCURRENT \
        DISPATCH_GLOBAL_OBJECT(dispatch_queue_attr_t, \
        _dispatch_queue_attr_concurrent)

A proposed solution to this problem would be to add to a custom header file a new definition of DISPATCH_QUEUE_CONCURRENT to instead be a constant global variable instead of a C preprocessor directive.

[CLOSED] Create develop branch

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 23:24 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/8

---

Investigate how to bind variables defined in Bluemix to a Swift application

Issue by ricardo-olivieri
Thursday Jan 14, 2016 at 16:49 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/46

---

[CLOSED] Compile list of libraries/frameworks used in the NodeJS server implementation for Swift Sandbox

Issue by ricardo-olivieri
Thursday Jan 07, 2016 at 02:28 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/9

---

Create a static file serving middleware for Kitura-router

Issue by KALLNER
Thursday Jan 07, 2016 at 10:18 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/13

---

[CLOSED] As an interim solution, move the following dependencies into the Phoenix repo: HiRedis, Pcre2, HttpParserHelper, and CurlHelpers.

Issue by ricardo-olivieri
Friday Jan 08, 2016 at 19:08 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/25

---

Given that the current version of Package Manager does not support the functionality we need to successfully build the project on linux, in the meantime, we plan to move these dependencies into the same repo as this project for ease of development.

[CLOSED] Enable the PhoenixRedis repo to compile (including test cases)

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 23:04 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/6

---

Also, let's move the test cases for Redis into the new repo for Redis.

[CLOSED] Use the updated version of the swift package manager that supports compilation flags

Issue by ricardo-olivieri
Tuesday Jan 12, 2016 at 16:11 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/37

---

Today, the team decided to use a forked version of the swift package manager that supports compilation flags instead of using custom make files.

This will require an additional step after the installation of the swift compiler:
-Cloning forked version of the swift package manager.
-Building and installing the swift package manager.

We will also need to implement this logic as part of the docker image.

[CLOSED] Compile Phoenix (and all its dependencies) using the Swift package manager on linux

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 22:32 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/1

---

Compile the Phoenix project and all its dependencies using the Swift package manager.

Add support for websockets

Issue by ricardo-olivieri
Monday Jan 11, 2016 at 16:50 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/33

---

Implement Swift-based server version for the Swift Sandbox

Issue by ricardo-olivieri
Thursday Jan 07, 2016 at 22:24 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/20

---

Monitor file system for changes in binaries and load them

Issue by ricardo-olivieri
Tuesday Jan 12, 2016 at 00:18 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/35

---

Similar to WAS Liberty and NodeJS, if there are changes in the binary files, these should be detected and loaded.

[CLOSED] Create makefile for all dependencies for linux

Issue by ricardo-olivieri
Thursday Jan 07, 2016 at 21:24 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/18

---

Given the current limitation we see in Package Manager (i.e. no capabilities to support compilation flags), we are creating a makefile to compile the different dependencies that otherwise would be imported using Package Manager.

[CLOSED] Reenable compilation on OS X

Issue by dfirsht
Wednesday Jan 13, 2016 at 17:01 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/41

---

The changes made to compile on linux broke OS X compatibility. We should enable compilation on both platforms

Create a router middleware for compression of data sent to requestor

Create a Kitura-Router middleware that supports the common forms of over the wire compression.

For the gzip compression we should probably use zLib.

This requires some work in the base router to APIs to add "plugins" that operate in the read/write path.

• Read Accept-Encoding from RouterRequest "gzip, deflate"
• Add Content-Encoding to RouterResponse: gzip
• Set correct content-length

[CLOSED] Investigate visibility issue with method and instance variable modifiers on linux (not compiling)

Issue by ricardo-olivieri
Thursday Jan 14, 2016 at 15:57 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/45

---

We were able to get the build to work. For some reason the closed property in FileDescriptor in IO module is being called in the net module.

public private(set) var closed = false

clang ./build/net.o -shared -o ./build/libnet.so
./build/net.o:(.data.rel+0x1200): undefined reference to `_TFC2io14FileDescriptors6closedSb'
./build/net.o:(.data.rel+0x1208): undefined reference to `_TFC2io14FileDescriptorm6closedSb'
/usr/bin/ld: ./build/libnet.so: hidden symbol `_TFC2io14FileDescriptorm6closedSb' isn't defined

Changing it to public is a temporary workaround:

public var closed = false

Deploy Kitura as the starter sample app for the Swift runtime

Issue by ricardo-olivieri
Thursday Jan 07, 2016 at 22:45 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/21

---

https://github.com/cloudfoundry-community/swift-buildpack

Enable the PhoenixCouchDB repo to compile (including test cases)

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 23:06 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/7

---

[CLOSED] Use Samuel's xctest framework version for implementation of automated test cases

Issue by ricardo-olivieri
Monday Jan 11, 2016 at 16:19 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/31

---

[CLOSED] Update Makefile so that it builds the C helper shims (as static library) and then invokes SPM.

Issue by ricardo-olivieri
Monday Jan 18, 2016 at 22:41 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/50

---

Given that we now can compile using the swift package manager, let's then update the make file so it has a target that does only what spm cannot do as of now.

[CLOSED] Create test cases for Phoenix inside the Phoenix repo

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 23:01 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/4

---

[CLOSED] rework net and router modules to get them to compile in linux

Issue by dfirsht
Friday Jan 08, 2016 at 22:27 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/27

---

[CLOSED] Undo work done by issue #25

Issue by ricardo-olivieri
Monday Jan 11, 2016 at 15:53 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/28

---

Let's keep the following dependencies in separate repos: HiRedis, Pcre2, HttpParserHelper, and CurlHelpers. Even though they are in separate repos, we can still make changes locally on our system to test the code without having so push, pull, and test.

[CLOSED] Set up Docker Hub account and upload initial docker image for Phoenix (Travis CI)

Issue by ricardo-olivieri
Monday Jan 11, 2016 at 20:34 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/34

---

https://hub.docker.com/

Docker hub is a public registry maintained by Docker.

Add to Kitura-router improved cookie support

Today one can send and receive cookies in Kitura-router via Cookie headers.

It would be nice to have better APIs for doing this, such as:

1. A cookies property in the RouterRequest class, which would in a lazy fashion parse all of the incoming headers looking for cookies.
2. A setCookie function in the RouterResponse class to add cookies to the response.
3. Easier ability to extract cookies for Http.ClientRequests
4. "CookieJar" support Http.ClientRequests, to automate the resending of Cookies received in earlier requests.

Our Cookie class in our APIs should NSCookie from foundation, which is already pure Swift.

[CLOSED] Replace sockets library with ETSockets

Issue by dfirsht
Thursday Jan 14, 2016 at 15:45 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/44

---

[CLOSED] Cannot compile HttpParser Wrapper code on linux

Issue by ricardo-olivieri
Friday Jan 08, 2016 at 16:20 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/24

---

At first glance, there seems to be Objective-C code in the HttpParser code. Daniel is investigating this and will follow up with Samuel.

[CLOSED] Improve the PhoenixTestingFramework for Continuous Integration

Issue by KALLNER
Friday Jan 08, 2016 at 12:13 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/23

---

1. Currently the binaries created by PhoenixTestingFramework exit after an error is detected.

   For continuous integration, the needed functionality is that when an assertion fails, the test running s stopped, while the rest of the tests in that test case and any other tests cases are still executed.

2. The current XCTest code on which the PhoenixTestingFoundation is based, doesn't have the XCTestExpectation based APIs, neither the class, not the APIs in XCTestCase.

   This makes it hard to test asynchronous APIs.

Complete the easy to use Swift based Redis API

Issue by KALLNER
Friday Jan 08, 2016 at 11:57 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/22

---

Add easy to use APIs for Redis List, Set, Sorted set, Transactional List, Transactional Set, and Transactional Sorted set operations.

Get SwiftyJSON to compile on linux (or remove dependency on it)

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 22:58 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/2

---

Some of the Swfit code in the net module depends on the SwiftyJSON library. As of now, we cannot get the SwiftyJSON library to compile.

This issue may have to be revisited. For instance, an alternative to SwiftyJSON is the following library (which is written entirely in Swift): https://github.com/Zewo/JSON. Another alrernative is to simply eliminate any dependencies on 3rd party Swift libraries.

Probably the benefits of using SwiftyJSON are negligible. For instance, when compared to the Gson library, SwiftyJSON does not even provide a quarter of the functionality Gson provides.

[CLOSED] Generate linux documentation for Phoenix

Issue by ricardo-olivieri
Wednesday Jan 06, 2016 at 22:59 GMT
Originally opened as https://github.ibm.com/ibmswift/Phoenix/issues/3

---