Copyright (c) 2025 Oleksandr Zhabenko

This file is a ported to Haskell language code with some simplifications of Ruby on Rails 'https://github.com/rails/rails' 'https://github.com/rails/rails/blob/2318163b4b9e9604b557057c0465e2a5ef162401/activesupport/lib/active\_support/notifications.rb' and is based on the structure of the original code of rack-attack, Copyright (c) David Heinemeier Hansson, under the MIT License.

This implementation is released under the MIT License.

Overview

The Notifications module supplies a **pluggable notification layer** for the rate-limiting parts of the keter-rate-limiting-plugin project. Whenever a throttle decides to reject or allow a request, you may want to:

• store an audit trail,
• emit a metric,
• send an e-mail / Slack message, or
• perform any other side effect.

The abstraction is intentionally minimal yet flexible:

• Notifier – a "generic" notifier that works with arbitrary data (converted to a textual representation by the caller).
• WAINotifier – a convenience type alias specialised for WAI Request objects.

Both flavours come with:

• "do-nothing" implementations (noopNotifier, noopWAINotifier) for easy disabling or testing, and
• simple console loggers (consoleNotifier, consoleWAINotifier) for straightforward debugging.

You can easily lift these notifiers into your favourite effect stack by wrapping the IO action with a natural transformation (e.g., liftIO for any MonadIO).

Quick example

