{"id":1996,"url":"https://github.com/amzn/smoke-framework","last_synced_at":"2025-04-07T23:13:19.864Z","repository":{"id":39846884,"uuid":"151299222","full_name":"amzn/smoke-framework","owner":"amzn","description":"A light-weight server-side service framework written in the Swift programming language.","archived":false,"fork":false,"pushed_at":"2024-07-30T10:07:35.000Z","size":1018,"stargazers_count":1445,"open_issues_count":9,"forks_count":41,"subscribers_count":38,"default_branch":"smoke-framework-2.x","last_synced_at":"2024-10-29T17:55:30.876Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amzn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-02T17:58:20.000Z","updated_at":"2024-10-25T21:53:52.000Z","dependencies_parsed_at":"2023-02-10T06:15:16.260Z","dependency_job_id":"1535db20-5cc5-4116-a74b-4c2582959ee2","html_url":"https://github.com/amzn/smoke-framework","commit_stats":{"total_commits":211,"total_committers":15,"mean_commits":"14.066666666666666","dds":0.3744075829383886,"last_synced_commit":"dfac392993fe7e6e359ebbf45c463a51732eca1a"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fsmoke-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fsmoke-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fsmoke-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amzn%2Fsmoke-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amzn","download_url":"https://codeload.github.com/amzn/smoke-framework/tar.gz/refs/heads/smoke-framework-2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744335,"owners_count":20988783,"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":[],"created_at":"2024-01-05T20:16:00.805Z","updated_at":"2025-04-07T23:13:19.835Z","avatar_url":"https://github.com/amzn.png","language":"Swift","funding_links":[],"categories":["Server","Projects using SwiftNIO","Swift","Frameworks","HarmonyOS"],"sub_categories":["Keychain","Packages \u0026 executables","Windows Manager"],"readme":"\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/amzn/smoke-framework/actions\"\u003e\n\u003cimg src=\"https://github.com/amzn/smoke-framework/actions/workflows/swift.yml/badge.svg?branch=main\" alt=\"Build - Main Branch\"\u003e\n\u003c/a\u003e\n\u003ca href=\"http://swift.org\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/swift-5.6|5.7|5.8-orange.svg?style=flat\" alt=\"Swift 5.6, 5.7 and 5.8 Tested\"\u003e\n\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/ubuntu-20.04|22.04-yellow.svg?style=flat\" alt=\"Ubuntu 20.04 and 22.04 Tested\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/CentOS-8-yellow.svg?style=flat\" alt=\"CentOS 8 Tested\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/AmazonLinux-2-yellow.svg?style=flat\" alt=\"Amazon Linux 2 Tested\"\u003e\n\u003ca href=\"https://gitter.im/SmokeServerSide\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/chat-on%20gitter-ee115e.svg?style=flat\" alt=\"Join the Smoke Server Side community on gitter\"\u003e\n\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/license-Apache2-blue.svg?style=flat\" alt=\"Apache 2\"\u003e\n\u003c/p\u003e\n\n# Smoke Framework\n\nThe Smoke Framework is a light-weight server-side service framework written in Swift\nand using [SwiftNIO](https://github.com/apple/swift-nio) for its networking layer by\ndefault. The framework can be used for REST-like or RPC-like services and in conjunction\nwith code generators from service models such as [Swagger/OpenAPI](https://www.openapis.org/).\n\nThe framework has built in support for JSON-encoded request and response payloads.\n\n## Support Policy\n\nSmokeFramework follows the same support policy as followed by SmokeAWS [here](https://github.com/amzn/smoke-aws/blob/master/docs/Support_Policy.md).\n\n# Conceptual Overview\n\nThe Smoke Framework provides the ability to specify handlers for operations your service application\nneeds to perform. When a request is received, the framework will decode the request into the operation's\ninput. When the handler returns, its response (if any) will be encoded and sent in the response.\n\nEach invocation of a handler is also passed an application-specific context, allowing application-scope or invocation-scope\nentities such as other service clients to be passed to operation handlers. Using the context allows \noperation handlers to remain *pure* functions (where its return value is determined by the function's \nlogic and input values) and hence easily testable.\n\n# SmokeFrameworkExamples\n\nSee [this repository](https://github.com/amzn/smoke-framework-examples) for examples of the Smoke Framework and\nthe related Smoke* repositories in action.\n\n# Getting Started using Code Generation\n\nThe Smoke Framework provides a [code generator](https://github.com/amzn/smoke-framework-application-generate) that will\ngenerate a complete Swift Package Manager repository for a SmokeFramework-based service from a Swagger 2.0 specification file.\n\nSee the instructions in the code generator repository on how to get started.\n\n# Getting Started without Code Generation\n\nThese steps assume you have just created a new swift application using `swift package init --type executable`.\n\n## Step 1: Add the Smoke Framework dependency\n\nThe Smoke Framework uses the Swift Package Manager. To use the framework, add the following dependency\nto your Package.swift-\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/amzn/smoke-framework.git\", from: \"2.0.0\")\n]\n\n.target(name: ..., dependencies: [\n    ..., \n    .product(name: \"SmokeOperationsHTTP1Server\", package: \"smoke-framework\"),\n]),\n```\n\n\n## Step 2: Update the runtime dependency requirements of the application\n\nIf you attempt to compile the application, you will get the error\n\n```\nthe product 'XXX' requires minimum platform version 10.12 for macos platform\n```\n\nThis 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.\n\n### Step 2a: Update the language version\n\nSpecify the language versions supported by the application-\n\n```swift\ntargets: [\n    ...\n    ],\nswiftLanguageVersions: [.v5]\n```\n\n### Step 2b: Update the supported platforms\n\nSpecify the platforms supported by the application-\n\n```swift\nname: \"XXX\",\nplatforms: [\n  .macOS(.v10_15), .iOS(.v10)\n],\nproducts: [\n```\n\n\n## Step 2: Add a Context Type\n\nAn instance of the context type will be passed to each invocation of an operation that needs to be handled. This instance can be setup to be initialized per invocation or once for the application.\n\nYou will need to create this context type. There are no requirements for a type to be passed as a context. The following code shows an example of creating the context type-\n\n```swift\npublic struct MyApplicationContext {\n    let logger: Logger\n    // TODO: Add properties to be accessed by the operation handlers\n    \n    public init(logger: Logger) {\n        self.logger = logger\n    }\n}\n```\n\n## Step 3: Add an Operation Function\n\nThe next step to using the Smoke Framework is to define one or more functions that will perform the operations\nthat your application requires. The following code shows an example of such a function-\n\n```swift\nextension MyApplicationContext {\n    func handleTheOperation(input: OperationInput) throws -\u003e OperationOutput {\n        return OperationOutput()\n    }\n}\n```\n\nThis particular operation function accepts the input to the operation and is within an extension of the context (giving it access to any attributes or functions on this type) while\nreturning the output from the operation.\n\nFor HTTP1, the operation input can conform to [OperationHTTP1InputProtocol](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperationsHTTP1/OperationHTTP1InputProtocol.swift), which defines how the input type is constructed from\nthe HTTP1 request. Similarly, the operation output can conform to [OperationHTTP1OutputProtocol](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperationsHTTP1/OperationHTTP1OutputProtocol.swift), which defines how to construct\nthe HTTP1 response from the output type. Both must also conform to the [Validatable](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperations/Validatable.swift#L23) protocol, giving the opportunity to validate any field constraints.\n\nAs an alternative, both operation input and output can conform to the `Codable` protocol if\nthey are constructed from only one part of the HTTP1 request and response.\n\nThe Smoke Framework also supports additional built-in and custom operation function signatures. See the *The Operation Function*\nand *Extension Points* sections for more information.\n\n## Step 4: Add Handler Selection\n\nAfter defining the required operation handlers, it is time to specify how they are selected for incoming requests.\n\nThe Smoke Framework provides the [SmokeHTTP1HandlerSelector](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperationsHTTP1/SmokeHTTP1HandlerSelector.swift) protocol to add handlers to a selector.\n\n\n```swift\nimport SmokeOperationsHTTP1\n\npublic enum MyOperations: String, Hashable, CustomStringConvertible {\n    case theOperation = \"TheOperation\"\n\n    public var description: String {\n        return rawValue\n    }\n\n    public var operationPath: String {\n        switch self {\n        case .theOperation:\n            return \"/theOperation\"\n        }\n    }\n}\n\npublic extension MyOperations {\n    static func addToSmokeServer\u003cSelectorType: SmokeHTTP1HandlerSelector\u003e(selector: inout SelectorType)\n            where SelectorType.ContextType == MyApplicationContext,\n                  SelectorType.OperationIdentifer == MyOperations {\n        \n        let allowedErrorsForTheOperation: [(MyApplicationErrors, Int)] = [(.unknownResource, 404)]\n        selector.addHandlerForOperationProvider(.theOperation, httpMethod: .POST,\n                                                operationProvider: MyApplicationContext.handleTheOperation,\n                                                allowedErrors: allowedErrorsForTheOperation)\n    }\n}\n```\n\nEach handler added requires the following parameters to be specified:\n* The operation to be added. This must be of a type conforming to [OperationIdentity](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperations/OperationIdentity.swift) such as an [enum](https://github.com/amzn/smoke-framework-examples/blob/master/PersistenceExampleService/Sources/PersistenceExampleModel/PersistenceExampleModelOperations.swift). \n  * The HTTP method that must be matched by the incoming request to select the handler.\n  * The function to be invoked.\n  * The errors that can be returned to the caller from this handler. The error type must also conform to `CustomStringConvertible` that returns the identity of the current error.\n  * The location in the HTTP1 request to construct the operation input type from (only required if the input type conforms to `Codable`)\n  * The location in the HTTP1 response that the output type represents (only required if the output type conforms to `Codable`)\n\n## Step 5: Setting up the Application Server\n\nThe final step is to setup an application as an operation server.\n\n```swift\nimport Foundation\nimport SmokeOperationsHTTP1Server\nimport AsyncHTTPClient\nimport NIO\nimport SmokeHTTP1\n\nstruct MyPerInvocationContextInitializer: StandardJSONSmokeServerPerInvocationContextInitializer {\n    typealias ContextType = MyApplicationContext\n    typealias OperationIdentifer = MyOperations\n    \n    let serverName = \"MyService\"\n    // specify the operations initializer\n    let operationsInitializer: OperationsInitializerType = MyOperations.addToSmokeServer\n\n    /**\n     On application startup.\n     */\n    init(eventLoopGroup: EventLoopGroup) throws {\n        // set up any of the application-wide context\n    }\n\n    /**\n     On invocation.\n    */\n    public func getInvocationContext(\n        invocationReporting: SmokeServerInvocationReporting\u003cSmokeInvocationTraceContext\u003e) -\u003e MyApplicationContext {\n        // create an invocation-specific context to be passed to an operation handler\n        return MyApplicationContext(logger: invocationReporting.logger)\n    }\n\n    /**\n     On application shutdown.\n    */\n    func onShutdown() throws {\n        // shutdown anything before the application closes\n    }\n}\n\nSmokeHTTP1Server.runAsOperationServer(MyPerInvocationContextInitializer.init)\n```\n\nYou can now run the application and the server will start up on port 8080. The application will block in the\n`SmokeHTTP1Server.runAsOperationServer` call. When the server has been fully shutdown and has\ncompleted all requests, `onShutdown` will be called. In this function you can close/shutdown\nany clients or credentials that were created on application startup.\n\n## Step 6: Add Reporting Configuration (Optional)\n\nAn optional configuration step is to setup the reporting configuration for metrics emitted by the Smoke Framework.\nThis involves overriding the default `reportingConfiguration` attribute on the initializer. For the metrics to be\nemitted, a `swift-metrics` backend - such as [CloudWatchMetricsFactory](https://github.com/amzn/smoke-aws/blob/main/Sources/SmokeAWSMetrics/CloudWatchMetricsFactory.swift) - will need to be initialized.\n\n```swift\n...\n\nstruct MyPerInvocationContextInitializer: StandardJSONSmokeServerPerInvocationContextInitializer {\n    typealias ContextType = MyApplicationContext\n    typealias OperationIdentifer = MyOperations\n    \n    let reportingConfiguration: SmokeReportingConfiguration\u003cOperationIdentifer\u003e\n    let serverName = \"MyService\"\n    // specify the operations initializer\n    let operationsInitializer: OperationsInitializerType = MyOperations.addToSmokeServer\n\n    /**\n     On application startup.\n     */\n    init(eventLoopGroup: EventLoopGroup) throws {\n        // set up any of the application-wide context\n        \n        // for the server, only report the latency metrics\n        // only report 5XX error counts for TheOperation (even if additional operations are added in the future)\n        // only report 4XX error counts for operations other than TheOperation (as they are added in the future)\n        self.reportingConfiguration = SmokeReportingConfiguration(\n            successCounterMatchingRequests: .none,\n            failure5XXCounterMatchingRequests: .onlyForOperations([.theOperation]),\n            failure4XXCounterMatchingRequests: .exceptForOperations([.theOperation]),\n            requestReadLatencyTimerMatchingRequests: .none,\n            latencyTimerMatchingRequests: .all,\n            serviceLatencyTimerMatchingRequests: .all,\n            outwardServiceCallLatencyTimerMatchingRequests: .all,\n            outwardServiceCallRetryWaitTimerMatchingRequests: .all)\n    }\n\n    ...\n}\n\nSmokeHTTP1Server.runAsOperationServer(MyPerInvocationContextInitializer.init)\n```\n\n# Enabling Distributed Tracing (Swift 5.7 and greater)\n\nTo have your application participate in distributed traces, add a property `enableTracingWithSwiftConcurrency` \nwith a value of true to your application initializer.\n\n```swift\nstruct MyPerInvocationContextInitializer: StandardJSONSmokeServerPerInvocationContextInitializer {\n    let enableTracingWithSwiftConcurrency = true\n\n    ...\n}\n```\n\nThis will enable tracing for any operation handlers that use Swift Concurrency (async/await). You will also \nneed to setup an Instrumentation backend by following the instructions [here](https://swiftpackageindex.com/apple/swift-distributed-tracing/1.0.0/documentation/tracing/traceyourapplication).\n\n# Logging\n\nThe Smoke Framework provides a Metadata Provider that can be used to decorate any logs emitted from the structured concurrency tree\nrooted at the operation handlers. What this means is that metadata such as the `internalRequestId` and `incomingOperation` will be\nadded to logs emitted from libraries called from operation handlers even if an explicit logger instance isn't passed into the library\nfunction.\n\n```swift\nimport Logging\nimport SmokeOperations\n\n...\n\n    let metadataProvider = Logging.MetadataProvider.smokeframework\n    let factory = \u003cprovided by your logging backend\u003e\n\n    LoggingSystem.bootstrap(factory, metadataProvider: metadataProvider)\n```\n\n# Further Concepts\n\n## The Application Context\n\nAn instance of the application context type is created at application start-up and is passed\nto each invocation of an operation handler. The framework imposes no restrictions on this \ntype and simply passes it through to the operation handlers. It is *recommended* that this\ncontext is immutable as it can potentially be passed to multiple handlers simultaneously. \nOtherwise, the context type is responsible for handling its own thread safety.\n\nIt is recommended that applications use a **strongly typed** context rather than a *bag of \nstuff* such as a Dictionary.\n\n## The Operation Delegate\n\nThe Operation Delegate handles specifics such as encoding and decoding requests to the handler's \ninput and output.\n\nThe Smoke Framework provides the [JSONPayloadHTTP1OperationDelegate](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperationsHTTP1Server/JSONPayloadHTTP1OperationDelegate.swift#L21) implementation that expects \na JSON encoded request body as the handler's input and returns the output as the JSON encoded\nresponse body.\n\nEach `addHandlerForOperation` invocation can optionally accept an operation delegate to use when that\nhandler is selected. This can be used when operations have specific encoding or decoding requirements.\nA default operation delegate is set up at server startup to be used for operations without a specific\nhandler or when no handler matches a request.\n\n## The Trace Context\n\nThe `JSONPayloadHTTP1OperationDelegate` takes a generic parameter conforming to the [HTTP1OperationTraceContext](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperationsHTTP1Server/HTTP1OperationTraceContext.swift) protocol. This protocol can be used to providing request-level tracing. The requirements for this protocol are defined [here](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperations/OperationTraceContext.swift#L21).\n\nA default implementation - [SmokeInvocationTraceContext](https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperationsHTTP1Server/SmokeInvocationTraceContext.swift#L48) - provides some basic tracing using request and response headers.\n\n## The Operation Function\n\nEach handler provides a function to be invoked when the handler is selected. By default, the Smoke\nframework provides four function signatures declared on the Context Type that this function can conform to-\n\n* `((InputType) throws -\u003e ())`: Synchronous method with no output.\n* `((InputType) throws -\u003e OutputType)`: Synchronous method with output.\n* `((InputType, (Swift.Error?) -\u003e ()) throws -\u003e ())`: Asynchronous method with no output.\n* `((InputType, (Result\u003cOutputType, Error\u003e) -\u003e ()) throws -\u003e ())`: Asynchronous method with output.\n\nDue to Swift type inference, a handler can switch between these different signatures without changing the\nhandler selector declaration - simply changing the function signature is sufficient.\n\nThe synchronous variants will return a response as soon as the function returns either with an empty body or \nthe encoded return value. The asynchronous variants will return a response when the provided result handlers\nare called.\n\n```swift\npublic protocol Validatable {\n    func validate() throws\n}\n```\n\nIn all cases, the InputType and OutputType types must conform to the `Validatable` protocol. This\nprotocol gives a type the opportunity to verify its fields - such as for string length, numeric\nrange validation. The Smoke Framework will call validate on operation inputs before passing it to the\nhandler and operation outputs after receiving from the handler-\n* If an operation input fails its validation call (by throwing an error), the framework will fail the operation\n  with a 400 ValidationError response, indicating an error by the caller (the framework also logs this event \n  at *Info* level).\n* If an operation output fails its validation call (by throwing an error), the framework will fail the operation\n  with a 500 Internal Server Error, indicating an error by the service logic (the framework also logs this event \n  at *Error* level).\n  \n  Additionally, the Smoke Framework provides the option to declare operation handlers outside the Context Type as standalone functions.\n  The Context Type is passed in directly to these functions.\n\n  ```swift\n  func handleTheOperation(input: OperationInput, context: MyApplicationContext) throws -\u003e OperationOutput {\n      return OperationOutput()\n  }\n  ```\n\n  Adding the handler selection is slightly different in this case-\n\n  ```swift\n  import SmokeOperationsHTTP1\n\n  public func addOperations\u003cSelectorType: SmokeHTTP1HandlerSelector\u003e(selector: inout SelectorType)\n          where SelectorType.ContextType == MyApplicationContext,\n                SelectorType.OperationIdentifer == MyOperations {\n      \n      let allowedErrorsForTheOperation: [(MyApplicationErrors, Int)] = [(.unknownResource, 404)]\n      selector.addHandlerForOperation(.theOperation, httpMethod: .POST,\n                                      operation: handleTheOperation,\n                                      allowedErrors: allowedErrorsForTheOperation)\n  }\n  ```\n  \n The four function signatures are also available when using this style of operation handlers.\n\n  * `((InputType, ContextType) throws -\u003e ())`: Synchronous method with no output.\n  * `((InputType, ContextType) throws -\u003e OutputType)`: Synchronous method with output.\n  * `((InputType, ContextType, (Swift.Error?) -\u003e ()) throws -\u003e ())`: Asynchronous method with no output.\n  * `((InputType, ContextType, (Result\u003cOutputType, Error\u003e) -\u003e ()) throws -\u003e ())`: Asynchronous method with output.\n\n## Error Handling\n\nBy default, any errors thrown from an operation handler will fail the operation and the framework will return a\n500 Internal Server Error to the caller (the framework also logs this event at *Error* level). This behavior \nprevents any unintentional leakage of internal error information.\n\n```swift\npublic typealias ErrorIdentifiableByDescription = Swift.Error \u0026 CustomStringConvertible\npublic typealias SmokeReturnableError = ErrorIdentifiableByDescription \u0026 Encodable\n```  \n\nErrors can be explicitly encoded and returned to the caller by conforming to the `Swift.Error`, `CustomStringConvertible`\nand `Encodable` protocols **and** being specified under *allowedErrors* in the `addHandlerForUri` call setting up the\noperation handler. For example-\n\n```swift\npublic enum MyError: Swift.Error {\n    case theError(reason: String)\n    \n    enum CodingKeys: String, CodingKey {\n        case reason = \"Reason\"\n    }\n}\n\nextension MyError: Encodable {\n    public func encode(to encoder: Encoder) throws {\n        var container = encoder.container(keyedBy: CodingKeys.self)\n        \n        switch self {\n        case .theError(reason: let reason):\n            try container.encode(reason, forKey: .reason)\n        }\n    }\n}\n\nextension MyError: CustomStringConvertible {\n    public var description: String {\n        return \"TheError\"\n    }\n}\n```\n\nWhen such an error is returned from an operation handler-\n* A response is returned to the caller with the HTTP code specified in the *allowedErrors* entry with a payload \n  of the error encoded according to the *Encodable* protocol. \n* In addition, the provided error identity of the error will be specified in the **__type** field of the \n  returned payload.\n* Comparison between the error specified in the *allowedErrors* list and the error thrown from the operation handler\n  is a string comparison between the respective error identities. This is to allow equivalent errors of differing type\n  (such as code generated errors from different models) to be handled as the same error.\n* For the built-in asynchronous operation functions, errors can either be thrown synchronously from the function itself\n  or passed asynchronously to the result handler. Either way, the operation will fail according to the type of error thrown\n  or passed. This is to avoid functions having to catch synchronous errors (such as in setup) only to pass them to the\n  result handler. \n\n## Testing\n\nThe Smoke Framework has been designed to make testing of operation handlers straightforward. It is recommended that operation\nhandlers are *pure* functions (where its return value is determined by the function's logic and input values). In this case,\nthe function can be called in unit tests with appropriately constructed input and context instances.\n\nIt is recommended that the application-specific context be used to vary behavior between release and testing executions - \nsuch as mocking service clients, random number generators, etc. In general this will create more maintainable tests by keeping\nall the testing logic in the testing function.\n\nIf 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. \n\n# Extension Points\n\nThe Smoke Framework is designed to be extensible beyond its current functionality-\n* `JSONPayloadHTTP1OperationDelegate` provides basic JSON payload encoding and decoding. Instead, the `HTTP1OperationDelegate` protocol can\n  be used to create a delegate that provides alternative payload encoding and decoding. Instances of this protocol are given\n  the entire HttpRequestHead and request body when decoding the input and encoding the output for situations when these are required.\n* `StandardSmokeHTTP1HandlerSelector` provides a handler selector that compares the HTTP URI and verb to select a\n  handler. Instead, the `SmokeHTTP1HandlerSelector` protocol can be used to create a selector that can use any property\n  from the HTTPRequestHead (such as headers) to select a handler.\n* Even if `StandardSmokeHTTP1HandlerSelector` does fit your requirements, it can be extended to support additional function\n  signatures. See the built-in function signatures (one can be found in OperationHandler+nonblockingWithInputWithOutput.swift)\n  for examples of this.\n* The Smoke Framework currently supports HTTP1 but can be extended to additional protocols while using the same operation handlers\n  if needed. The initializers of `OperationHandler` provide a protocol-agnostic layer - as an example [1] - which can be used by a\n  protocol-specific layer - such as [2] for HTTP1 - to abstract protocol-specific handling for the different operation types. \n\n\n[1] https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperations/OperationHandler%2BblockingWithInputWithOutput.swift\n\n[2] https://github.com/amzn/smoke-framework/blob/master/Sources/SmokeOperationsHTTP1/SmokeHTTP1HandlerSelector%2BblockingWithInputWithOutput.swift\n\n## License\n\nThis library is licensed under the Apache 2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famzn%2Fsmoke-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famzn%2Fsmoke-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famzn%2Fsmoke-framework/lists"}