0
# Utilities and Extensions
1

2
Core utilities, exception handling, native performance extensions, and optional blockchain integration components that support and extend autobahn's WebSocket and WAMP functionality.
3

4
## Capabilities
5

6
### Core Utilities
7

8
Essential utility functions for ID generation, time handling, cryptographic operations, and text processing.
9

10
```python { .api }
11
def generate_token() -> str:
12
    """Generate secure random token."""
13

14
def generate_activation_code() -> str:
15
    """Generate activation code."""
16

17
def generate_serial_number() -> str:
18
    """Generate serial number."""
19

20
def generate_user_password() -> str:
21
    """Generate user password."""
22

23
def machine_id() -> str:
24
    """Get machine identifier."""
25

26
def id() -> str:
27
    """Generate random ID."""
28

29
def rid() -> str:
30
    """Generate request ID."""
31

32
def newid() -> str:
33
    """Generate new ID."""
34

35
def utcnow() -> datetime:
36
    """Get current UTC time."""
37

38
def utcstr(ts: datetime = None) -> str:
39
    """Convert timestamp to UTC string."""
40

41
def rtime() -> float:
42
    """Get runtime."""
43

44
def encode_truncate(
45
    text: str,
46
    limit: int,
47
    encoding: str = 'utf8',
48
    return_encoded: bool = True
49
) -> bytes | str:
50
    """
51
    Truncate string to byte limit.
52
    
53
    Parameters:
54
    - text: Input text
55
    - limit: Byte limit
56
    - encoding: Text encoding
57
    - return_encoded: Return bytes if True, str if False
58
    
59
    Returns:
60
    Truncated text as bytes or string
61
    """
62

63
def xor(d1: bytes, d2: bytes) -> bytes:
64
    """
65
    XOR two byte strings.
66
    
67
    Parameters:
68
    - d1: First byte string
69
    - d2: Second byte string
70
    
71
    Returns:
72
    XOR result
73
    """
74
```
75

76
### Cryptographic Utilities
77

78
Key management and cryptographic helper functions.
79

80
```python { .api }
81
def parse_keyfile(keyfile: str) -> tuple:
82
    """
83
    Parse key file.
84
    
85
    Parameters:
86
    - keyfile: Path to key file
87
    
88
    Returns:
89
    Tuple of (private_key, public_key)
90
    """
91

92
def write_keyfile(keyfile: str, privkey: bytes, pubkey: bytes) -> None:
93
    """
94
    Write key file.
95
    
96
    Parameters:
97
    - keyfile: Path to key file
98
    - privkey: Private key bytes
99
    - pubkey: Public key bytes
100
    """
101

102
def with_0x(value: str) -> str:
103
    """Add 0x prefix to value."""
104

105
def without_0x(value: str) -> str:
106
    """Remove 0x prefix from value."""
107
```
108

109
### Text Formatting Utilities
110

111
Terminal text highlighting and formatting functions.
112

113
```python { .api }
114
def hl(text: str, color: str, bold: bool = False) -> str:
115
    """
116
    Highlight text with color.
117
    
118
    Parameters:
119
    - text: Text to highlight
120
    - color: Color name
121
    - bold: Bold formatting
122
    
123
    Returns:
124
    Formatted text
125
    """
126

127
def hltype(text: str) -> str:
128
    """Highlight type name."""
129

130
def hlid(text: str) -> str:
131
    """Highlight ID."""
132

133
def hluserid(text: str) -> str:
134
    """Highlight user ID."""
135

136
def hlval(text: str) -> str:
137
    """Highlight value."""
138

139
def hlcontract(text: str) -> str:
140
    """Highlight contract."""
141
```
142

143
### Utility Classes
144

145
Helper classes for common patterns and operations.
146

