Hexaville是一个用于Swift现代化的serverless web应用引擎和框架

Hexaville

Hexaville - The Serverless Framework using AWS Lambda + ApiGateway etc as a back end. Build applications comprised of microservices that run in response to events, auto-scale for you, and only charge you when they run. This lowers the total cost of maintaining your apps, enabling you to develop more, faster.

It's the greatest motivation to help many Swift and mobile application developers with rapid server side development and low cost operation.

Supported Cloud Servises

AWS Lambda(Node.js 8.1 Runtime) + APIGateway Google Cloud Function

Pre-Required

Docker: using for builiding swift applicationserverless: using for deployment

Deployment Engine

0.x: fullscratch deployment with aws-sdk-swift1.x or later: serverless framework

Plugins

HexavilleAuth: A pluggable framework for providing various authentication methods(OAuth, simple password based etc.)DynamodbSessionStore: Dynamodb Session StoreRedisSessionStore: Redis Session Store

Recommended Database Clients

DynamoDB: A DynamoDB typesafe client in AWSSDKSwift

Example Application for Hexaville

HexavilleTODOExample has following practical examples for Hexaville application.

User authentication with GitHub's OAuthData persistence with DynamoDBDynamic HTML Rendering

Quick Start

Install Docker for mac

Install Docker for mac from here, If you haven't installed yet.

Install Hexaville from Script(Highly recommended)

curl -L https://rawgit.com/noppoMan/Hexaville/master/install.sh | bash

The script clones the hexaville repository to ~/.hexaville and adds the source line to your profile (~/.zshrc, or ~/.bashrc).

export PATH="$PATH:$HOME/.hexaville"

source your profile and then, type hexaville

source ~/.bashrchexaville

Install Hexaville from Source

git clone https://github.com/noppoMan/Hexaville.gitcd Hexavilleswift build

and then, should link Hexaville executable path to /usr/local/bin or something like that.

Create a Project

Usage: hexaville generate

hexaville generate Hello --dest /path/to/your/app

swift-tools-version

You can specify swift-tools-version for the new project with --swift-tools-version option. Current default tool version is 5.1

If the tool version is higher than 3.1, layouts and definiations of Package.swift are refined.

e.g.

# swift.version will be 5.1hexaville generate Hello# swift.version will be 5.0hexaville generate Hello --swift-tools-version 5.0# swift.version will be swift-4.0-DEVELOPMENT-SNAPSHOT-2017-08-04-ahexaville generate Hello --swift-tools-version swift-4.0-DEVELOPMENT-SNAPSHOT-2017-08-04-a

Open your project with Xcode

swift package generate-xcodeprojopen *.xcodeproj

The created codes in the project is example snippet of https://github.com/noppoMan/HexavilleFramework

HexavilleFramework is an express like micro framework for Hexaville.

The syntax is following.

import HexavilleFrameworklet app = HexavilleFramework()app.use(RandomNumberGenerateMiddleware())let router = Router()router.use(.GET, "/") { request, context in let htmlString = "Welcome to Hexaville!" return Response(headers: ["Content-Type": "text/html"], body: htmlString)}app.use(router)try app.run()

Deploy Your Project

Hexaville depends on serverless at deployment.

See Install Guide: https://serverless.com/framework/docs/getting-started/

Packaging hexaville application

hexaville package command does the following.

build a swift application on the docker(Ubuntu14.04) to create the ELF that is executed on servrless environment.zip ELF, swift standard libraries, runtime program and assets

cd /path/to/your/apphexaville package

Deploying to the cloud

serverless deploy --stage staging

Default serverless.yml that is created by hexaville generate has only staging and production environment. If you'd like to add other environments, please edit severless.yml manually.

Troubleshooting

1. What is executableTarget in Hexavillefile.yml?

executableTarget is a name that specified in products(name: 'executableTarget') on Package.swift. In following case, it's a my-app not MyApp.

let package = Package( name: "MyApp", products: [ .executable(name: "my-app", targets: ["MyApp"]) ], ....)

Access to your api resources

