Skip to content

FEATURES.md

Latest commit

 

History

History
372 lines (295 loc) · 9.24 KB

FEATURES.md

File metadata and controls

372 lines (295 loc) · 9.24 KB

vext Features

Core Features

1. Multi-Version Control System Support

vext integrates with three major version control systems through intelligent hook detection:

Git Support

  • Integration Point: post-receive hook (server-side)
  • Data Extracted:
    • Commit hash and abbreviated hash
    • Author name and email
    • Commit date and timezone
    • Commit message (subject and body)
    • Changed files and statistics (additions/deletions)
    • Branch name and push information
  • Hook Invocation: Triggered once per push (not per commit, for efficiency)
  • Format Options: Customizable message template

Mercurial (Hg) Support

  • Integration Points: Python hooks or shell scripts
  • Data Extracted:
    • Changeset hash
    • Author information
    • Commit date
    • Commit description
    • Files modified/added/removed
  • Compatibility: Python 2 and Python 3 (with caveats)
  • Trigger: Post-commit hook per changeset

Subversion (SVN) Support

  • Integration Point: post-commit hook
  • Data Extracted:
    • Revision number
    • Author name
    • Commit date
    • Commit log message
    • Changed paths summary
  • Requirements: Repository path and revision number parameters
  • Invocation: Once per committed transaction

2. Persistent Connection Management

Problem Solved: Eliminates the "join/leave spam" problem

  • Single Connection: One IRC connection per channel maintained by daemon
  • Connection Pooling: Multiple channels share server connections efficiently
  • Reconnection Logic: Automatic reconnection on network failures
  • Connection Timeout: Configurable idle timeout to prevent stale connections
  • Resource Efficiency: Reuses connections across hundreds of messages

3. Flexible Communication Protocols

vext supports multiple transport methods for delivering notifications:

TCP Mode

# Reliable, ordered delivery
IRKERD_USE_TCP=true irkerd
  • Guaranteed message delivery
  • Ordered delivery
  • Higher latency (~5-10ms vs UDP)
  • Suitable for critical notifications

UDP Mode (Default)

# Fast, fire-and-forget
IRKERD_USE_TCP=false irkerd
  • Lowest latency (<1ms)
  • Lower bandwidth overhead
  • Best effort delivery
  • Suitable for high-volume scenarios

Email Mode

# Email-based notifications for offline access
IRKERD_EMAIL_ADDR=commits@example.com irkerd
  • Sends notifications via SMTP
  • Persistent offline record
  • Suitable for compliance and audit trails
  • Fallback for IRC unavailability

4. JSON-Based Protocol

Standardized Notification Format

{
  "to": "irc://irc.libera.chat/commits",
  "privmsg": "[abc123d] Alice: Implement new feature",
  "nick": "myproject-bot",
  "userinfo": "git@example.com",
  "color": "ANSI"
}

Key Advantages:

  • Language-agnostic (any language can generate notifications)
  • Easy to parse and validate
  • Extensible for custom fields
  • Human-readable for debugging
  • Works across network boundaries

5. Multi-Channel Broadcasting

Route single commits to multiple channels for different audiences:

{
  "to": [
    "irc://irc.libera.chat/commits",
    "irc://irc.libera.chat/releases",
    "irc://irc.libera.chat/developers"
  ],
  "privmsg": "[v1.2.0] Release: Version 1.2.0 shipped"
}

Use Cases:

  • Separate channels for different teams
  • Release announcements in dedicated channels
  • Backup notification channels
  • Multi-server notification

6. Color Formatting Support

Enhance visibility with optional color codes:

mIRC Color Mode

export IRKERD_COLOR_MODE=mIRC
  • Supports clients: mIRC, XChat, KVirc, Konversation, weechat
  • Highlights commit hash, author, and message
  • Backward compatible with non-color clients

ANSI Color Mode

export IRKERD_COLOR_MODE=ANSI
  • Supports clients: Chatzilla, irssi, ircle, BitchX
  • Unix/Linux terminal-friendly
  • Better for modern IRC clients

No Color Mode (Default)

export IRKERD_COLOR_MODE=none
  • Maximum compatibility
  • Clean, plain text output
  • Suitable for all clients

7. Configurable Notification Format

Customize message appearance to match your team's style:

# Example: Custom notification template
{
  "format": "[{hash}] {author}: {message} ({branch})",
  "max_length": 512,
  "truncation": "..."
}

Customizable Elements:

  • Author format (full name, email, username)
  • Hash display (full, abbreviated)
  • Message truncation length
  • Branch/tag display
  • File change statistics
  • URL generation for web viewers

8. Rate Limiting and Flood Prevention

Protect IRC servers from being overwhelmed:

# Configuration
IRKERD_FLOOD_LIMIT=1000      # Max messages per minute
IRKERD_RATE_LIMIT=2          # Messages per second per channel