147
```python { .api }
148
class Stopwatch:
149
    """Timer utility for measuring elapsed time."""
150
    
151
    def __init__(self):
152
        """Initialize stopwatch."""
153
    
154
    def start(self) -> None:
155
        """Start timing."""
156
    
157
    def stop(self) -> float:
158
        """
159
        Stop timing.
160
        
161
        Returns:
162
        Elapsed time in seconds
163
        """
164
    
165
    def elapsed(self) -> float:
166
        """
167
        Get elapsed time without stopping.
168
        
169
        Returns:
170
        Elapsed time in seconds
171
        """
172

173
class Tracker:
174
    """Object tracker for debugging and monitoring."""
175
    
176
    def __init__(self):
177
        """Initialize tracker."""
178
    
179
    def track(self, obj: object) -> None:
180
        """Track object."""
181
    
182
    def untrack(self, obj: object) -> None:
183
        """Untrack object."""
184
    
185
    def tracked(self) -> list:
186
        """
187
        Get tracked objects.
188
        
189
        Returns:
190
        List of tracked objects
191
        """
192

193
class EqualityMixin:
194
    """Mixin for equality comparison based on attributes."""
195
    
196
    def __eq__(self, other: object) -> bool:
197
        """Check equality."""
198
    
199
    def __ne__(self, other: object) -> bool:
200
        """Check inequality."""
201

202
class ObservableMixin:
203
    """Mixin for observable pattern implementation."""
204
    
205
    def __init__(self):
206
        """Initialize observable."""
207
    
208
    def fire(self, event: str, *args, **kwargs) -> None:
209
        """Fire event to observers."""
210
    
211
    def on(self, event: str, handler: callable) -> None:
212
        """Register event handler."""
213
    
214
    def off(self, event: str, handler: callable = None) -> None:
215
        """Unregister event handler."""
216

217
class IdGenerator:
218
    """ID generation utility with various formats."""
219
    
220
    def __init__(self):
221
        """Initialize ID generator."""
222
    
223
    def next(self) -> str:
224
        """
225
        Generate next ID.
226
        
227
        Returns:
228
        Generated ID string
229
        """
230
```
231

232
### Native Extensions (NVX)
233

234
High-performance native extensions for critical operations.
235

236
```python { .api }
237
class Utf8Validator:
238
    """High-performance UTF-8 validator using native code (CFFI-based)."""
239
    
240
    def __init__(self):
241
        """Initialize UTF-8 validator."""
242
    
243
    def validate(self, data: bytes) -> tuple:
244
        """
245
        Validate UTF-8 data.
246
        
247
        Parameters:
248
        - data: Bytes to validate
249
        
250
        Returns:
251
        Tuple of (is_valid, end_of_string)
252
        """
253
    
254
    def reset(self) -> None:
255
        """Reset validator state."""
256
```
257

258
### Exception Handling
259

260
Comprehensive exception hierarchy for error handling and diagnostics.
261

262
```python { .api }
263
class Error(Exception):
264
    """Base WAMP error with structured error information."""
265
    
266
    def __init__(
267
        self,
268
        error_uri: str,
269
        args: list = None,
270
        kwargs: dict = None,
271
        enc_algo: str = None,
272
        callee: int = None,
273
        callee_authid: str = None,
274
        callee_authrole: str = None,
275
        forward_for: list = None
276
    ):
277
        """
278
        Initialize WAMP error.
279
        
280
        Parameters:
281
        - error_uri: Error URI identifying error type
282
        - args: Error arguments
283
        - kwargs: Error keyword arguments
284
        - enc_algo: Encryption algorithm used
285
        - callee: Callee session ID
286
        - callee_authid: Callee authentication ID
287
        - callee_authrole: Callee authentication role
288
        - forward_for: Forward chain information
289
        """
290

291
class ApplicationError(Error):
292
    """Application-defined error for custom error conditions."""
293

294
class InvalidUri(Error):
295
    """Invalid URI format in WAMP operations."""
296

297
class SerializationError(Error):
298
    """Message serialization/deserialization error."""
299

300
class ProtocolError(Error):
301
    """WAMP protocol violation error."""
302

303
class TransportLost(Exception):
304
    """Transport connection lost unexpectedly."""
305

306
class SessionNotReady(Exception):
307
    """Session not ready for WAMP operations."""
308

309
class PayloadExceededError(RuntimeError):
310
    """WAMP payload exceeds configured size limit."""
311

312
class Disconnected(RuntimeError):
313
    """Operation requires connection but WebSocket/RawSocket is disconnected."""
314
```
315

