MTT-139: release 18

Author: Vladislav Alekseev

.gitignore

@@ -1,3 +1,5 @@
+.DS_Store
+
 # Xcode
 #
 # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
@@ -46,6 +48,7 @@ playground.xcworkspace
 # hence it is not needed unless you have added a package configuration file to your project
 # .swiftpm
 
+.swiftpm/
 .build/
 
 # CocoaPods

Package.resolved

@@ -0,0 +1,35 @@
+// swift-tools-version:5.3
+import PackageDescription
+let package = Package(
+    name: "EmceePluginSupport",
+    platforms: [
+        .macOS(.v11),
+    ],
+    products: [
+        .library(name: "EmceePlugin", targets: ["EmceePlugin"]),
+        .library(name: "EmceePluginModels", targets: ["EmceePluginModels"]),
+    ],
+    dependencies: [
+        .package(name: "CommandLineToolkit", url: "https://github.com/avito-tech/CommandLineToolkit.git", from: "1.0.20"),
+        .package(name: "Starscream", url: "https://github.com/daltoniam/Starscream.git", from: "3.0.6"),
+    ],
+    targets: [
+        .target(
+            name: "EmceePlugin",
+            dependencies: [
+                .product(name: "CLTLogging", package: "CommandLineToolkit"),
+                .product(name: "CLTLoggingModels", package: "CommandLineToolkit"),
+                .product(name: "DateProvider", package: "CommandLineToolkit"),
+                .product(name: "DI", package: "CommandLineToolkit"),
+                .product(name: "FileSystem", package: "CommandLineToolkit"),
+                .product(name: "JSONStream", package: "CommandLineToolkit"),
+                .product(name: "Starscream", package: "Starscream"),
+                .product(name: "SynchronousWaiter", package: "CommandLineToolkit"),
+                "EmceePluginModels",
+            ]
+        ),
+        .target(
+            name: "EmceePluginModels"
+        )
+    ]
+)

Package.swift

@@ -1,2 +1,56 @@
-# EmceePluginSupport
-Swift package that allows to extend Emcee with plugins
+#  Plugin
+
+This module provides a basic class that plugin can use to create a bridge between the worker and the plugin.
+All events are broadcasted into running plugins, but not backwards.
+The worker will start web socket server, the plugin subprocess, and then disconnect.
+Plugin is expected to terminate after its web socket disconnect. 
+Worker will forcefully terminate it after some timeout if it stays alive.   
+
+```
+Main Executable     ----- (web socket) ------->     Plugin
+```
+
+## Using `Plugin`
+
+In your `Package.swift`, import the library that has all required APIs to implement a plugin. Please use the matching Emcee version as a tag:
+
+```
+dependencies: [
+    .package(url: "https://github.com/avito-tech/EmceePluginSupport", .revision("18.0.0"))
+]
+```
+
+In your plugin target add `EmceePlugin` dependency: 
+
+```
+targets: [
+    .target(
+        name: "MyOwnPlugin",
+        dependencies: [
+            "EmceePlugin",
+            "EmceePluginModels"
+        ]
+    )
+]
+```
+
+The main class for plugin is `Plugin`. The most common scenario is (`main.swift`):
+
+```swift
+import Foundation
+import EmceePlugin
+import EmceePluginModels
+
+func main() throws -> Int32 {
+    let plugin = try Plugin { (event: PluginAppleTestEvent) in
+        // process an event
+    }
+    plugin.join()
+    return 0
+}
+
+exit(try main())
+
+```
+
+`Plugin` class will automatically stop streaming events when web socket gets disconnected, allowing `join()` method to return.

README.md

@@ -0,0 +1,25 @@
+import CLTLogging
+import DateProvider
+import DI
+import FileSystem
+
+public final class EmceeModuleDependencies: ModuleDependencies, InitializableWithNoArguments {
+    public init() {}
+    
+    public func otherModulesDependecies() -> [ModuleDependencies] {
+        [
+            DateProviderModuleDependencies(),
+            FileSystemModuleDependencies(),
+        ]
+    }
+    
+    public func registerDependenciesOfCurrentModule(di: DependencyRegisterer) {
+        di.register(type: LoggingSetup.self) { di in
+            try LoggingSetup(
+                dateProvider: di.resolve(),
+                fileSystem: di.resolve(),
+                logDomainName: "EmceePlugins"
+            )
+        }
+    }
+}