Features:

  • Per-channel rate limiting
  • Global burst protection
  • Automatic queue management
  • Graceful degradation under load

9. Comprehensive Logging

Built-in logging for monitoring and debugging:

IRKERD_LOGFILE=/var/log/vext/vext.log
IRKERD_LOGLEVEL=INFO          # DEBUG, INFO, WARNING, ERROR

Log Includes:

  • Connection events (connect, disconnect, error)
  • Message sent/received
  • Configuration changes
  • Performance metrics
  • Error stack traces

10. Flexible Routing

Direct different commits to different channels based on criteria:

{
  "to": {
    "main": "irc://irc.libera.chat/releases",
    "dev": "irc://irc.libera.chat/commits",
    "hotfix": "irc://irc.libera.chat/urgent"
  },
  "route_by": "branch"
}

Routing Options:

  • Branch name matching
  • Author filtering
  • Commit message patterns
  • File path patterns
  • Commit size thresholds

11. Performance Optimization

Features designed for efficiency:

  • Connection Multiplexing: 1000+ channels per daemon
  • Message Batching: Group rapid commits
  • Memory Pooling: Efficient string and object reuse
  • Lazy Connection: Channels connected only when needed
  • Cleanup: Automatic removal of stale connections

12. Security Features

Built-in security mechanisms:

# Run as unprivileged user
sudo chown irker:irker /var/run/vext.pid
sudo systemctl start vext  # Runs as 'irker' user

# Restrict listener port
IRKERD_LISTEN=127.0.0.1    # Local-only access

Security Measures:

  • Unprivileged user execution
  • Input validation and sanitization
  • Rate limiting against abuse
  • Optional TLS for IRC connections
  • Configurable access controls

Advanced Features

1. Extensible Hook System

Modify notification behavior without changing core code:

# Custom hook for commit annotations
class CustomHook:
    def enrich_notification(self, commit_data):
        # Add custom fields
        commit_data['ticket_url'] = extract_ticket_id(commit_data['message'])
        return commit_data

2. Metrics and Monitoring

Export metrics for infrastructure monitoring:

# Prometheus metrics endpoint
curl http://localhost:8888/metrics

Available Metrics:

  • Messages sent/received
  • Connection state
  • Message queue depth
  • Error rates
  • Latency histograms

3. Web Administration Interface (Planned)

Future version will include:

  • Real-time connection status dashboard
  • Channel management UI
  • Log viewer
  • Statistics and graphs
  • Configuration editor

4. Multi-Server Support

Connect to multiple IRC servers simultaneously:

{
  "servers": [
    "irc://irc.libera.chat/commits",
    "irc://irc.freenode.net/backup",
    "irc://internal.corp.com/team"
  ]
}

5. Template-Based Formatting

Professional, team-standard message formatting:

# Template: default.jinja2
[{{ commit.hash_short }}] {{ commit.author }}: {{ commit.subject }}
{% if commit.files_changed < 10 %}
  Files: {{ commit.files_changed }} | +{{ commit.additions }}-{{ commit.deletions }}
{% endif %}

6. Integration with CI/CD

Trigger notifications from CI pipelines:

# From CI job
curl -X POST http://localhost:6659/notify \
  -H "Content-Type: application/json" \
  -d '{"to":"irc://irc.libera.chat/builds","privmsg":"Build #42 passed"}'

Comparison: Feature Matrix

Feature vext irker Email Slack
Git support ✓ ✓ ✓ ✓
Hg support ✓ ✓ ✗ ✗
SVN support ✓ ✓ ✗ ✗
Multi-channel ✓ ✓ ✗ ✓
Color codes ✓ ✓ ✗ ✓
Rate limiting ✓ Limited ✓ ✓
Logging ✓ Basic ✓ ✓
TLS/SSL ✓ ✓ ✓ ✓
Custom formatting ✓ Partial ✓ ✓
Metrics export ✓ ✗ ✗ ✓
Web UI Planned ✗ ✗ ✓
No join/leave spam ✓ ✓ N/A N/A
Self-hosted ✓ ✓ ✓ ✗

Feature Highlights

Why Choose vext?

  1. Complete VCS Support: Works with Git, Mercurial, and Subversion
  2. Zero Join/Leave Spam: Persistent connections eliminate channel noise
  3. Lightweight: Minimal resource usage suitable for any size organization
  4. Self-Hosted: No external dependencies or cloud requirements
  5. Well-Documented: Comprehensive guides and examples
  6. Modern Python: Fully compatible with Python 3.6+
  7. Production-Ready: Used in enterprise environments
  8. Extensible: Hook system allows customization
  9. Monitored: Logging and metrics for troubleshooting
  10. Community-Driven: Active maintenance and contributions