Compatibility
- 2.6.05.35.25.15.04.2
- main5.35.25.15.04.2
- 2.6.0 and mainiOSmacOS(Intel)macOS(ARM)LinuxtvOSwatchOS
A light-weight server-side service framework written in the Swift programming language.
The Smoke Framework is a light-weight server-side service framework written in Swift and using SwiftNIO for its networking layer by default. The framework can be used for REST-like or RPC-like services and in conjunction with code generators from service models such as Swagger/OpenAPI.
The framework has built in support for JSON-encoded request and response payloads.
SmokeFramework follows the same support policy as followed by SmokeAWS here.
The Smoke Framework provides the ability to specify handlers for operations your service application needs to perform. When a request is received, the framework will decode the request into the operation's input. When the handler returns, its response (if any) will be encoded and sent in the response.
Each invocation of a handler is also passed an application-specific context, allowing application-scope or invocation-scope entities such as other service clients to be passed to operation handlers. Using the context allows operation handlers to remain pure functions (where its return value is determined by the function's logic and input values) and hence easily testable.
See this repository for examples of the Smoke Framework and the related Smoke* repositories in action.
The Smoke Framework provides a code generator that will generate a complete Swift Package Manager repository for a SmokeFrammework-based service from a Swagger 2.0 specification file.
See the instructions in the code generator repository on how to get started.
These steps assume you have just created a new swift application using swift package init --type executable
.
The Smoke Framework uses the Swift Package Manager. To use the framework, add the following dependency to your Package.swift-
For swift-tools version 5.2 and greater-
dependencies: [
.package(url: "https://github.com/amzn/smoke-framework.git", from: "2.0.0")
]
.target(name: ..., dependencies: [
...,
.product(name: "SmokeOperationsHTTP1Server", package: "smoke-framework"),
]),
For swift-tools version 5.1 and prior-
dependencies: [
.package(url: "https://github.com/amzn/smoke-framework.git", from: "2.0.0")
]
.target(
name: ...,
dependencies: [..., "SmokeOperationsHTTP1Server"]),
If you attempt to compile the application, you will get the error
the product 'XXX' requires minimum platform version 10.12 for macos platform
This is because SmokeFramework projects have a minimum MacOS version dependency. To correct this there needs to be a couple of additions to to the Package.swift file.
Specify the language versions supported by the application-
targets: [
...
],
swiftLanguageVersions: [.v5]
Specify the platforms supported by the application-
name: "XXX",
platforms: [
.macOS(.v10_15), .iOS(.v10)
],
products: [
name: "XXX",
platforms: [
.macOS(.v10_12), .iOS(.v10)
],
products: [
The next step to using the Smoke Framework is to define one or more functions that will perform the operations that your application requires. The following code shows an example of such a function-
func handleTheOperation(input: OperationInput, context: MyApplicationContext) throws -> OperationOutput {
return OperationOutput()
}
This particular operation function accepts the input to the operation and the application-specific context - MyApplicationContext
- while
returning the output from the operation. The application-specific context can be any type the application requires to pass application-specific or invocation-specific context to the operation handlers
For HTTP1, the operation input can conform to OperationHTTP1InputProtocol, which defines how the input type is constructed from the HTTP1 request. Similarly, the operation output can conform to OperationHTTP1OutputProtocol, which defines how to construct the HTTP1 response from the output type. Both must also conform to the Validatable protocol, giving the opportunity to validate any field constraints.
As an alternative, both operation input and output can conform to the Codable
protocol if
they are constructed from only one part of the HTTP1 request and response.
The Smoke Framework also supports additional built-in and custom operation function signatures. See the The Operation Function and Extension Points sections for more information.
After defining the required operation handlers, it is time to specify how they are selected for incoming requests.
The Smoke Framework provides the SmokeHTTP1HandlerSelector protocol to add handlers to a selector.
import SmokeOperationsHTTP1
public func addOperations<SelectorType: SmokeHTTP1HandlerSelector>(selector: inout SelectorType)
where SelectorType.ContextType == MyApplicationContext,
SelectorType.OperationIdentifer == MyOperations {
selector.addHandlerForOperation(MyOperations.theOperation, httpMethod: .POST,
operation: handleTheOperation,
allowedErrors: [(MyApplicationErrors.unknownResource, 400)])
}
Each handler added requires the following parameters to be specified:
CustomStringConvertible
that returns the identity of the current error.Codable
)Codable
)The final step is to setup an application as an operation server.
import Foundation
import SmokeOperationsHTTP1
import SmokeOperationsHTTP1Server
import AsyncHTTPClient
import NIO
import SmokeHTTP1
typealias MyOperationDelegate = JSONPayloadHTTP1OperationDelegate<SmokeInvocationTraceContext>
struct MyPerInvocationContextInitializer: SmokeServerPerInvocationContextInitializer {
typealias SelectorType =
StandardSmokeHTTP1HandlerSelector<MyApplicationContext, MyOperationDelegate,
MyOperations>
// add any application-wide context
let handlerSelector: SelectorType
/**
On application startup.
*/
init(eventLoop: EventLoop) throws {
// set up any of the application-wide context
var selector = SelectorType(defaultOperationDelegate: JSONPayloadHTTP1OperationDelegate())
addOperations(selector: &selector)
self.handlerSelector = selector
}
/**
On invocation.
*/
public func getInvocationContext(
invocationReporting: SmokeServerInvocationReporting<SmokeInvocationTraceContext>) -> MyApplicationContext {
// create an invocation-specific context to be passed to an operation handler
return MyApplicationContext(...)
}
/**
On application shutdown.
*/
func onShutdown() throws {
// shutdown anything before the application closes
}
}
SmokeHTTP1Server.runAsOperationServer(MyPerInvocationContextInitializer.init)
You can now run the application and the server will start up on port 8080. The application will block in the
SmokeHTTP1Server.runAsOperationServer
call. When the server has been fully shutdown and has
completed all requests, onShutdown
will be called. In this function you can close/shutdown
any clients or credentials that were created on application startup.
An instance of the application context type is created at application start-up and is passed to each invocation of an operation handler. The framework imposes no restrictions on this type and simply passes it through to the operation handlers. It is recommended that this context is immutable as it can potentially be passed to multiple handlers simultaneously. Otherwise, the context type is responsible for handling its own thread safety.
It is recommended that applications use a strongly typed context rather than a bag of stuff such as a Dictionary.
The Operation Delegate handles specifics such as encoding and decoding requests to the handler's input and output.
The Smoke Framework provides the JSONPayloadHTTP1OperationDelegate implementation that expects a JSON encoded request body as the handler's input and returns the output as the JSON encoded response body.
Each addHandlerForOperation
invocation can optionally accept an operation delegate to use when that
handler is selected. This can be used when operations have specific encoding or decoding requirements.
A default operation delegate is set up at server startup to be used for operations without a specific
handler or when no handler matches a request.
The JSONPayloadHTTP1OperationDelegate
takes a generic parameter conforming to the HTTP1OperationTraceContext protocol. This protocol can be used to providing request-level tracing. The requirements for this protocol are defined here.
A default implementation - SmokeInvocationTraceContext - provides some basic tracing using request and response headers.
Each handler provides a function to be invoked when the handler is selected. By default, the Smoke framework provides four function signatures that this function can conform to-
((InputType, ContextType) throws -> ())
: Synchronous method with no output.((InputType, ContextType) throws -> OutputType)
: Synchronous method with output.((InputType, ContextType, (Swift.Error?) -> ()) throws -> ())
: Asynchronous method with no output.((InputType, ContextType, (SmokeResult<OutputType>) -> ()) throws -> ())
: Asynchronous method with output.Due to Swift type inference, a handler can switch between these different signatures without changing the handler selector declaration - simply changing the function signature is sufficient.
The synchronous variants will return a response as soon as the function returns either with an empty body or the encoded return value. The asynchronous variants will return a response when the provided result handlers are called.
public protocol Validatable {
func validate() throws
}
In all cases, the InputType and OutputType types must conform to the Validatable
protocol. This
protocol gives a type the opportunity to verify its fields - such as for string length, numeric
range validation. The Smoke Framework will call validate on operation inputs before passing it to the
handler and operation outputs after receiving from the handler-
By default, any errors thrown from an operation handler will fail the operation and the framework will return a 500 Internal Server Error to the caller (the framework also logs this event at Error level). This behavior prevents any unintentional leakage of internal error information.
public typealias ErrorIdentifiableByDescription = Swift.Error & CustomStringConvertible
public typealias SmokeReturnableError = ErrorIdentifiableByDescription & Encodable
Errors can be explicitly encoded and returned to the caller by conforming to the Swift.Error
, CustomStringConvertible
and Encodable
protocols and being specified under allowedErrors in the addHandlerForUri
call setting up the
operation handler. For example-
public enum MyError: Swift.Error {
case theError(reason: String)
enum CodingKeys: String, CodingKey {
case reason = "Reason"
}
}
extension MyError: Encodable {
public func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
switch self {
case .theError(reason: let reason):
try container.encode(reason, forKey: .reason)
}
}
}
extension MyError: CustomStringConvertible {
public var description: String {
return "TheError"
}
}
When such an error is returned from an operation handler-
The Smoke Framework has been designed to make testing of operation handlers straightforward. It is recommended that operation handlers are pure functions (where its return value is determined by the function's logic and input values). In this case, the function can be called in unit tests with appropriately constructed input and context instances.
It is recommended that the application-specific context be used to vary behavior between release and testing executions - such as mocking service clients, random number generators, etc. In general this will create more maintainable tests by keeping all the testing logic in the testing function.
If you want to run all test cases in Smoke Framework, please open command line and go to smoke-framework
(root) directory, run swift test
and then you should be able to see test cases result.
The Smoke Framework is designed to be extensible beyond its current functionality-
JSONPayloadHTTP1OperationDelegate
provides basic JSON payload encoding and decoding. Instead, the HTTP1OperationDelegate
protocol can
be used to create a delegate that provides alternative payload encoding and decoding. Instances of this protocol are given
the entire HttpRequestHead and request body when decoding the input and encoding the output for situations when these are required.StandardSmokeHTTP1HandlerSelector
provides a handler selector that compares the HTTP URI and verb to select a
handler. Instead, the SmokeHTTP1HandlerSelector
protocol can be used to create a selector that can use any property
from the HTTPRequestHead (such as headers) to select a handler.StandardSmokeHTTP1HandlerSelector
does fit your requirements, it can be extended to support additional function
signatures. See the built-in function signatures (one can be found in OperationHandler+nonblockingWithInputWithOutput.swift)
for examples of this.OperationHandler
provide a protocol-agnostic layer - as an example [1] - which can be used by a
protocol-specific layer - such as [2] for HTTP1 - to abstract protocol-specific handling for the different operation types.This library is licensed under the Apache 2.0 License.