feat: Compatibility layer

[codcod]

Python-smpplib Compatibility Gap Analysis

Executive Summary

This document analyzes the gaps between the current smppai library and python-smpplib to determine what features need to be implemented to make smppai a complete drop-in replacement for python-smpplib.

Overview

python-smpplib is a mature SMPP client library that has been widely used in production environments. smppai is a modern async SMPP implementation with both client and server capabilities. This analysis identifies the missing features needed for full compatibility.

Current Status Comparison

Architecture Differences

Aspect	python-smpplib	smppai	Gap Status
Paradigm	Synchronous + Threading	Async/Await Native	✅ Modern Improvement
Server Support	❌ Client Only	✅ Full Server Implementation	✅ Enhancement
Python Version	2.7 + 3.x	3.13+	✅ Modern
Type Hints	❌ None	✅ Full Coverage	✅ Enhancement

Core Functionality Gaps

1. Missing PDU Types

Critical Missing PDUs (High Priority)

PDU Type	python-smpplib	smppai	Impact	Priority
REPLACE_SM	✅	❌	Cannot replace existing messages	CRITICAL
REPLACE_SM_RESP	✅	❌	Cannot handle replace responses	CRITICAL
CANCEL_SM	✅	❌	Cannot cancel submitted messages	CRITICAL
CANCEL_SM_RESP	✅	❌	Cannot handle cancel responses	CRITICAL
SUBMIT_MULTI	✅	❌	Cannot send to multiple destinations	HIGH
SUBMIT_MULTI_RESP	✅	❌	Cannot handle multi-submit responses	HIGH

Implemented PDUs (Available in Both)

PDU Type	python-smpplib	smppai	Status
BIND_TRANSMITTER	✅	✅	✅ Compatible
BIND_RECEIVER	✅	✅	✅ Compatible
BIND_TRANSCEIVER	✅	✅	✅ Compatible
UNBIND	✅	✅	✅ Compatible
SUBMIT_SM	✅	✅	✅ Compatible
DELIVER_SM	✅	✅	✅ Compatible
ENQUIRE_LINK	✅	✅	✅ Compatible
GENERIC_NACK	✅	✅	✅ Compatible
DATA_SM	✅	✅	✅ Compatible
QUERY_SM	✅	✅	✅ Compatible
ALERT_NOTIFICATION	✅	✅	✅ Compatible

2. Client API Compatibility

Missing Client Methods (Critical for Migration)

# python-smpplib methods NOT in smppai
class Client:
    # Message operations
    def send_message(**kwargs)        # ❌ Missing in smppai
    def query_message(**kwargs)       # ❌ Missing in smppai
    def cancel_message(**kwargs)      # ❌ Missing in smppai - PDU missing
    def replace_message(**kwargs)     # ❌ Missing in smppai - PDU missing
    def send_multi_message(**kwargs)  # ❌ Missing in smppai - PDU missing

    # Event handlers
    def set_message_received_handler(func)  # ❌ Missing in smppai
    def set_message_sent_handler(func)      # ❌ Missing in smppai
    def set_query_resp_handler(func)        # ❌ Missing in smppai
    def set_error_pdu_handler(func)         # ❌ Missing in smppai

    # Connection management
    def listen()                      # ❌ Missing in smppai
    def read_once()                   # ❌ Missing in smppai
    def poll()                        # ❌ Missing in smppai

    # Sequence management
    def next_sequence()               # ❌ Missing in smppai
    @property sequence                # ❌ Missing in smppai

Current smppai Client Methods

# smppai provides different API
class SMPPClient:
    async def connect()
    async def bind_transmitter()
    async def bind_receiver()
    async def bind_transceiver()
    async def submit_sm()
    async def unbind()
    async def disconnect()

3. GSM-Specific Features

Message Segmentation (Critical Gap)

# python-smpplib provides
import smpplib.gsm
parts, encoding_flag, msg_type_flag = smpplib.gsm.make_parts(u'Long message...')

# smppai equivalent: ❌ MISSING
# No equivalent functionality for:
# - Automatic message segmentation
# - UDH (User Data Header) handling
# - Concatenated SMS support
# - GSM 7-bit encoding

Encoding Support Gaps

Feature	python-smpplib	smppai	Gap
GSM 7-bit	✅	❌	CRITICAL
UCS2/Unicode	✅	✅	✅
Binary Data	✅	✅	✅
Auto-detection	✅	❌	HIGH

4. Constants and Enums

Missing Constants (Medium Priority)

# python-smpplib constants missing in smppai
SMPP_TON_*           # Type of Number constants
SMPP_NPI_*           # Numbering Plan Indicator
SMPP_ENCODING_*      # Encoding type constants
SMPP_MSGMODE_*       # Message mode constants
SMPP_MSGTYPE_*       # Message type constants
SMPP_GSMFEAT_*       # GSM feature constants

