Python SDK Python Repository

The Gluesync Python SDK provides a comprehensive framework for building integrations, modules, and extensions that communicate with the Core Hub using Python.

Open Source This project is Open Source

Overview

The Python SDK is a fully-featured implementation of the Core Hub handshake protocol, offering seamless integration with Gluesync’s real-time data synchronization platform. Designed with Pythonic interfaces, the SDK enables developers to quickly build and deploy custom solutions that leverage Gluesync’s infrastructure.

Installation

pip install git+https://gitlab.com/molo17-public/gluesync/gluesync-python-corehub-handshake-sdk.git

Key Features

  • Core Hub Handshake

    • Secure WebSocket connections (WS/WSS)

    • Automated authentication flow

    • Protocol version negotiation

    • Connection management

  • Authentication

    • License management and validation

    • JWT token handling

    • Secure credential handling

    • Session management

  • Connection Management

    • Keep-alive mechanism (ping/pong)

    • UDP autodiscovery of CoreHub

    • Automatic reconnection handling

    • Cross-platform compatibility

  • Security

    • SSL/TLS support with JKS certificates

    • Secure token management

    • Verified connections

  • (Coming soon) Event Handling

    • Real-time event subscription

    • Event stream processing

    • Custom event handlers

    • Event filtering and routing

  • (Coming soon) Data Processing

    • JSON serialization/deserialization

    • Schema validation

    • Transformation utilities

    • Error handling middleware

Basic Usage

import asyncio
from gluesync_sdk import GluesyncClient

async def main():
    # Initialize the client with CoreHub address and license file path
    # For fixed address:
    client = GluesyncClient(
        host="localhost",
        port=1717,
        license_file_path="/path/to/gs-license.dat",
        module_tag="my-module",
        use_ssl=True,  # Enable SSL/TLS
        verify_ssl=False  # Disable SSL certificate verification
    )

    # Or use UDP autodiscovery (set host to None)
    # client = GluesyncClient(
    #    host=None,  # Will use UDP autodiscovery to find CoreHub
    #    port=1717,
    #    license_file_path="/path/to/gs-license.dat",
    #    module_tag="my-module",
    #    use_ssl=True,  # Enable SSL/TLS
    #    verify_ssl=False  # Disable SSL certificate verification
    # )

    # Connect to CoreHub
    await client.connect()

    # The JWT token for API requests is available after connection
    jwt_token = client.token
    print(f"Connected with token: {jwt_token}")

    # Do your work here

    # Disconnect when done
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

Advanced Features

Using UDP Autodiscovery

import asyncio
from gluesync_sdk import GluesyncClient

async def main():
    # Initialize the client without specifying a host to use autodiscovery
    client = GluesyncClient(
        # host parameter is omitted to enable autodiscovery
        license_file_path="/path/to/gs-license.dat",
        module_tag="my-module"
    )

    # Connect will automatically discover the CoreHub on the network
    await client.connect()

    # Do your work here

    # Disconnect when done
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

You can also use the environment variable CORE_HUB_ADDRESS to bypass autodiscovery:

import os

# Set this to bypass autodiscovery
os.environ["CORE_HUB_ADDRESS"] = "192.168.1.100"

Using SSL/TLS with JKS Certificates

import asyncio
from gluesync_sdk import GluesyncClient

async def main():
    client = GluesyncClient(
        host="corehub.example.com",
        port=1717,
        license_file_path="/path/to/gs-license.dat",
        module_tag="my-module",
        ssl=True,
        keystore_path="/path/to/Gluesync.com.jks",
        keystore_password="your-password"
    )

    await client.connect()
    # ...

if __name__ == "__main__":
    asyncio.run(main())

Event Handling

import asyncio
from gluesync_sdk import GluesyncClient

async def on_connected(token):
    print(f"Connected! Received token: {token}")

async def on_disconnected(reason):
    print(f"Disconnected: {reason}")

async def on_error(error):
    print(f"Error: {error}")