316
### Test Utilities
317

318
Testing support utilities for autobahn applications.
319

320
```python { .api }
321
def run_once() -> None:
322
    """Run reactor once for testing."""
323

324
def test_timeout(timeout: float = 10) -> callable:
325
    """
326
    Decorator for test timeout.
327
    
328
    Parameters:
329
    - timeout: Timeout in seconds
330
    
331
    Returns:
332
    Test decorator
333
    """
334
```
335

336
## XBR Protocol Support (Optional)
337

338
Cross Blockchain Router protocol integration for decentralized data markets (available when XBR is not stripped).
339

340
### Blockchain Integration
341

342
```python { .api }
343
# Contract ABIs
344
XBR_TOKEN_ABI: list          # XBR Token contract ABI
345
XBR_NETWORK_ABI: list        # XBR Network contract ABI  
346
XBR_MARKET_ABI: list         # XBR Market contract ABI
347
XBR_CATALOG_ABI: list        # XBR Catalog contract ABI
348
XBR_CHANNEL_ABI: list        # XBR Channel contract ABI
349

350
# Debug contract addresses
351
XBR_DEBUG_TOKEN_ADDR: str    # Debug token address
352
XBR_DEBUG_NETWORK_ADDR: str  # Debug network address
353
XBR_DEBUG_MARKET_ADDR: str   # Debug market address
354
XBR_DEBUG_CATALOG_ADDR: str  # Debug catalog address
355
XBR_DEBUG_CHANNEL_ADDR: str  # Debug channel address
356

357
def make_w3(gateway_config: dict = None) -> Web3:
358
    """
359
    Create Web3 instance.
360
    
361
    Parameters:
362
    - gateway_config: Gateway configuration
363
    
364
    Returns:
365
    Configured Web3 instance
366
    """
367

368
def pack_uint256(value: int) -> bytes:
369
    """Pack integer to uint256 bytes."""
370

371
def unpack_uint256(data: bytes) -> int:
372
    """Unpack uint256 bytes to integer."""
373

374
class SimpleBlockchain:
375
    """Simple blockchain interaction class."""
376
    
377
    def __init__(self, w3: Web3):
378
        """Initialize with Web3 instance."""
379
    
380
    def get_balance(self, address: str) -> int:
381
        """Get account balance."""
382
    
383
    def send_transaction(self, tx: dict) -> str:
384
        """Send transaction."""
385
```
386

387
### Cryptographic Classes
388

389
EIP-712 signature support for blockchain operations.
390

391
```python { .api }
392
class EIP712Certificate:
393
    """EIP-712 certificate for blockchain signatures."""
394
    
395
    def __init__(self, data: dict):
396
        """Initialize certificate."""
397
    
398
    def sign(self, private_key: bytes) -> bytes:
399
        """Sign certificate."""
400
    
401
    def verify(self, signature: bytes, public_key: bytes) -> bool:
402
        """Verify certificate signature."""
403

404
class EIP712AuthorityCertificate(EIP712Certificate):
405
    """Authority certificate for delegation."""
406

407
class EIP712DelegateCertificate(EIP712Certificate):
408
    """Delegate certificate for permissions."""
409

410
def sign_eip712_member_register(
411
    eth_privkey: bytes,
412
    member: str,
413
    registered: int,
414
    eula: str,
415
    profile: str,
416
    chain_id: int = 1
417
) -> bytes:
418
    """Sign member registration."""
419

420
def recover_eip712_member_register(
421
    signature: bytes,
422
    member: str,
423
    registered: int,
424
    eula: str,
425
    profile: str,
426
    chain_id: int = 1
427
) -> str:
428
    """Recover member registration signer."""
429
```
430

431
### Trading Classes
432

433
Data market trading implementation.
434

