Skip to content

Releases: SpaceShaman/socketapi

🌐 v0.2.0 – Configurable Cross-Host Broadcasting

18 Dec 09:41
@SpaceShaman SpaceShaman
v0.2.0
d35d040

Choose a tag to compare

View all tags
🌐 v0.2.0 – Configurable Cross-Host Broadcasting Latest
Latest

🚀 What’s New

This release introduces explicit, secure support for broadcasting from other machines, while keeping safe defaults.

✨ Configurable broadcast_allowed_hosts

The SocketAPI constructor now exposes a new parameter:

broadcast_allowed_hosts

By default, broadcasting endpoints still accept only localhost connections for security.
With v0.2.0 you can explicitly allow external machines to broadcast messages by whitelisting their IPs or hostnames.

app = SocketAPI(
    host="0.0.0.0",
    port=8000,
    broadcast_allowed_hosts=("127.0.0.1", "::1", "localhost", "192.168.1.50")
)

This makes cross-process and cross-machine broadcasting intentional, explicit, and secure.

📘 Improved Documentation

The Channels documentation now includes a dedicated section:

“Broadcasting from a Different Machine”, explaining:

  • default localhost-only behavior
  • how and when to enable external hosts
  • recommended security practices

This closes the loop between the security change introduced earlier and real-world deployment needs.

🎯 Why This Matters

SocketAPI can now be safely used with:

  • 🧵 Background workers on separate servers
  • 🔁 Existing infrastructure and legacy systems
  • 🔔 External services triggering real-time updates
  • 🏗️ Distributed architectures

All without sacrificing secure defaults.

📦 Version

  • v0.2.0

Upgrade:

pip install -U socketapi

🔗 Links

This release is backward-compatible and strictly opt-in for external broadcasting.

Full Changelog: v0.1.2...v0.2.0

Assets 2
Loading

🔐 v0.1.2 – Secure External Broadcasting

17 Dec 19:05
@SpaceShaman SpaceShaman
v0.1.2
4ad8007

Choose a tag to compare

View all tags
🔐 v0.1.2 – Secure External Broadcasting

🚀 What’s New

This release introduces an important security hardening related to broadcasting messages from outside the server process.

🛡️ Localhost-Only Broadcast Endpoint

Broadcasting to channels from other processes is now restricted to localhost only.

This means:

  • ✅ Internal/background processes on the same machine can still broadcast messages
  • ❌ External network access to the broadcast endpoint is blocked by default
  • 🔒 Prevents accidental or malicious access from outside the host

This change improves the default security posture of SocketAPI, especially for production deployments.

🔮 What’s Planned Next

In a future release, SocketAPI will allow:

  • 🌐 Custom external host configuration, explicitly defined by the user
  • 🧩 More flexible and intentional cross-process / cross-host broadcasting setups

Security-first defaults now, configurability later.

📦 Version

  • v0.1.2

Upgrade as usual:

pip install -U socketapi

🐙 Links

This release is fully backward-compatible for local and same-host usage.

Full Changelog: v0.1.1...v0.1.2

Loading

🎉 SocketAPI v0.1.1 - Initial Release

14 Dec 08:35
@SpaceShaman SpaceShaman
v0.1.1
78bad08

Choose a tag to compare

View all tags
🎉 SocketAPI v0.1.1 - Initial Release

🚀 Welcome to SocketAPI!

I am thrilled to announce the first official release of SocketAPI – a lightweight, modern Python framework for building real-time WebSocket APIs with ease! 🎊

SocketAPI combines the simplicity of FastAPI's declarative routing with the real-time power of WebSockets, using a single multiplexed connection for all communications.

✨ Key Features

🎯 Actions - Request-Response Pattern

Define WebSocket endpoints just like REST APIs! Actions provide a familiar request-response pattern for handling client requests.

@app.action("calculate")
async def calculate(a: int, b: int) -> int:
    return a + b

📡 Channels - Pub/Sub Pattern

Subscribe to real-time data streams with automatic broadcasting to all connected clients.

@app.channel("chat")
async def chat_channel(message: str):
    return {"message": message}

🔄 Single Multiplexed Connection

All communications happen through one WebSocket connection, multiplexed via the channel field – efficient and simple!