Sources/.DS_Store

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) Avito Tech LLC
+ */
+
+import CLTLogging
+import Foundation
+import JSONStream
+import EmceePluginModels
+
+final class EmceePluginJSONStreamAdapter: JSONReaderEventStream {
+    private let logger: ContextualLogger
+    private let decoder = JSONDecoder()
+    private let onNewEvent: (PluginAppleTestEvent) -> ()
+    
+    public init(
+        logger: ContextualLogger,
+        onNewEvent: @escaping (PluginAppleTestEvent) -> ()
+    ) {
+        self.logger = logger
+        self.onNewEvent = onNewEvent
+    }
+    
+    func newArray(_ array: NSArray, data: Data) {
+        logger.warning("JSON stream reader received an unexpected event: '\(data)'")
+    }
+    
+    func newObject(_ object: NSDictionary, data: Data) {
+        do {
+            let event = try decoder.decode(PluginAppleTestEvent.self, from: data)
+            onNewEvent(event)
+        } catch {
+            logger.error("Failed to decode plugin event: \(error), object: \(object)")
+        }
+    }
+}

Sources/EmceePlugin/.DS_Store

@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) Avito Tech LLC
+ */
+
+import CLTLogging
+import EmceePluginModels
+import Foundation
+import Starscream
+
+public final class EventReceiver: WebSocketDelegate {
+    public typealias Handler = () -> ()
+    public typealias ErrorHandler = (Swift.Error) -> ()
+    public typealias DataHandler = (Data) -> ()
+    
+    private let address: String
+    private let logger: ContextualLogger
+    private let pluginIdentifier: String
+    private let socket: WebSocket
+    private let encoder = JSONEncoder()
+    private let decoder = JSONDecoder()
+    private var didHandshake = false
+    
+    public var onDisconnect: Handler?
+    public var onError: ErrorHandler?
+    public var onData: DataHandler?
+    
+    public enum `Error`: Swift.Error, CustomStringConvertible {
+        case acknowledgementError(message: String?)
+        
+        public var description: String {
+            switch self {
+            case .acknowledgementError(let message):
+                return "Plugin acknowledgement error: \(message ?? "null message")"
+            }
+        }
+    }
+
+    public init(
+        address: String,
+        logger: ContextualLogger,
+        pluginIdentifier: String
+    ) {
+        self.address = address
+        self.logger = logger
+        self.pluginIdentifier = pluginIdentifier
+        self.socket = WebSocket(url: URL(string: address)!)
+    }
+    
+    public func start() {
+        logger.trace("Connecting to web socket: \(address)")
+        didHandshake = false
+        socket.delegate = self
+        socket.connect()
+    }
+    
+    public func stop() {
+        logger.trace("Disconnecting from web socket: \(address)")
+        socket.disconnect()
+    }
+    
+    public func websocketDidConnect(socket: WebSocketClient) {
+        logger.trace("Connected to web socket")
+        do {
+            let handshakeRequest = PluginHandshakeRequest(pluginIdentifier: pluginIdentifier)
+            let data = try encoder.encode(handshakeRequest)
+            socket.write(data: data)
+            logger.trace("Sent handshake request")
+        } catch {
+            logger.error("Failed to encode handshake request: \(error)")
+        }
+    }
+    
+    public func websocketDidDisconnect(socket: WebSocketClient, error: Swift.Error?) {
+        didHandshake = false
+        if let error = error {
+            if let wsError = error as? WSError, wsError.code == CloseCode.normal.rawValue {
+                logger.trace("Disconnected from web socket normally")
+                onDisconnect?()
+            } else {
+                logger.error("Web socket error: \(error)")
+                onError?(error)
+            }
+        } else {
+            logger.trace("Disconnected from web socket without error")
+            onDisconnect?()
+        }
+    }
+    
+    public func websocketDidReceiveMessage(socket: WebSocketClient, text: String) {
+        logger.warning("Received unexpected message from web socket: \(text)")
+    }
+    
+    public func websocketDidReceiveData(socket: WebSocketClient, data: Data) {
+        logger.trace("Received data from web socket: \(data.count) bytes")
+        
+        if didHandshake {
+            onData?(data)
+        } else if let acknowledgement = try? decoder.decode(PluginHandshakeAcknowledgement.self, from: data) {
+            switch acknowledgement {
+            case .successful:
+                didHandshake = true
+            case .error(let message):
+                onError?(Error.acknowledgementError(message: message))
+            }
+        } else {
+            stop()
+        }
+    }
+}