435
```python { .api }
436
class SimpleSeller:
437
    """Data seller implementation."""
438
    
439
    def __init__(self, private_key: bytes):
440
        """Initialize seller."""
441
    
442
    def sell_data(self, data: bytes, price: int) -> dict:
443
        """Sell data."""
444

445
class SimpleBuyer:
446
    """Data buyer implementation."""
447
    
448
    def __init__(self, private_key: bytes):
449
        """Initialize buyer."""
450
    
451
    def buy_data(self, seller: str, data_id: str) -> bytes:
452
        """Buy data."""
453

454
class KeySeries:
455
    """Encryption key series for data markets."""
456
    
457
    def __init__(self, key_id: bytes = None):
458
        """Initialize key series."""
459
    
460
    def generate_key(self, key_no: int) -> bytes:
461
        """Generate encryption key."""
462
```
463

464
## Usage Examples
465

466
### Basic Utilities
467

468
```python
469
from autobahn.util import generate_token, utcnow, encode_truncate
470

471
# Generate secure token
472
token = generate_token()
473
print(f"Token: {token}")
474

475
# Get current UTC time
476
now = utcnow()
477
print(f"Current time: {now}")
478

479
# Truncate text to byte limit
480
text = "This is a long text that needs truncation"
481
truncated = encode_truncate(text, 20)
482
print(f"Truncated: {truncated}")
483
```
484

485
### Stopwatch Usage
486

487
```python
488
from autobahn.util import Stopwatch
489
import time
490

491
# Measure operation time
492
stopwatch = Stopwatch()
493
stopwatch.start()
494

495
# Simulate work
496
time.sleep(1)
497

498
elapsed = stopwatch.stop()
499
print(f"Operation took {elapsed:.2f} seconds")
500
```
501

502
### UTF-8 Validation
503

504
```python
505
from autobahn.nvx import Utf8Validator
506

507
validator = Utf8Validator()
508

509
# Validate UTF-8 data
510
valid_data = "Hello, 世界!".encode('utf-8')
511
is_valid, end_pos = validator.validate(valid_data)
512
print(f"Valid UTF-8: {is_valid}, End position: {end_pos}")
513

514
# Validate invalid UTF-8
515
invalid_data = b'\xff\xfe'
516
is_valid, end_pos = validator.validate(invalid_data)
517
print(f"Valid UTF-8: {is_valid}, End position: {end_pos}")
518
```
519

520
### Error Handling
521

522
```python
523
from autobahn.wamp.exception import ApplicationError
524

525
def divide(a, b):
526
    if b == 0:
527
        raise ApplicationError(
528
            'com.math.divbyzero',
529
            ['Division by zero'],
530
            {'dividend': a, 'divisor': b}
531
        )
532
    return a / b
533

534
try:
535
    result = divide(10, 0)
536
except ApplicationError as e:
537
    print(f"Error: {e.error}")
538
    print(f"Args: {e.args}")
539
    print(f"Kwargs: {e.kwargs}")
540
```
541

542
### Observable Pattern
543

544
```python
545
from autobahn.util import ObservableMixin
546

547
class EventEmitter(ObservableMixin):
548
    def __init__(self):
549
        super().__init__()
550
    
551
    def do_something(self):
552
        # Fire event
553
        self.fire('something_happened', data='test')
554

555
# Usage
556
emitter = EventEmitter()
557

558
def on_something(data):
559
    print(f"Something happened with data: {data}")
560

561
emitter.on('something_happened', on_something)
562
emitter.do_something()
563
```
564

565
### ID Generation
566

567
```python
568
from autobahn.util import IdGenerator, id, rid, newid
569

570
# Global ID functions
571
print(f"Random ID: {id()}")
572
print(f"Request ID: {rid()}")
573
print(f"New ID: {newid()}")
574

575
# ID generator instance
576
generator = IdGenerator()
577
print(f"Generated ID: {generator.next()}")
578
```
579

580
### Text Highlighting
581

582
```python
583
from autobahn.util import hl, hltype, hlid, hlval
584

585
# Highlight text
586
print(hl("Important message", "red", bold=True))
587
print(hltype("String"))
588
print(hlid("session-123"))
589
print(hlval("42"))
590
```