async def main():
    client = GluesyncClient(
        host="localhost",
        port=1717,
        license_file_path="/path/to/gs-license.dat",
        module_tag="my-module"
    )

    # Set up event handlers
    client.on_connected = on_connected
    client.on_disconnected = on_disconnected
    client.on_error = on_error

    await client.connect()

    # Keep the connection alive for some time
    await asyncio.sleep(3600)  # 1 hour

    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

Connection Resilience

Implement an automatic reconnection strategy for your application:

import asyncio
from gluesync_sdk import GluesyncClient

# Reconnection settings
MAX_RECONNECT_ATTEMPTS = 5
RECONNECT_DELAY = 2.0  # Base delay in seconds
reconnecting = False

async def on_disconnected(reason):
    """Handle disconnection and trigger reconnection"""
    global reconnecting
    print(f"Disconnected: {reason}")

    if not reconnecting:
        reconnecting = True
        asyncio.create_task(attempt_reconnect())

async def attempt_reconnect():
    """Attempt to reconnect with exponential backoff"""
    global client, reconnecting
    attempt = 0

    while reconnecting and (attempt < MAX_RECONNECT_ATTEMPTS):
        attempt += 1
        delay = min(RECONNECT_DELAY * (2 ** (attempt - 1)), 30)  # Exponential backoff

        print(f"Reconnecting in {delay:.1f} seconds (attempt {attempt}/{MAX_RECONNECT_ATTEMPTS})")
        await asyncio.sleep(delay)

        try:
            await client.connect()
            print("Reconnected successfully!")
            reconnecting = False
            break
        except Exception as e:
            print(f"Reconnection failed: {e}")

    if reconnecting:
        print(f"Failed to reconnect after {MAX_RECONNECT_ATTEMPTS} attempts")
        reconnecting = False

async def main():
    global client

    client = GluesyncClient(
        host=None,  # Use autodiscovery
        license_file_path="/path/to/gs-license.dat",
        module_tag="resilient-module"
    )

    # Register the disconnection handler
    client.on_disconnected = on_disconnected

    try:
        await client.connect()
        print(f"Connected with token: {client.token[:10]}...")

        # Keep the application running
        while True:
            await asyncio.sleep(1)

    except KeyboardInterrupt:
        await client.disconnect()
        print("Disconnected")

Error Handling

The SDK defines several exception types to handle different error scenarios:

import asyncio
from gluesync_sdk import GluesyncClient
from gluesync_sdk.exceptions import GluesyncAuthenticationError, GluesyncLicenseError

async def main():
    try:
        client = GluesyncClient(
            host="localhost",
            port=1717,
            license_file_path="/path/to/gs-license.dat",
            module_tag="my-module"
        )

        await client.connect()
        # ...

    except GluesyncAuthenticationError as e:
        print(f"Authentication failed: {e}")
    except GluesyncLicenseError as e:
        print(f"License error: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Exception types include:

  • GluesyncConnectionError: Base exception for connection issues

  • GluesyncAuthenticationError: Authentication failed

  • GluesyncLicenseError: License is invalid or expired

  • GluesyncTimeoutError: Connection or operation timed out

API Reference

For complete API documentation, please visit the GitLab repository: Python SDK on GitLab.

Source Code & Contributing

The Python SDK is open source and available on GitLab:

  • Repository: Python SDK on GitLab

  • Issues: Please report bugs and feature requests through the GitLab issue tracker

  • Contributing: See the CONTRIBUTING section in the repository for guidelines

License

The Gluesync Python SDK is dual-licensed under the following licenses:

  1. GNU General Public License (GPL) Version 3 You may use, modify, and distribute this software under the terms of the GPL v3. See the LICENSE-GPL file or GPL v3 for details. This option is available at no cost, but any derivative works must also be licensed under GPL v3.

  2. MOLO17 Commercial License Alternatively, you may use this software under the MOLO17 Commercial License, which includes a warranty and permits proprietary use. Contact MOLO17 at info@molo17.com for licensing terms and conditions.

You must choose one of these licenses to use this software. Using this software implies acceptance of one of these licenses.

Copyright © 2025 MOLO17. All rights reserved.