feat: audit log improvements — CSV/JSON export and real-time WebSocket stream

[BillChirico]

Summary

Enhances the audit log system with two missing features from the issue:

✅ Export to CSV/JSON

• New endpoint: GET /guilds/:id/audit-log/export
• Supports format=csv or format=json (default)
• Up to 10k rows per export (vs 100 for paginated view)
• All existing filters apply (action, userId, startDate, endDate)
• CSV uses proper RFC 4180 quoting (escapeCsvValue)
• JSON wraps entries with metadata (guildId, exportedAt, count)
• Triggers file download via Content-Disposition: attachment

✅ Real-time WebSocket updates

• New WebSocket server on /ws/audit-log (same HMAC ticket auth as /ws/logs)
• Clients authenticate, then receive live entry events as mutations are committed
• Optional per-client filter: { type: 'filter', guildId, action, userId }
• Broadcast hooks into insertAuditEntry via RETURNING clause (no extra query)
• Lifecycle wired into startServer/stopServer
• Cap of 10 concurrent clients; 30s heartbeat

Already present (no changes needed)

• ✅ Filter by action type, user, date range — existed in the original route
• ✅ Pagination — existed in the original route

Tests

• 30 route tests (existing 14 + 16 new export tests)
• 17 WebSocket stream tests (connection, auth, filtering, broadcast, edge cases)
• All 47 new tests pass

Diff stat

src/api/middleware/auditLog.js    |  24 ++-
src/api/routes/auditLog.js        | 201 ++++++++++-----
src/api/server.js                 |  12 ++
src/api/ws/auditStream.js         | 322 +++++++++++++++++++++++++++
tests/api/routes/auditLog.test.js | 234 ++++++++++++++++++++
tests/api/ws/auditStream.test.js  | 349 +++++++++++++++++++++++++++++++
6 files changed, 1102 insertions(+), 40 deletions(-)

Closes #136

[coderabbitai]

Warning

Rate limit exceeded

@BillChirico has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 25 minutes and 49 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 4c49a09 and 7bbcade.

📒 Files selected for processing (6)

• src/api/middleware/auditLog.js
• src/api/routes/auditLog.js
• src/api/server.js
• src/api/ws/auditStream.js
• tests/api/routes/auditLog.test.js
• tests/api/ws/auditStream.test.js

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/issue-136

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds audit log export (CSV/JSON) and a real-time WebSocket audit stream to improve dashboard audit log consumption.

Changes:

• Added GET /guilds/:id/audit-log/export with CSV/JSON output, larger limits, and export-specific rate limiting.
• Introduced /ws/audit-log WebSocket stream with HMAC ticket auth, optional filtering, heartbeat, and client cap.
• Updated audit log insertion to RETURNING the inserted row and broadcast it to connected WebSocket clients.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/api/middleware/auditLog.js	Broadcasts newly inserted audit entries to the audit WebSocket stream using RETURNING row data.
src/api/routes/auditLog.js	Adds export endpoint, CSV helpers, and refactors shared filter-building logic.
src/api/server.js	Wires audit stream lifecycle into server start/stop.
src/api/ws/auditStream.js	Implements WebSocket audit log streaming server (auth, filter, heartbeat, broadcast).
tests/api/routes/auditLog.test.js	Adds unit tests for CSV helpers and integration tests for the export endpoint.
tests/api/ws/auditStream.test.js	Adds coverage for audit stream connection/auth/filter/broadcast behaviors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

This PR successfully implements the two missing features from issue #136: CSV/JSON export and real-time WebSocket streaming for audit logs.

Key Changes:

• Export endpoint (GET /guilds/:id/audit-log/export) supports CSV and JSON formats with up to 10k rows, proper RFC 4180 CSV escaping, and all existing filters
• WebSocket server (/ws/audit-log) provides real-time updates using HMAC ticket authentication (matching the existing log stream pattern), client-side filtering, and 30-second heartbeat
• Broadcast integration uses PostgreSQL RETURNING clause to broadcast new entries without additional queries
• Code refactoring extracted filter logic into reusable buildFilters() helper

Implementation Quality:

• Follows all project conventions: ESM modules, Winston logging, parameterized queries, proper error handling
• Comprehensive test coverage with 47 total tests (30 route + 17 WebSocket tests)
• Defensive programming with try-catch blocks preventing audit failures from affecting streaming
• Enhanced WebSocket heartbeat with readyState checks and error handling (improvement over existing log stream)
• Configurable auth timeout via AUDIT_STREAM_AUTH_TIMEOUT_MS environment variable

Architecture:

• Non-blocking audit middleware ensures streaming failures don't impact audit integrity
• Proper lifecycle management integrated into server startup/shutdown
• Rate limiting: 30 req/min for standard queries, 10 req/min for exports
• Max 10 concurrent WebSocket clients with automatic cleanup

Confidence Score: 5/5

• This PR is safe to merge with high confidence
• Code follows all project security and style conventions, has comprehensive test coverage, uses parameterized queries throughout, implements proper authentication (HMAC tickets for WebSocket, guild admin middleware for HTTP), includes defensive error handling, and introduces no breaking changes or security vulnerabilities
• No files require special attention

Important Files Changed

Filename	Overview
src/api/middleware/auditLog.js	Modified to broadcast audit entries to WebSocket clients via RETURNING clause integration
src/api/routes/auditLog.js	Added export endpoint with CSV/JSON formats and refactored filter logic into reusable buildFilters helper
src/api/server.js	Integrated audit stream lifecycle (setup/teardown) into server startup and shutdown
src/api/ws/auditStream.js	New WebSocket server for real-time audit log streaming with HMAC auth, filtering, and heartbeat

Sequence Diagram

sequenceDiagram
    participant Client as Dashboard Client
    participant HTTP as Express Server
    participant WS as WebSocket Server
    participant Middleware as Audit Middleware
    participant DB as PostgreSQL
    
    Note over Client,DB: Real-time Audit Stream Flow
    Client->>WS: Connect to /ws/audit-log
    WS->>Client: Connection established
    Client->>WS: {type: 'auth', ticket: 'hmac'}
    WS->>WS: Validate HMAC ticket
    WS->>Client: {type: 'auth_ok'}
    Client->>WS: {type: 'filter', guildId, action}
    WS->>Client: {type: 'filter_ok'}
    
    Note over Client,DB: Mutation triggers broadcast
    Client->>HTTP: PUT /guilds/:id/config
    HTTP->>Middleware: Audit middleware intercepts
    Middleware->>DB: INSERT ... RETURNING *
    DB->>Middleware: Return new entry with id
    Middleware->>WS: broadcastAuditEntry(entry)
    WS->>WS: Match against client filters
    WS->>Client: {type: 'entry', entry: {...}}
    
    Note over Client,DB: Export Flow
    Client->>HTTP: GET /guilds/:id/audit-log/export?format=csv
    HTTP->>HTTP: Validate auth & guild admin
    HTTP->>DB: SELECT * WHERE ... LIMIT 10000
    DB->>HTTP: Return matching entries
    HTTP->>Client: CSV file download

Loading

_{Last reviewed commit: 7bbcade}

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.