{"id":15293705,"url":"https://github.com/noppoman/hexaville","last_synced_at":"2025-04-13T13:25:30.848Z","repository":{"id":63919321,"uuid":"91464199","full_name":"noppoMan/Hexaville","owner":"noppoMan","description":"The modern serverless web application engine and framework for Swift","archived":false,"fork":false,"pushed_at":"2019-09-27T08:31:25.000Z","size":269106,"stargazers_count":126,"open_issues_count":12,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-27T04:23:11.289Z","etag":null,"topics":["api-gateway","aws","lambda","server-side-swift","serverless","swift","swift4"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noppoMan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-16T13:53:36.000Z","updated_at":"2025-02-11T22:14:32.000Z","dependencies_parsed_at":"2023-01-14T14:00:20.710Z","dependency_job_id":null,"html_url":"https://github.com/noppoMan/Hexaville","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noppoMan%2FHexaville","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noppoMan%2FHexaville/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noppoMan%2FHexaville/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noppoMan%2FHexaville/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noppoMan","download_url":"https://codeload.github.com/noppoMan/Hexaville/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501916,"owners_count":21114681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","aws","lambda","server-side-swift","serverless","swift","swift4"],"created_at":"2024-09-30T16:50:54.041Z","updated_at":"2025-04-13T13:25:30.826Z","avatar_url":"https://github.com/noppoMan.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hexaville\n\n[\u003cimg src=\"https://travis-ci.org/noppoMan/Hexaville.svg?branch=master\"\u003e](https://travis-ci.org/noppoMan/Hexaville) \u003cimg src=\"https://camo.githubusercontent.com/20738bb8299d3bba047a2257835816c996f32dce/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6f732d6d61634f532d677265656e2e7376673f7374796c653d666c6174\"\u003e \u003cimg src=\"https://camo.githubusercontent.com/e03f50adf26f5ec614c12cfd26146990e82f72ce/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6f732d6c696e75782d677265656e2e7376673f7374796c653d666c6174\"\u003e [![codebeat badge](https://codebeat.co/badges/9f87684c-8392-488e-807c-2c9fae4350fd)](https://codebeat.co/projects/github-com-noppoman-hexaville-master)\n\nHexaville - The Serverless Framework using AWS Lambda + ApiGateway etc as a back end.\nBuild 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.\n\nIt's the greatest motivation to help many Swift and mobile application developers with rapid server side development and low cost operation.\n\n### Supported Cloud Servises\n* [x] AWS Lambda(Node.js 8.1 Runtime) + APIGateway\n* [ ] Google Cloud Function\n\n### Pre-Required\n\n* [Docker](https://www.docker.com/): using for builiding swift application\n* [serverless](https://serverless.com/): using for deployment\n\n### Deployment Engine\n\n* 0.x: fullscratch deployment with [aws-sdk-swift](https://github.com/swift-aws/aws-sdk-swift)\n* 1.x or later: [serverless framework](https://serverless.com/)\n\n## Plugins\n* [HexavilleAuth](https://github.com/Hexaville): A pluggable framework for providing various authentication methods(OAuth, simple password based etc.)\n* [DynamodbSessionStore](https://github.com/Hexaville/DynamodbSessionStore): Dynamodb Session Store\n* [RedisSessionStore](https://github.com/Hexaville/RedisSessionStore): Redis Session Store\n\n## Recommended Database Clients\n* [DynamoDB](https://github.com/swift-aws/aws-sdk-swift): A DynamoDB typesafe client in AWSSDKSwift\n\n## Example Application for Hexaville\n\n[HexavilleTODOExample](https://github.com/Hexaville/HexavilleTODOExample) has following practical examples for Hexaville application.\n\n* User authentication with GitHub's OAuth\n* Data persistence with DynamoDB\n* Dynamic HTML Rendering\n\n# Quick Start\n\n## Install Docker for mac\nInstall Docker for mac from [here](https://docs.docker.com/docker-for-mac/install/), If you haven't installed yet.\n\n## Install Hexaville from Script(Highly recommended)\n\n```\ncurl -L https://rawgit.com/noppoMan/Hexaville/master/install.sh | bash\n```\n\nThe script clones the hexaville repository to `~/.hexaville` and adds the source line to your profile (~/.zshrc, or ~/.bashrc).\n```\nexport PATH=\"$PATH:$HOME/.hexaville\"\n```\n\n`source` your profile and then, type `hexaville`\n\n```sh\nsource ~/.bashrc\nhexaville\n```\n\n## Install Hexaville from Source\n```sh\ngit clone https://github.com/noppoMan/Hexaville.git\ncd Hexaville\nswift build\n```\nand then, should link Hexaville executable path to /usr/local/bin or something like that.\n\n## Create a Project\n\n`Usage: hexaville generate \u003cprojectName\u003e`\n\n```sh\nhexaville generate Hello --dest /path/to/your/app\n```\n\n### swift-tools-version\nYou can specify swift-tools-version for the new project with `--swift-tools-version` option.\nCurrent default tool version is `5.1`\n\nIf the tool version is higher than 3.1, layouts and definiations of `Package.swift` are refined.\n\n**e.g.**\n```sh\n# swift.version will be 5.1\nhexaville generate Hello\n\n# swift.version will be 5.0\nhexaville generate Hello --swift-tools-version 5.0\n\n# swift.version will be swift-4.0-DEVELOPMENT-SNAPSHOT-2017-08-04-a\nhexaville generate Hello --swift-tools-version swift-4.0-DEVELOPMENT-SNAPSHOT-2017-08-04-a\n```\n\n## Open your project with Xcode\n\n```\nswift package generate-xcodeproj\nopen *.xcodeproj\n```\n\nThe created codes in the project is example snippet of https://github.com/noppoMan/HexavilleFramework\n\nHexavilleFramework is an express like micro framework for Hexaville.\n\nThe syntax is following.\n```swift\nimport HexavilleFramework\n\nlet app = HexavilleFramework()\n\napp.use(RandomNumberGenerateMiddleware())\n\nlet router = Router()\n\nrouter.use(.GET, \"/\") { request, context in\n    let htmlString = \"\u003chtml\u003e\u003chead\u003e\u003ctitle\u003eHexaville\u003c/title\u003e\u003c/head\u003e\u003cbody\u003eWelcome to Hexaville!\u003c/body\u003e\u003c/html\u003e\"\n    return Response(headers: [\"Content-Type\": \"text/html\"], body: htmlString)\n}\n\napp.use(router)\n\ntry app.run()\n```\n\n## Deploy Your Project\n\nHexaville depends on [serverless](https://serverless.com/) at deployment.\n\nSee Install Guide: https://serverless.com/framework/docs/getting-started/\n\n### Packaging hexaville application\n\n`hexaville package` command does the following.\n\n* build a swift application on the docker(Ubuntu14.04) to create the ELF that is executed on servrless environment.\n* zip ELF, swift standard libraries, runtime program and assets\n\n```sh\ncd /path/to/your/app\nhexaville package\n```\n\n### Deploying to the cloud\n\n```sh\nserverless deploy --stage staging\n```\n\nDefault serverless.yml that is created by `hexaville generate` has only staging and production environment.\nIf you'd like to add other environments, please edit severless.yml manually.\n\n### Troubleshooting\n\n**1. What is executableTarget in Hexavillefile.yml?**\n\n`executableTarget` is a name that specified in `products(name: 'executableTarget')` on Package.swift. In following case, it's a `my-app` not `MyApp`.\n\n```swift\nlet package = Package(\n    name: \"MyApp\",\n    products: [\n        .executable(name: \"my-app\", targets: [\"MyApp\"])\n    ],\n    ....\n)\n```\n\n## Access to your api resources\n```\ncurl https://xxxxxx.execute-api.ap-northeast-1.amazonaws.com/staging/\n```\n\nor access the endpoint from Browser.\n\n## Binary Media Types\n\nCurrenty Hexaville supports following binary media types\n\n* image/*\n* application/octet-stream\n* application/x-protobuf\n* application/x-google-protobuf\n\n### How to get binary content?\n\nThrer are two rules to respond to the binary content in the routing handler.\n* RowBinaryData should be encoded as Base64\n* Adding `\"Content-Type\": \"{BinaryMediaType}\"` to the response headers\n\n```swift\nrouter.use(.get, \"/some_image\") { request, context in\n    let imageData = Data(contentsOf: URL(string: \"file:///path/to/your/image.jpeg\")!)\n    return Response(headers: [\"Content-Type\": \"image/jpeg\"], body: imageData.base64EncodedData())\n}\n```\n\nGetting binary content from Hexaville, need to send request that includes `Content-Type: {BinaryMediaType}` and `Accept: {BinaryMediaType}` headers\n\n```sh\ncurl --request GET -H \"Accept: image/jpeg\" -H \"Content-Type: image/jpeg\" https://yourdomain.com/staging/random_image\n\n# ????JFIF``??;CREATOR: gd-jpeg v1.0 (using IJG JPEG v62), quality = 70\n# ??C\n#\n#\n#\n#\n#\n# #%$\"\"!\u0026+7/\u0026)4)!\"0A149;\u003e\u003e\u003e%.DIC\u003cH7=\u003e;??C\n#\n#\n# ;(\"(;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;???\"??\n# ............\n```\n\n\n## How to debug?\n\nYou can debug your application with the HexavilleFramework's builtin web server with serve command.\n\n```sh\n/path/to/your/app/.build/debug/Hello serve\n# =\u003e Hexaville Builtin Server started at 0.0.0.0:3000\n```\n\n# Advanced Settings\n\n## Environment Variables\n\nSee: https://serverless.com/framework/docs/providers/aws/guide/variables/\n\n## VPC and Security Groups\n\nSee: https://serverless.com/framework/docs/providers/aws/guide/functions#vpc-configuration\n\n## Swift Versioning and Build Configuration\n\nYou can configure swift versioning and build configuration in `swift` directive\n\n* default swift version is `5.1`\n* default build configuration is `debug`\n\n```yaml\nswift:\n  version: 5.1 #format should be major.minor.[patch] or valid SWIFT DEVELOPMENT-SNAPSHOT name\n  buildOptions:\n    configuration: release\n```\n\n### Use SWIFT DEVELOPMENT-SNAPSHOT\n\nYou can also specify SWIFT DEVELOPMENT-SNAPSHOT as internal using swift version.  \nThe format is same as [swiftenv version](https://swiftenv.fuller.li/en/latest/commands.html#version)\n\n**e.g.**\n```yaml\nswift:\n  version: swift-4.0-DEVELOPMENT-SNAPSHOT-2017-08-04-a\n```\n\n## Static Assets\n\nYou can also upload static assets.\nJust put your assets into the `assets` directory in your project root.\n\n### Loading Static Assets in Application\n\nYou can load static assets from local filesystem with `AssetLoader`\n\n```swift\nimport HexavilleFramework\n\nlet data = try AssetLoader.shared.load(fileInAssets: \"/html/index.html\")\n```\n\n# Against for the Severless weak points\n\n## Too many connections will created between Serveless functions and RDB, Cache Server\n\nAlmost 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.\n\nIn that case, Hexaville provides you to connection pooling mechanism with [hexaville-tcp-proxy-server](https://github.com/Hexaville/hexaville-tcp-proxy-server).\n\nhexaville-tcp-proxy-server is not only a Proxy Sever But Connection Pooling Server.\nSee the detail to see [README](https://github.com/Hexaville/hexaville-tcp-proxy-server).\n\n## Cold Start\n\nThere are several third parties's libraries to againt cold start on github.\n\nThe major one is [serverless-plugin-warmup](https://github.com/FidelLimited/serverless-plugin-warmup)\n\n## How to update Hexaville CLI Version?\n\n```sh\n$ rm -rf ~/.hexaville\n$ curl -L https://rawgit.com/noppoMan/Hexaville/master/install.sh | bash\n$ hexaville version\n```\n\n## Contributing\nAll developers should feel welcome and encouraged to contribute to Hexaville, see our getting started document here to get involved.\n\nTo 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.\n\nIf you find a bug, please submit a pull request with a failing test case displaying the bug or create an issue.\n\nIf you find a security vulnerability, please contact yuki@miketokyo.com as soon as possible. We take these matters seriously.\n\n\n## Related Articles\n* [Serverless Server Side Swift with Hexaville](https://medium.com/@yukitakei/serverless-server-side-swift-with-hexaville-ef0e1788a20)\n* [Serverless Server Side Swift@Builderscon Tokyo 2017](https://speakerdeck.com/noppoman/serverless-server-side-swift)\n* [WEB+DB PRESS Vol.101](https://www.amazon.co.jp/WEB-DB-PRESS-Vol-101-%E6%A3%AE%E6%9C%AC/dp/4774192392)\n\n## License\n\nHexaville is released under the MIT license. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoppoman%2Fhexaville","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoppoman%2Fhexaville","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoppoman%2Fhexaville/lists"}