poc: analytics tracking

cabal.project

@@ -8,3 +8,4 @@ packages:
   nri-http/nri-http.cabal
   nri-postgresql/nri-postgresql.cabal
   nri-kafka/nri-kafka.cabal
+  nri-analytics/nri-analytics.cabal

nri-analytics/CHANGELOG.md

@@ -0,0 +1,7 @@
+# 0.1.0.0
+
+- Initial release. Provides `Analytics.handler`, `Analytics.silentHandler`,
+  `Analytics.Settings`, and `Analytics.decoder`. Sync HTTP POST delivery
+  to a configured events service URL with bearer auth, bounded timeout,
+  and log-and-drop on failure. Wire format is provisional pending the
+  events service contract.

nri-analytics/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, NoRedInk
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nri-analytics/README.md

@@ -0,0 +1,8 @@
+# nri-analytics
+
+Sync HTTP delivery of typed analytics events to the NoRedInk events service.
+
+This package is consumed by NoRedInk's monolith. It produces an
+`AnalyticsHandler` whose `sendEvent` is wired into `nri-prelude`'s
+`Platform.Analytics.Internal` callback at the application root. See the
+companion design doc in `NoRedInk/event-platform/docs`.

nri-analytics/nri-analytics.cabal

@@ -0,0 +1,99 @@
+cabal-version: 1.18
+
+-- This file has been generated from package.yaml by hpack version 0.37.0.
+--
+-- see: https://github.com/sol/hpack
+
+name:           nri-analytics
+version:        0.1.0.0
+synopsis:       Deliver typed analytics events to the NoRedInk events service.
+description:    Please see the README at <https://github.com/NoRedInk/haskell-libraries/tree/trunk/nri-analytics#readme>.
+category:       Web
+homepage:       https://github.com/NoRedInk/haskell-libraries/tree/trunk/nri-analytics#readme
+bug-reports:    https://github.com/NoRedInk/haskell-libraries/issues
+author:         NoRedInk
+maintainer:     haskell-open-source@noredink.com
+copyright:      2026 NoRedInk Corp.
+license:        BSD3
+license-file:   LICENSE
+build-type:     Simple
+extra-doc-files:
+    README.md
+    LICENSE
+    CHANGELOG.md
+
+source-repository head
+  type: git
+  location: https://github.com/NoRedInk/haskell-libraries
+  subdir: nri-analytics
+
+library
+  exposed-modules:
+      Analytics
+  other-modules:
+      Analytics.Internal
+  hs-source-dirs:
+      src
+  default-extensions:
+      DeriveGeneric
+      FlexibleInstances
+      GeneralizedNewtypeDeriving
+      NamedFieldPuns
+      NoImplicitPrelude
+      OverloadedStrings
+      PartialTypeSignatures
+      ScopedTypeVariables
+      Strict
+  ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates -Wpartial-fields -Wredundant-constraints -Wincomplete-uni-patterns -fplugin=NriPrelude.Plugin
+  build-depends:
+      aeson >=2.0 && <2.3
+    , base >=4.18 && <4.22
+    , bytestring >=0.10.8.2 && <0.13
+    , conduit >=1.3.0 && <1.4
+    , http-client >=0.6.0 && <0.8
+    , http-client-tls >=0.3.0 && <0.4
+    , nri-env-parser >=0.1.0.0 && <0.5
+    , nri-prelude >=0.7.0.0 && <0.8
+    , safe-exceptions >=0.1.7.0 && <1.3
+    , text >=1.2.3.1 && <2.2
+    , time >=1.9.3 && <2
+    , uuid ==1.3.*
+  default-language: Haskell2010
+
+test-suite tests
+  type: exitcode-stdio-1.0
+  main-is: Main.hs
+  other-modules:
+      Spec.Analytics
+      Analytics
+      Analytics.Internal
+      Paths_nri_analytics
+  hs-source-dirs:
+      tests
+      src
+  default-extensions:
+      DeriveGeneric
+      FlexibleInstances
+      GeneralizedNewtypeDeriving
+      NamedFieldPuns
+      NoImplicitPrelude
+      OverloadedStrings
+      PartialTypeSignatures
+      ScopedTypeVariables
+      Strict
+  ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates -Wpartial-fields -Wredundant-constraints -Wincomplete-uni-patterns -fplugin=NriPrelude.Plugin -threaded
+  build-depends:
+      aeson >=2.0 && <2.3
+    , base >=4.18 && <4.22
+    , bytestring >=0.10.8.2 && <0.13
+    , conduit >=1.3.0 && <1.4
+    , http-client >=0.6.0 && <0.8
+    , http-client-tls >=0.3.0 && <0.4
+    , nri-analytics
+    , nri-env-parser >=0.1.0.0 && <0.5
+    , nri-prelude >=0.7.0.0 && <0.8
+    , safe-exceptions >=0.1.7.0 && <1.3
+    , text >=1.2.3.1 && <2.2
+    , time >=1.9.3 && <2
+    , uuid ==1.3.*
+  default-language: Haskell2010

nri-analytics/package.yaml

