Interface McpAuditSink

All Known Implementing Classes:
FanOutAuditSink, FileAuditSink, KafkaAuditSink, S3AuditSink, SplunkAuditSink, SpoolingAuditSink, SyslogAuditSink
public interface McpAuditSink
Where a generated MCP server sends its audit records.

A service-provider interface rather than a built-in: MCP_AUDIT_SINK names an implementing class, exactly as DAO_LOG_TYPE selects a LogInterface backend. That keeps every client library — Kafka's included — an optional dependency nobody else pays for, and makes a broker, a database table and a file three implementations rather than three forks of the emitted code.

Implementations need a public no-argument constructor and must configure themselves from the environment.

record(com.mcpdbwizard.pub.McpAuditEvent) must not throw. It is called from a finally on the tool-call path, so an exception escaping it would replace the caller's real result — or its real error — with a failure of the audit system. A sink that cannot deliver should count and report, not propagate. Whether it should also block is the deployment's decision and belongs in the implementation; see docs/mcp-audit-sink-plan.md §2.3. Copyright 2003-2026 ATB Consultancy Services Ltd (formerly Orinda Software Ltd, Dublin, Ireland)

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
     
    default String
    describe()
    A short human description of what this sink is, for an operator reading a status page.
    default boolean
    flush()
    Confirm that everything handed to record(com.mcpdbwizard.pub.McpAuditEvent) since the last flush is durably accepted.
    default long
    getDeliveredCount()
    How many records were confirmed delivered, or -1 when the sink does not report.
    default long
    getDroppedCount()
    How many records this sink is known to have LOST, or -1 when it does not report.
    default long
    getPendingCount()
    How many records are written down but not yet delivered, or -1 when not reported.
    void
    record(McpAuditEvent theEvent)
    Record one call.

  • Method Details

    • record

      void record(McpAuditEvent theEvent)
      Record one call. Must not throw.
      Parameters:
      theEvent - the call to record; never null

    • flush

      default boolean flush()
      Confirm that everything handed to record(com.mcpdbwizard.pub.McpAuditEvent) since the last flush is durably accepted.

      This is what makes a spool possible. A spool writes each record to disk first and may only delete it once the sink has genuinely taken it — and for an asynchronous sink like Kafka, record returning tells you nothing, because the send has not completed yet.

      The default returns true, which is correct for a sink that delivers synchronously inside record. An asynchronous sink must override it, and must return false if anything since the last flush was lost — returning true on a failed batch would let a spool delete records that never arrived, which is the one way a spool can be worse than no spool.

      Returns:
      true if everything since the last flush is safely delivered

    • getDroppedCount

      default long getDroppedCount()
      How many records this sink is known to have LOST, or -1 when it does not report.

      The number an operator actually needs, and the one nothing surfaced before: a trail is only worth citing if it is complete, and "complete" is exactly what a drop count denies. Reported through the SPI rather than by casting to a particular sink so a status page keeps working when the sink is swapped.

      -1 means "this sink does not count", which a caller must show differently from 0. Claiming zero losses on a sink that cannot tell is the one wrong answer here.

    • getDeliveredCount

      default long getDeliveredCount()
      How many records were confirmed delivered, or -1 when the sink does not report.

    • getPendingCount

      default long getPendingCount()
      How many records are written down but not yet delivered, or -1 when not reported.

    • describe

      default String describe()
      A short human description of what this sink is, for an operator reading a status page.

      Defaults to the class name. A wrapper overrides it to name what it wraps — otherwise a spooled Kafka sink reports only "SpoolingAuditSink", and where the records finally go is the part being asked about.

    • close

      void close()