AGNTCY Slim v0.6.0 Release

[msardara]

SLIM v0.6.0 Release Announcement 🚀

We're excited to announce the release of SLIM (Secure Low-Latency Interactive Messaging) v0.6.0! This major release brings significant improvements to the session management API, enhanced Python bindings, better control plane functionality, and numerous performance optimizations.

🎯 Key Highlights

🔥 Major Breaking Changes & API Improvements

Session API Refactoring (#598)

• BREAKING CHANGE: Complete overhaul of the session receive() API for better clarity and lifecycle management
• BREAKING CHANGE: Split Python receive() into listen_for_session() and get_message() for per-session message handling
• BREAKING CHANGE: Introduced new SessionContext (Rust & Python) replacing legacy Info/SessionMessage structures
• BREAKING CHANGE: Session-scoped methods for publish, invite, remove, and config operations
• BREAKING CHANGE: New Notification enum for cleaner app-to-user event handling
• BREAKING CHANGE: Eliminated ambiguous, multiplexed receive operations for more predictable behavior

🐍 Enhanced Python Bindings

Comprehensive Python API Improvements

• Improved Documentation (feat(python/bindings): improve documentation #748, docs(python/bindings): add documentantion for sessions and example #750): Enhanced documentation with better examples and usage patterns
• Enhanced Publish Function (feat(python/bindings): improve publish function #749): More intuitive and feature-rich publishing capabilities
• Session Metadata Support (feat(session): introduce session metadata #744): Full session metadata support in Python bindings
• Exposed Session Details (feat(pysession): expose session type, src and dst names #737): Access to session type, source, and destination names
• Removed Request-Reply API (feat(python/bindings): remove request-reply API #677): Streamlined API by removing legacy request-reply patterns

🎛️ Control Plane Enhancements

Enhanced Reliability & Networking

• Control Plane Group Management (feat: implement control plane group management #554): Comprehensive implementation of centralized group management capabilities for coordinated multi-participant sessions
• Exponential Backoff Work Queue: Improved reliability with exponential backoff for route reconciliation operations
• Node ID Enhancements: Better node identification with group ID integration for multi-cluster deployments
• Multi-cluster Support: Enhanced Helm chart configurations for multi-cluster setups
• Connection Optimization: Skip TLS verification for local connections to improve performance

🚀 Deployment Templates & Strategies

New Deployment Templates System (#753)

• Comprehensive Deployment Strategies: Four complete deployment patterns with documentation and automation
  • Naive Strategy: Simple single-node deployment for development and testing
  • StatefulSet Strategy: Persistent storage deployment with SPIRE integration for production environments
  • DaemonSet Strategy: Node-level deployment for distributed processing scenarios
  • Multi-cluster Strategy: Cross-cluster communication with load balancing and federation
• Automated Deployment Tasks: Complete Taskfile automation for each deployment strategy
• SPIRE Integration: Built-in SPIRE support for enhanced security across deployment strategies
• Example Client Applications: Ready-to-use sender/receiver applications for testing each strategy
• Kind Cluster Support: Local development support with automated Kind cluster creation

📡 Session & Communication Improvements

Session Management

• Session Metadata (feat(session): introduce session metadata #744): Rich metadata support for better session tracking and management
• Point-to-Point Enhancements (feat: improve point to point session with sender/receiver buffer #735): Improved sender/receiver buffer management for better performance
• Group Simplification (feat(multicast): remove moderator parameter from configuration #739): Removed moderator parameter from group configuration for easier setup
• Message Naming (feat: add string name on pub messages #693): Added string names to published messages for better debugging and tracing

Group Management Improvements

• Centralized Group Control: Control plane now can manage group lifecycle, membership, and coordination
• Simplified Group Configuration: Streamlined group setup
• Enhanced Group Reliability: Better handling of concurrent group membership changes and state synchronization

🔐 Security & Infrastructure

Authentication & Security

• Basic Auth for Ingress (feat: add basic auth to ingress #722): Added HTTP basic authentication support for ingress endpoints
• Rust Toolchain Upgrade (build: upgrade to rust toolchain 1.90.0 #730): Updated to Rust toolchain 1.90.0 for latest security and performance improvements

⚠️ Migration Guide

Overview of Changes

The API has undergone a fundamental architectural shift from app-centric messaging to session-centric messaging:

• Old paradigm: Messages sent through the Slim application instance with session IDs
• New paradigm: Messages sent directly through Session objects

---

1. Dependency Updates

Update your requirements

# pyproject.toml or requirements.txt
- slim-bindings>=0.5.0
+ slim-bindings>=0.6.0

---

2. Application Instance Management

Instance ID Access

# OLD: Method call
app = await slim_bindings.Slim.new(name, provider, verifier)
instance_id = app.get_id()

# NEW: Property access
app = await slim_bindings.Slim.new(name, provider, verifier)
instance_id_str = app.id_str
instance_id = app.id

Context Manager Usage

# OLD: Required context manager
async with app:
    session = await app.create_session(config)
    await app.publish(session, message, destination)

# NEW: No context manager needed
session = await app.create_session(config)
await session.publish(message)

Migration: Remove async with app: context managers, replace app.get_id() with app.id_str or app.id.

---

3. Session Configuration (Major Changes)

The session configuration system has been completely redesigned around communication patterns.

Old Session Types → New Session Types

Fire-and-Forget → PointToPoint

# OLD: Fire-and-forget with sticky=True
session = await app.create_session(
    slim_bindings.PySessionConfiguration.FireAndForget(
        max_retries=5,
        timeout=datetime.timedelta(seconds=5),
        sticky=True,  # Sticky = same peer
        mls_enabled=enable_mls,
    )
)

# NEW: Explicit PointToPoint
session = await app.create_session(
    slim_bindings.PySessionConfiguration.PointToPoint(
        peer_name=remote_name,
        # uncomment to enable reliable delivery and MLS
        # max_retries=5,
        # timeout=datetime.timedelta(seconds=5),
        # mls_enabled=enable_mls,
    )
)

Streaming → Group

# OLD: Bidirectional streaming with topic
session = await app.create_session(
    slim_bindings.PySessionConfiguration.Streaming(
        slim_bindings.PySessionDirection.BIDIRECTIONAL,
        topic=channel_name,
        moderator=True,
        max_retries=5,
        timeout=datetime.timedelta(seconds=5),
        mls_enabled=enable_mls,
    )
)

# NEW: Group with channel
session = await app.create_session(
    slim_bindings.PySessionConfiguration.Group(
        channel_name=channel_name,
        # uncomment to enable reliable delivery and MLS
        # max_retries=5,
        # timeout=datetime.timedelta(seconds=5),
        # mls_enabled=enable_mls,
    )
)

Migration Mapping:

• FireAndForget(sticky=True) → PointToPoint(peer_name=target)
• Streaming(BIDIRECTIONAL, topic=X) → Group(channel_name=X)

---

5. Message Sending

The message sending API has moved from app-level methods to session-level methods.

Basic Message Publishing

# OLD: App-level publishing with session reference
await app.publish(session, message.encode(), destination_name)

# NEW: Session-level publishing

# For PointToPoint/Group (destination implicit)
await session.publish(message.encode())

Reply to Received Messages

# OLD: App-level reply
await app.publish_to(session_info, reply.encode())

# NEW: Session-level reply with message context
await session.publish_to(msg_ctx, reply.encode())

---

6. Message Receiving

Message receiving has changed from app-level session management to session-level message handling.

Waiting for New Sessions

# OLD: App-level receive for new sessions
session_info, initial_message = await app.receive()
session_id = session_info.id

# NEW: Explicit session listening
session = await app.listen_for_session()

# Session also contains additional properties
session_id = session.id
session_metadata = session.metadata
session_type = session.session_type
session_config = session.session_config
session_src = session.src
session_dst = session.dst

Receiving Messages from Sessions

# OLD: App-level receive with session ID
session_info, message = await app.receive(session=session_id)

# NEW: Session-level message receiving
msg_ctx, message = await session.get_message()

Message Context Changes

# OLD: Session info contained properties regarding the last message received
source = session_info.destination_name:
dst = session_info.source_name

# NEW: Message context contains additional received message properties
source_name = msg_ctx.source_name
dst_name = msg_ctx.destination_name
payload_type = msg_ctx.payload_type
message_metadata = msg_ctx.metadata
input_connection = msg_ctx.input_connection

---

7. Session Lifecycle Management

Session Object Usage

# OLD: Sessions referenced by ID, managed through app
async def handle_session(app, session_id):
    while True:
        session_info, msg = await app.receive(session=session_id)
        await app.publish_to(session_info, response.encode())

# NEW: Sessions are first-class objects
async def handle_session(session):
    while True:
        msg_ctx, msg = await session.get_message()
        await session.publish_to(msg_ctx, response.encode())

Multiple Session Handling

# OLD: Track sessions by ID
active_sessions = {}
session_info, _ = await app.receive()
session_id = session_info.id
active_sessions[session_id] = session_info

# NEW: Work directly with session objects
active_sessions = []
session = await app.listen_for_session()
active_sessions.append(session)

---

8. Group Management (Invitations)

Inviting Participants

# OLD: App-level invitation management
await app.invite(session_info, participant_name)

# NEW: Session-level invitation management

# Add a participant
await session.invite(participant_name)

# Remove a participant
await session.remove(participant_name)

---

9. Error Handling Changes

Session-Related Errors

# OLD: Errors handled at app level with session IDs
try:
    session_info, msg = await app.receive(session=session_id)
except Exception as e:
    # Handle session-specific errors

# NEW: Errors handled at session level
try:
    msg_ctx, msg = await session.get_message()
except Exception as e:
    # Handle session-specific errors

---

10. Complete Migration Checklist

Phase 1: Dependencies and Basic Setup

• Update slim-bindings to >=0.6.0
• Replace app.get_id() with app.id_str
• Remove async with app: context managers

Phase 2: Session Configuration

• Map FireAndForget(sticky=True) → PointToPoint(peer_name=target)
• Map Streaming(BIDIRECTIONAL) → Group(channel_name=topic)
• Update session configuration parameters

Phase 3: Message Sending

• Replace app.publish() with session.publish()
• Replace app.publish_to() with session.publish_to()

Phase 4: Message Receiving

• Replace app.receive() with app.listen_for_session() for new sessions
• Replace app.receive(session=id) with session.get_message()
• Update message context handling (msg_ctx.source_name vs session_info.destination_name)

Phase 5: Session Management

• Update background task signatures to accept session objects instead of IDs
• Replace app.invite() with session.invite()
• Update session tracking to use objects instead of IDs

Phase 6: Testing and Validation

• Test all communication patterns (PointToPoint, Group)
• Verify MLS functionality if used
• Test error handling and edge cases
• Validate performance characteristics

---

11. Key Benefits of Migration

After migration, your code will benefit from:

• Clearer API semantics: Communication patterns are explicitly defined
• Better encapsulation: Session operations are contained within session objects
• Improved type safety: Session objects provide stronger typing
• Simplified message handling: Direct session-to-session communication
• Enhanced debugging: Session-level error handling and logging

The new API design makes the communication patterns more explicit and provides a cleaner separation of concerns between application-level and session-level operations.

🔧 Developer Experience Improvements

• Better Documentation: Comprehensive updates to Python bindings documentation with practical examples
• Cleaner APIs: Removed deprecated and confusing API patterns
• Type Safety: Enhanced type safety with new SessionContext and Notification types
• Testing: All examples and tests updated to demonstrate new API patterns
• Performance: Optimized buffer management for point-to-point sessions

🚀 Performance Improvements

• Enhanced Buffering: Improved sender/receiver buffer management for point-to-point sessions
• Optimized Message Flow: Streamlined message processing pipeline
• Reduced Overhead: Eliminated unnecessary multiplexing in the python bindings

📚 Documentation & Examples

• Updated Python bindings documentation with comprehensive examples
• New session management examples demonstrating best practices
• Migration guides for upgrading from v0.5.x
• Enhanced API reference documentation
• Updated Helm chart documentation for new control plane features

🤝 Contributing

We welcome contributions! This release includes numerous community-driven improvements. Check out our Contributing Guide to get started.

📞 Support & Community

• Documentation: https://docs.agntcy.org/messaging/slim-core/
• GitHub Issues: Report bugs or request features
• Discussions: Community discussions and Q&A

Happy messaging with SLIM v0.6.0! 🎉