{-# LANGUAGE OverloadedStrings #-}
import Keter.RateLimiter.Notifications
import Network.Wai
import Network.Socket
import Network.Wai.Handler.Warp (run)
import Network.HTTP.Types (status200, status429)
import Control.Monad.IO.Class (liftIO)

-- A hypothetical function called when a client hits a rate limit.
blocked :: Request -> IO Response
blocked req = do
  -- Log the event using the predefined WAI console notifier.
  -- "per-ip" is the logical name of our throttle.
  -- 100 is the limit that was exceeded.
  consoleWAINotifier "per-ip" req 100
  pure $ responseLBS status429 [] "Too Many Requests"

-- A simple WAI application.
app :: Application
app req respond = do
  -- In a real application, you would have logic here to check the rate limit.
  -- If the limit is exceeded, call blocked.
  let isBlocked = False -- Placeholder for actual rate-limiting logic.
  if isBlocked
    then blocked req >>= respond
    else respond $ responseLBS status200 [] OK

main :: IO ()
main = run 8080 app

Advanced usage patterns

Custom notifiers

You can create custom notifiers for integration with external systems:

import qualified Data.Text.IO as TIO
import Control.Exception (try, SomeException)
import Data.Time.Clock (getCurrentTime)
import Data.Time.Format (defaultTimeLocale, formatTime)

-- A notifier that attempts to write to a file, falling back to console on error
fileNotifier :: FilePath -> Notifier
fileNotifier path = Notifier
  { notifierName = "file-logger"
  , notifierAction = \throttle act item limit -> do
      now <- getCurrentTime
      let timestamp = formatTime defaultTimeLocale "%Y-%m-%d %H:%M:%S" now
          parts = [throttle, act, item, T.concat ["(limit: ", T.pack (show limit), ")"]]
          message = T.intercalate " " $ filter (not . T.null) parts
          fullMessage = T.concat [T.pack timestamp, " - ", message, "\n"]
      
      result <- try $ TIO.appendFile path fullMessage
      case result of
        Left (_ :: SomeException) -> 
          -- Fallback to console logging
          notifierAction consoleNotifier throttle act item limit
        Right _ -> pure ()
  }

Combining notifiers

Multiple notifiers can be combined to send notifications to different destinations:

multiNotifier :: [Notifier] -> Notifier
multiNotifier notifiers = Notifier
  { notifierName = "multi"
  , notifierAction = \throttle act item limit ->
      mapM_ (\n -> notifierAction n throttle act item limit) notifiers
  }

-- Usage example
combinedNotifier = multiNotifier [consoleNotifier, fileNotifier "varlog/rate-limits.log"]

Converting between notifier types

The waiNotifier function allows you to use any generic Notifier with WAI requests:

-- Use a custom notifier with WAI
myWAINotifier :: WAINotifier
myWAINotifier = waiNotifier (fileNotifier "varlog/wai-rate-limits.log")

Log format specifications

Generic notifier format

The consoleNotifier produces log entries in the following format:

YYYY-MM-DD HH:MM:SS - throttleName action item (limit: N)

When the throttle name is empty, it is omitted from the output:

YYYY-MM-DD HH:MM:SS - action item (limit: N)

Examples: 2025-01-30 13:45:12 - loginAttempts blocked "user123" (limit: 5) 2025-01-30 13:45:13 - api-global blocked "192.168.1.100" (limit: 1000) 2025-01-30 13:45:14 - blocked "item" (limit: 50)

Note that textual items are quoted due to the use of show for conversion.

WAI notifier format

The consoleWAINotifier produces more detailed log entries specifically for HTTP requests:

YYYY-MM-DD HH:MM:SS - throttleName blocked METHOD PATH[?QUERY] from IP:PORT (limit: N)

Examples: 2025-01-30 13:45:12 - api-global blocked GET v1users?id=123 from 192.0.2.1:54321 (limit: 1000) 2025-01-30 13:45:13 - auth blocked POST /login from 10.0.0.1:443 (limit: 10) 2025-01-30 13:45:14 - resource blocked DELETE resource123 from 127.0.0.1:9000 (limit: 50)

Request conversion details

The convertWAIRequest function creates a compact representation of WAI requests:

• **IPv4 addresses**: 192.168.1.100:8080
• **IPv6 addresses**: 2001:0db8:0000:0000:0000:0000:0000:0001:443
• **Unix sockets**: Port information is omitted
• **Empty query strings**: Only the path is included
• **Non-empty query strings**: Included with the leading ? character

Thread-safety

All predefined notifiers are **thread-safe** because they only use atomic functions from the base and text packages. The timestamp generation using getCurrentTime is also thread-safe.

If you write a custom notifier that has internal mutable state (such as counters, caches, or connection pools), you must ensure its operations are properly synchronized using appropriate concurrency primitives like STM, MVar, or IORef with atomic operations.

Error handling considerations

The predefined notifiers (consoleNotifier, consoleWAINotifier) do not handle IO exceptions that might occur during logging operations. In production environments, you may want to wrap these notifiers with appropriate error handling:

import Control.Exception (try, SomeException)

safeNotifier :: Notifier -> Notifier
safeNotifier baseNotifier = baseNotifier
  { notifierAction = \throttle act item limit -> do
      result <- try $ notifierAction baseNotifier throttle act item limit
      case result of
        Left (_ :: SomeException) -> 
          -- Log the error or use a fallback strategy
          pure ()
        Right _ -> pure ()
  }

Performance considerations

• The convertWAIRequest function uses unsafePerformIO internally for IP resolution. This is marked with NOINLINE to prevent duplication and ensure predictable behavior.
• Timestamp generation occurs for every notification, which involves system calls. For high-throughput applications, consider batching notifications or using asynchronous logging mechanisms.
• The console notifiers write to stdout synchronously, which may become a bottleneck under heavy load. Consider using buffered or asynchronous alternatives for production deployments.

Testing support

The module is designed with testability in mind:

• noopNotifier and noopWAINotifier can be used in test environments to suppress output
• The modular design allows easy substitution of test doubles
• All notification functions are pure except for the final IO action, making them easy to test with custom capture mechanisms

Example test notifier:

import Data.IORef

createTestNotifier :: IORef [Text] -> Notifier
createTestNotifier outputRef = Notifier
  { notifierName = "test"
  , notifierAction = \throttle act item limit -> do
      now <- getCurrentTime
      let timestamp = formatTime defaultTimeLocale "%Y-%m-%d %H:%M:%S" now
          parts = [throttle, act, item, T.concat ["(limit: ", T.pack (show limit), ")"]]
          message = T.intercalate " " $ filter (not . T.null) parts
          fullMessage = T.pack timestamp <> " - " <> message
      modifyIORef' outputRef (fullMessage :)
  }