curl https://xxxxxx.execute-api.ap-northeast-1.amazonaws.com/staging/

or access the endpoint from Browser.

Binary Media Types

Currenty Hexaville supports following binary media types

image/*application/octet-streamapplication/x-protobufapplication/x-google-protobuf

How to get binary content?

Threr are two rules to respond to the binary content in the routing handler.

RowBinaryData should be encoded as Base64Adding "Content-Type": "{BinaryMediaType}" to the response headers

router.use(.get, "/some_image") { request, context in let imageData = Data(contentsOf: URL(string: "file:///path/to/your/image.jpeg")!) return Response(headers: ["Content-Type": "image/jpeg"], body: imageData.base64EncodedData())}

Getting binary content from Hexaville, need to send request that includes Content-Type: {BinaryMediaType} and Accept: {BinaryMediaType} headers

curl --request GET -H "Accept: image/jpeg" -H "Content-Type: image/jpeg" https://yourdomain.com/staging/random_image# ????JFIF``??;CREATOR: gd-jpeg v1.0 (using IJG JPEG v62), quality = 70# ??C###### #%$""!&+7/&)4)!"0A149;>>>%.DIC;??C### ;("(;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;???"??# ............

How to debug?

You can debug your application with the HexavilleFramework's builtin web server with serve command.

/path/to/your/app/.build/debug/Hello serve# => Hexaville Builtin Server started at 0.0.0.0:3000

Advanced Settings

Environment Variables

See: https://serverless.com/framework/docs/providers/aws/guide/variables/

VPC and Security Groups

See: https://serverless.com/framework/docs/providers/aws/guide/functions#vpc-configuration

Swift Versioning and Build Configuration

You can configure swift versioning and build configuration in swift directive

default swift version is 5.1default build configuration is debug

swift: version: 5.1 #format should be major.minor.[patch] or valid SWIFT DEVELOPMENT-SNAPSHOT name buildOptions: configuration: release

Use SWIFT DEVELOPMENT-SNAPSHOT

You can also specify SWIFT DEVELOPMENT-SNAPSHOT as internal using swift version. The format is same as swiftenv version

e.g.

swift: version: swift-4.0-DEVELOPMENT-SNAPSHOT-2017-08-04-a

Static Assets

You can also upload static assets. Just put your assets into the assets directory in your project root.

Loading Static Assets in Application

You can load static assets from local filesystem with AssetLoader

import HexavilleFrameworklet data = try AssetLoader.shared.load(fileInAssets: "/html/index.html")

Against for the Severless weak points

Too many connections will created between Serveless functions and RDB, Cache Server

Almost Web develoeprs access RDB, Cache Server through connection pooling from your applications. It's a one of the best practice for reducing connection for them. But Functions that are called on Serverless is like a Pre-Folk. It means can not have connection pooling and the number of connection of Database is same as number of functions that are executed in parallel.

In that case, Hexaville provides you to connection pooling mechanism with hexaville-tcp-proxy-server.

hexaville-tcp-proxy-server is not only a Proxy Sever But Connection Pooling Server. See the detail to see README.

Cold Start

There are several third parties's libraries to againt cold start on github.

The major one is serverless-plugin-warmup

How to update Hexaville CLI Version?

$ rm -rf ~/.hexaville$ curl -L https://rawgit.com/noppoMan/Hexaville/master/install.sh | bash$ hexaville version

Contributing

All developers should feel welcome and encouraged to contribute to Hexaville, see our getting started document here to get involved.

To contribute a feature or idea to Hexaville, submit an issue and fill in the template. If the request is approved, you or one of the members of the community can start working on it.

If you find a bug, please submit a pull request with a failing test case displaying the bug or create an issue.

If you find a security vulnerability, please contact yuki@miketokyo.com as soon as possible. We take these matters seriously.

Related Articles

Serverless Server Side Swift with HexavilleServerless Server Side Swift@Builderscon Tokyo 2017WEB+DB PRESS Vol.101

License

Hexaville is released under the MIT license. See LICENSE for details.

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。