✅ Pydantic Integration

Automatic data validation and serialization powered by Pydantic v2. Type-safe by design!

class UserData(BaseModel):
    username: str
    email: str
    age: int

@app.action("create_user")
async def create_user(user: UserData) -> UserResponse:
    return UserResponse(id=1, username=user.username)

💉 Dependency Injection

FastAPI-style dependency injection for reusable logic like authentication, database connections, and more.

async def get_current_user(token: str) -> User:
    # Validate token
    return User(id=1, username="alice")

@app.action("get_profile")
async def get_profile(
    current_user: Annotated[User, Depends(get_current_user)]
):
    return current_user

📦 Router Support

Organize your application into logical modules and split code across multiple files.

router = Router()

@router.channel("notifications")
async def notifications(message: str):
    return {"message": message}

app.include_router(router)

🌐 Broadcasting from Anywhere

Call channel functions from outside the server context – perfect for background tasks, Celery jobs, webhooks, and external services!

# Works from anywhere - even different processes!
await chat_channel(message="Hello from external process!")

⚠️ Error Handling

Automatic error reporting with validation messages sent directly to clients.

🛠️ Built on Solid Foundations

  • Starlette for robust WebSocket handling
  • Pydantic v2 for data validation
  • ASGI-compatible - works with Uvicorn, Hypercorn, and more

📦 Installation

Install SocketAPI with pip:

pip install socketapi

Requirements:

  • Python 3.11 or higher
  • Starlette >= 0.50.0
  • Pydantic >= 2.12.5
  • httpx >= 0.28.1

🎓 Quick Start

Server Side

from socketapi import SocketAPI

app = SocketAPI()

@app.action("add_numbers")
async def add_numbers(a: int, b: int) -> int:
    return a + b

@app.channel("chat")
async def chat_channel(message: str = "Welcome"):
    return {"message": message}

@app.action("send_message")
async def send_message(message: str):
    await chat_channel(message=message)

Run with Uvicorn:

uvicorn main:app --reload

Client Side

Connect to ws://localhost:8000/ and exchange JSON messages:

Call an action:

{"type": "action", "channel": "add_numbers", "data": {"a": 5, "b": 3}}

Subscribe to a channel:

{"type": "subscribe", "channel": "chat"}

Broadcast to subscribers:

{"type": "action", "channel": "send_message", "data": {"message": "Hello!"}}

🎯 Perfect For

  • 💬 Chat applications - Real-time messaging with pub/sub
  • 📊 Live dashboards - Stream data updates to multiple clients
  • 🎮 Multiplayer games - Handle game state and player actions
  • 📈 Real-time analytics - Push live metrics and events
  • 🔔 Notification systems - Broadcast alerts to subscribed users
  • 🤖 IoT applications - Manage device communications
  • 📡 Live feeds - Social media updates, news streams, etc.

📚 Documentation

Full documentation is available at: spaceshaman.github.io/socketapi/

🧪 Testing

SocketAPI includes a built-in test client for easy testing:

from socketapi import SocketAPI
from socketapi.testclient import TestClient

app = SocketAPI()
client = TestClient(app)

@app.action("test_action")
async def test_action(value: int):
    return {"result": value * 2}

def test_my_action():
    with client.websocket_connect("/") as websocket:
        websocket.send_json({
            "type": "action",
            "channel": "test_action",
            "data": {"value": 5}
        })
        response = websocket.receive_json()
        assert response["data"]["result"] == 10

🏗️ Development Stack

🤝 Contributing

We welcome contributions! Whether it's:

  • 🐛 Bug reports
  • 💡 Feature requests
  • 📝 Documentation improvements
  • 🔧 Code contributions

Note: We maintain 100% test coverage to ensure reliability and safety.

📄 License

SocketAPI is licensed under the MIT License.
Copyright © 2025 SpaceShaman

🙏 Acknowledgments

Special thanks to:

🔗 Links

💬 Get in Touch

Have questions or want to share what you're building with SocketAPI?
I would love to hear from you!

📧 Email: [email protected]

Thank you for trying SocketAPI! 🎉

Built with ❤️ by SpaceShaman

⭐ Star us on GitHub if you find SocketAPI useful!

Loading