5. Compatibility Layer Requirements

1. Synchronous Wrapper (Critical for Migration)

# Required compatibility layer
class SyncSMPPClient:
    """Synchronous wrapper around async SMPPClient for python-smpplib compatibility"""

    def __init__(self, host, port, timeout=5, **kwargs):
        # Wrap async client with sync interface

    def connect(self):
        # asyncio.run(self._async_client.connect())

    def bind_transmitter(self, **kwargs):
        # asyncio.run(self._async_client.bind_transmitter(**kwargs))

    def send_message(self, **kwargs):
        # Map to submit_sm with proper parameter translation

    def listen(self):
        # Event loop for message handling

2. Parameter Mapping

# python-smpplib uses snake_case, smppai may differ
PARAMETER_MAPPING = {
    'source_addr_ton': 'source_addr_ton',      # Same
    'dest_addr_ton': 'dest_addr_ton',          # Same
    'destination_addr': 'destination_addr',     # Same
    'short_message': 'short_message',          # Same
    'registered_delivery': 'registered_delivery', # Same
    # Add any differences
}

6. Implementation Priority

Phase 1: Critical Compatibility (Weeks 1-2)

1. Add missing PDU types:

   • REPLACE_SM / REPLACE_SM_RESP
   • CANCEL_SM / CANCEL_SM_RESP
   • SUBMIT_MULTI / SUBMIT_MULTI_RESP

2. Create synchronous client wrapper

3. Add missing client methods: send_message(), query_message()

4. Basic event handler system

Phase 2: GSM Features (Weeks 3-4)

1. Message segmentation (smpplib.gsm equivalent)
2. GSM 7-bit encoding support
3. UDH handling for concatenated SMS
4. Encoding auto-detection

Phase 3: Advanced Compatibility (Weeks 5-6)

1. Complete constants mapping
2. Advanced event handlers
3. Sequence number management compatibility
4. SSL/TLS support parity

Phase 4: Testing & Validation (Weeks 7-8)

1. Migration test suite
2. Performance benchmarking
3. Memory usage optimization
4. Documentation and examples

7. Breaking Changes to Avoid

To maintain compatibility, these python-smpplib behaviors should be preserved:

1. Parameter names must match exactly
2. Return value formats should be compatible
3. Exception types should map appropriately
4. Event handler signatures must match
5. Default values should be preserved

8. Recommended Implementation Strategy

Option A: Compatibility Layer (Recommended)

• Keep smppai's modern async API as primary
• Add smppai.compat module with python-smpplib compatible interface
• Allows gradual migration and supports both paradigms

Option B: Direct Integration

• Modify smppai's primary API to match python-smpplib
• Risk breaking existing smppai users
• Less flexibility for modern async applications

9. Migration Guide Template

# Before (python-smpplib)
import smpplib.client
import smpplib.consts

client = smpplib.client.Client('host', 2775)
client.connect()
client.bind_transceiver(system_id='test', password='test')
pdu = client.send_message(
    source_addr_ton=smpplib.consts.SMPP_TON_INTL,
    source_addr='1234',
    dest_addr_ton=smpplib.consts.SMPP_TON_INTL,
    destination_addr='5678',
    short_message=b'Hello'
)

# After (smppai with compatibility layer)
import smppai.compat as smpplib_compat

client = smpplib_compat.Client('host', 2775)
client.connect()
client.bind_transceiver(system_id='test', password='test')
pdu = client.send_message(
    source_addr_ton=smpplib_compat.SMPP_TON_INTL,
    source_addr='1234',
    dest_addr_ton=smpplib_compat.SMPP_TON_INTL,
    destination_addr='5678',
    short_message=b'Hello'
)

10. Success Metrics

• 100% API compatibility for core SMPP operations
• Migration time < 1 hour for typical python-smpplib projects
• Performance parity or better than python-smpplib
• Zero code changes required for basic use cases
• Comprehensive test coverage for compatibility layer

Conclusion

While smppai provides a solid foundation with modern async architecture and server capabilities, it requires significant compatibility additions to serve as a drop-in replacement for python-smpplib. The primary gaps are:

1. Missing PDU types (REPLACE_SM, CANCEL_SM, SUBMIT_MULTI)
2. Synchronous client interface for easy migration
3. GSM-specific features (message segmentation, 7-bit encoding)
4. Event handler system matching python-smpplib patterns

With focused development effort (6-8 weeks), smppai can become a superior replacement that maintains full backward compatibility while offering modern async capabilities and server functionality.