@@ -0,0 +1,63 @@
+name: nri-analytics
+synopsis: Deliver typed analytics events to the NoRedInk events service.
+description: Please see the README at <https://github.com/NoRedInk/haskell-libraries/tree/trunk/nri-analytics#readme>.
+homepage: https://github.com/NoRedInk/haskell-libraries/tree/trunk/nri-analytics#readme
+author: NoRedInk
+version: 0.1.0.0
+maintainer: haskell-open-source@noredink.com
+copyright: 2026 NoRedInk Corp.
+github: NoRedInk/haskell-libraries/nri-analytics
+license-file: LICENSE
+category: Web
+extra-doc-files:
+  - README.md
+  - LICENSE
+  - CHANGELOG.md
+dependencies:
+  - aeson >= 2.0 && < 2.3
+  - base >= 4.18 && < 4.22
+  - bytestring >= 0.10.8.2 && < 0.13
+  - conduit >= 1.3.0 && < 1.4
+  - http-client >= 0.6.0 && < 0.8
+  - http-client-tls >= 0.3.0 && < 0.4
+  - nri-env-parser >= 0.1.0.0 && < 0.5
+  - nri-prelude >= 0.7.0.0 && < 0.8
+  - safe-exceptions >= 0.1.7.0 && < 1.3
+  - text >= 1.2.3.1 && < 2.2
+  - time >= 1.9.3 && < 2
+  - uuid >= 1.3 && < 1.4
+library:
+  exposed-modules:
+    - Analytics
+  other-modules:
+    - Analytics.Internal
+  source-dirs: src
+default-extensions:
+  - DeriveGeneric
+  - FlexibleInstances
+  - GeneralizedNewtypeDeriving
+  - NamedFieldPuns
+  - NoImplicitPrelude
+  - OverloadedStrings
+  - PartialTypeSignatures
+  - ScopedTypeVariables
+  - Strict
+ghc-options:
+  - -Wall
+  - -Wcompat
+  - -Widentities
+  - -Wincomplete-record-updates
+  - -Wpartial-fields
+  - -Wredundant-constraints
+  - -Wincomplete-uni-patterns
+  - -fplugin=NriPrelude.Plugin
+tests:
+  tests:
+    main: Main.hs
+    source-dirs:
+      - tests
+      - src
+    ghc-options:
+      - -threaded
+    dependencies:
+      - nri-analytics

nri-analytics/src/Analytics.hs

@@ -0,0 +1,102 @@
+-- | Sync HTTP delivery of typed analytics events to NoRedInk's events
+-- service. The `AnalyticsHandler` produced here is meant to be threaded
+-- into `nri-prelude`'s `LogHandler` analytics callback at the
+-- application root.
+module Analytics
+  ( -- * Handle
+    Internal.AnalyticsHandler,
+    sendEvent,
+    handler,
+    silentHandler,
+
+    -- * Settings
+    Internal.Settings
+      ( Settings,
+        eventsServiceUrl,
+        timeoutMicros,
+        authToken
+      ),
+    decoder,
+  )
+where
+
+import qualified Analytics.Internal as Internal
+import qualified Conduit
+import qualified Data.Aeson as Aeson
+import qualified Environment
+import qualified Log
+import qualified Network.HTTP.Client.TLS as HTTP.TLS
+import NriPrelude
+import Prelude (IO, pure)
+
+-- | Send a single event payload. Called from
+-- `Platform.Analytics.Internal.trackEvent` via the `LogHandler`'s
+-- analytics callback. Synchronous; bounded by `Settings.timeoutMicros`;
+-- never throws.
+sendEvent :: Internal.AnalyticsHandler -> Aeson.Value -> IO ()
+sendEvent = Internal.sendEvent
+
+-- | A no-op handler. Use this in tests and on platforms that have not
+-- opted in to analytics tracking yet.
+silentHandler :: Internal.AnalyticsHandler
+silentHandler =
+  Internal.AnalyticsHandler
+    { Internal.sendEvent = \_ -> pure (),
+      Internal.settings =
+        Internal.Settings
+          { Internal.eventsServiceUrl = "",
+            Internal.timeoutMicros = 0,
+            Internal.authToken = Log.mkSecret ""
+          },
+      Internal.httpManager = Nothing
+    }
+
+-- | Acquire a live handler. Owns an HTTP manager that lives until the
+-- `Acquire` is released.
+handler :: Internal.Settings -> Conduit.Acquire Internal.AnalyticsHandler
+handler s = do
+  manager <- Conduit.mkAcquire HTTP.TLS.newTlsManager (\_ -> pure ())
+  pure
+    Internal.AnalyticsHandler
+      { Internal.sendEvent = Internal.sendEventIO manager s,
+        Internal.settings = s,
+        Internal.httpManager = Just manager
+      }
+
+-- | Read settings from environment variables.
+decoder :: Environment.Decoder Internal.Settings
+decoder =
+  pure Internal.Settings
+    |> andMap eventsServiceUrlDecoder
+    |> andMap timeoutMicrosDecoder
+    |> andMap authTokenDecoder
+
+eventsServiceUrlDecoder :: Environment.Decoder Text
+eventsServiceUrlDecoder =
+  Environment.variable
+    Environment.Variable
+      { Environment.name = "ANALYTICS_EVENTS_SERVICE_URL",
+        Environment.description = "Base URL of the events service.",
+        Environment.defaultValue = ""
+      }
+    Environment.text
+
+timeoutMicrosDecoder :: Environment.Decoder Int
+timeoutMicrosDecoder =
+  Environment.variable
+    Environment.Variable
+      { Environment.name = "ANALYTICS_EVENTS_TIMEOUT_MICROS",
+        Environment.description = "Per-request timeout in microseconds. Default 500000 (500ms).",
+        Environment.defaultValue = "500000"
+      }
+    Environment.int
+
+authTokenDecoder :: Environment.Decoder (Log.Secret Text)
+authTokenDecoder =
+  Environment.variable
+    Environment.Variable
+      { Environment.name = "ANALYTICS_EVENTS_AUTH_TOKEN",
+        Environment.description = "Bearer token for the events service.",
+        Environment.defaultValue = ""
+      }
+    (Environment.secret Environment.text)