diff --git a/.gitignore b/.gitignore index 9a1ab8d..0040fda 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ Packages DerivedData/ Package.resolved .swiftpm +Tests/LinuxMain.swift diff --git a/Sources/Bugsnag/BugsnagConfiguration.swift b/Sources/Bugsnag/BugsnagConfiguration.swift index 3143c77..930c292 100644 --- a/Sources/Bugsnag/BugsnagConfiguration.swift +++ b/Sources/Bugsnag/BugsnagConfiguration.swift @@ -1,12 +1,24 @@ +/// Bugsnag's configuration options. +/// +/// app.bugsnag.configuration = .init(...) +/// public struct BugsnagConfiguration { + /// Notifier API key found in Bugsnag project settings. public var apiKey: String + + /// Which version of your app is running, like `development` or `production`. public var releaseStage: String /// A version identifier, (eg. a git hash) public var version: String? + + /// Defines sensitive keys that should be hidden from data reported to Bugsnag. public var keyFilters: Set + + /// Controls whether reports are sent to Bugsnag. public var shouldReport: Bool + /// Creates a new `BugsnagConfiguration`. public init( apiKey: String, releaseStage: String, diff --git a/Sources/Bugsnag/BugsnagMiddleware.swift b/Sources/Bugsnag/BugsnagMiddleware.swift index 6a55dda..ce3466e 100644 --- a/Sources/Bugsnag/BugsnagMiddleware.swift +++ b/Sources/Bugsnag/BugsnagMiddleware.swift @@ -1,10 +1,16 @@ import Vapor +/// Automatically catches and reports errors to Bugsnag. +/// +/// app.middleware.use(BugsnagMiddleware()) +/// +/// This should be placed _before_ `ErrorMiddleware`. public struct BugsnagMiddleware { public init() { } } extension BugsnagMiddleware: Middleware { + /// See `Middleware`. public func respond(to request: Request, chainingTo next: Responder) -> EventLoopFuture { next.respond(to: request).flatMapErrorThrowing { error in request.bugsnag.report(error) diff --git a/Sources/Bugsnag/BugsnagReporter.swift b/Sources/Bugsnag/BugsnagReporter.swift index eb02f48..6f6f782 100644 --- a/Sources/Bugsnag/BugsnagReporter.swift +++ b/Sources/Bugsnag/BugsnagReporter.swift @@ -1,16 +1,40 @@ import class Foundation.JSONSerialization import Vapor +/// Capable of reporting Bugsnag errors. +/// +/// See `req.bugsnag` and `app.bugsnag`. public protocol BugsnagReporter { + /// HTTP client used to contact Bugsnag. var client: Client { get } + + /// Logger to use for reporting information or errors. var logger: Logger { get } + + /// EventLoop to use for future returns. var eventLoop: EventLoop { get } + + /// Bugsnag configuration options for reporting. var configuration: BugsnagConfiguration? { get } + + /// Used to include additional information about the current + /// request in the report. var currentRequest: Request? { get } + + /// Configures which users will be reported by Bugsnag. var users: BugsnagUsers { get } } extension BugsnagReporter { + /// Reports an error to Bugsnag. + /// + /// req.bugsnag.report(someError) + /// + /// Conformance to `DebuggableError` and `BugsnagError` will be checked + /// for additional error context. + /// + /// - parameters: + /// - error: The error to report. @discardableResult public func report( _ error: Error diff --git a/Sources/Bugsnag/Request+Bugsnag.swift b/Sources/Bugsnag/Request+Bugsnag.swift index b72efb5..e9e5f22 100644 --- a/Sources/Bugsnag/Request+Bugsnag.swift +++ b/Sources/Bugsnag/Request+Bugsnag.swift @@ -1,16 +1,34 @@ import Vapor extension Request { + /// Bugsnag helper. Used to send reports during route handling. + /// + /// // Report an error. + /// req.bugsnag.report(someError) + /// public var bugsnag: Bugsnag { .init(request: self) } + /// Bugsnag helper. Used to send reports during route handling. + /// + /// // Report an error. + /// req.bugsnag.report(someError) + /// public struct Bugsnag { public let request: Request } } extension Request.Bugsnag { + /// Adds a breadcrumb to all reports sent. + /// + /// req.bugsnag.breadcrumb("login", type: .user) + /// + /// - parameters: + /// - name: Unique identifier for this breadcrumb. + /// - type: Type of breadcrumb. + /// - metadata: Optional context dictionary. @discardableResult public func breadcrumb( name: String, @@ -50,31 +68,38 @@ extension Request.Bugsnag { } extension Request.Bugsnag: BugsnagReporter { + /// See `BugsnagReporter`. public var currentRequest: Request? { self.request } + /// See `BugsnagReporter`. public var client: Client { self.request.client } + /// See `BugsnagReporter`. public var logger: Logger { self.request.logger } + /// See `BugsnagReporter`. public var eventLoop: EventLoop { self.request.eventLoop } + /// See `BugsnagReporter`. public var configuration: BugsnagConfiguration? { self.request.application.bugsnag.configuration } + /// See `BugsnagReporter`. public var users: BugsnagUsers { self.request.application.bugsnag.users } } +/// Types of Bugsnag report breadcrumbs. public enum BugsnagBreadcrumbType: String { case error case log diff --git a/Sources/Bugsnag/Severity.swift b/Sources/Bugsnag/Severity.swift index b46b761..92b13e8 100644 --- a/Sources/Bugsnag/Severity.swift +++ b/Sources/Bugsnag/Severity.swift @@ -1,6 +1,12 @@ +/// Error severity. See `BugsnagError`. public struct BugsnagSeverity { + /// Information. public static let info = Self(value: "info") + + /// Warning. public static let warning = Self(value: "warning") + + /// Error. public static let error = Self(value: "error") let value: String