From cf6685b34b643e45a5f5599850c6b1fc9438387b Mon Sep 17 00:00:00 2001
From: CJ van den Berg <cj@vdbonline.com>
Date: Wed, 4 Mar 2026 20:19:59 +0100
Subject: [PATCH] refactor: add some misuse checks to the C API

---
 src/c/socket.cpp | 11 +++++++++++
 src/c/tcp.cpp    | 11 +++++++++++
 src/c/unx.cpp    | 12 ++++++++++++
 3 files changed, 34 insertions(+)

diff --git a/src/c/socket.cpp b/src/c/socket.cpp
index 57b3517..1d51b69 100644
--- a/src/c/socket.cpp
+++ b/src/c/socket.cpp
@@ -2,6 +2,12 @@
 #include <thespian/c/socket.h>
 #include <thespian/socket.hpp>
 
+#include <cassert>
+
+#define ASSERT_HANDLE(h, fn) \
+    assert((h) != nullptr && "null handle passed to " fn ": was it created outside an actor?")
+
+
 using socket_impl = thespian::socket_impl;
 
 extern "C" {
@@ -22,6 +28,7 @@ auto thespian_socket_create(const char *tag, int fd)
 
 auto thespian_socket_write(struct thespian_socket_handle *handle,
                            const char *data, size_t len) -> int {
+  ASSERT_HANDLE(handle, "thespian_socket_write");
   try {
     thespian::socket_write(reinterpret_cast<socket_impl *>(handle), // NOLINT
                            std::string_view(data, len));
@@ -37,6 +44,7 @@ auto thespian_socket_write(struct thespian_socket_handle *handle,
 
 auto thespian_socket_write_binary(struct thespian_socket_handle *handle,
                                   const uint8_t *data, size_t len) -> int {
+  ASSERT_HANDLE(handle, "thespian_socket_write_binary");
   try {
     std::vector<uint8_t> buf(data, data + len); // NOLINT
     thespian::socket_write_binary(
@@ -53,6 +61,7 @@ auto thespian_socket_write_binary(struct thespian_socket_handle *handle,
 }
 
 auto thespian_socket_read(struct thespian_socket_handle *handle) -> int {
+  ASSERT_HANDLE(handle, "thespian_socket_read");
   try {
     thespian::socket_read(reinterpret_cast<socket_impl *>(handle)); // NOLINT
     return 0;
@@ -66,6 +75,7 @@ auto thespian_socket_read(struct thespian_socket_handle *handle) -> int {
 }
 
 auto thespian_socket_close(struct thespian_socket_handle *handle) -> int {
+  ASSERT_HANDLE(handle, "thespian_socket_close");
   try {
     thespian::socket_close(reinterpret_cast<socket_impl *>(handle)); // NOLINT
     return 0;
@@ -79,6 +89,7 @@ auto thespian_socket_close(struct thespian_socket_handle *handle) -> int {
 }
 
 void thespian_socket_destroy(struct thespian_socket_handle *handle) {
+  ASSERT_HANDLE(handle, "thespian_socket_destroy");
   try {
     thespian::destroy_socket(reinterpret_cast<socket_impl *>(handle)); // NOLINT
   } catch (const std::exception &e) {
diff --git a/src/c/tcp.cpp b/src/c/tcp.cpp
index befc834..0080cd1 100644
--- a/src/c/tcp.cpp
+++ b/src/c/tcp.cpp
@@ -2,6 +2,11 @@
 #include <thespian/c/tcp.h>
 #include <thespian/tcp.hpp>
 
+#include <cassert>
+
+#define ASSERT_HANDLE(h, fn) \
+    assert((h) != nullptr && "null handle passed to " fn ": was it created outside an actor?")
+
 using ::port_t;
 using thespian::tcp::acceptor_impl;
 using thespian::tcp::connector_impl;
@@ -24,6 +29,7 @@ auto thespian_tcp_acceptor_create(const char *tag)
 
 auto thespian_tcp_acceptor_listen(struct thespian_tcp_acceptor_handle *handle,
                                   in6_addr ip, uint16_t port) -> uint16_t {
+  ASSERT_HANDLE(handle, "thespian_tcp_acceptor_listen");
   try {
     port_t p = thespian::tcp::acceptor_listen(
         reinterpret_cast<acceptor_impl *>(handle), ip, port); // NOLINT
@@ -39,6 +45,7 @@ auto thespian_tcp_acceptor_listen(struct thespian_tcp_acceptor_handle *handle,
 
 auto thespian_tcp_acceptor_close(struct thespian_tcp_acceptor_handle *handle)
     -> int {
+  ASSERT_HANDLE(handle, "thespian_tcp_acceptor_close");
   try {
     thespian::tcp::acceptor_close(
         reinterpret_cast<acceptor_impl *>(handle)); // NOLINT
@@ -54,6 +61,7 @@ auto thespian_tcp_acceptor_close(struct thespian_tcp_acceptor_handle *handle)
 
 void thespian_tcp_acceptor_destroy(
     struct thespian_tcp_acceptor_handle *handle) {
+  ASSERT_HANDLE(handle, "thespian_tcp_acceptor_destroy");
   try {
     thespian::tcp::destroy_acceptor(
         reinterpret_cast<acceptor_impl *>(handle)); // NOLINT
@@ -82,6 +90,7 @@ auto thespian_tcp_connector_create(const char *tag)
 auto thespian_tcp_connector_connect(
     struct thespian_tcp_connector_handle *handle, in6_addr ip, uint16_t port)
     -> int {
+  ASSERT_HANDLE(handle, "thespian_tcp_connector_connect");
   try {
     thespian::tcp::connector_connect(
         reinterpret_cast<connector_impl *>(handle), // NOLINT
@@ -98,6 +107,7 @@ auto thespian_tcp_connector_connect(
 
 auto thespian_tcp_connector_cancel(struct thespian_tcp_connector_handle *handle)
     -> int {
+  ASSERT_HANDLE(handle, "thespian_tcp_connector_cancel");
   try {
     thespian::tcp::connector_cancel(
         reinterpret_cast<connector_impl *>(handle)); // NOLINT
@@ -113,6 +123,7 @@ auto thespian_tcp_connector_cancel(struct thespian_tcp_connector_handle *handle)
 
 void thespian_tcp_connector_destroy(
     struct thespian_tcp_connector_handle *handle) {
+  ASSERT_HANDLE(handle, "thespian_tcp_connector_destroy");
   try {
     thespian::tcp::destroy_connector(
         reinterpret_cast<connector_impl *>(handle)); // NOLINT
diff --git a/src/c/unx.cpp b/src/c/unx.cpp
index e4ae3b1..9c3475c 100644
--- a/src/c/unx.cpp
+++ b/src/c/unx.cpp
@@ -2,6 +2,12 @@
 #include <thespian/c/unx.h>
 #include <thespian/unx.hpp>
 
+#include <cassert>
+
+#define ASSERT_HANDLE(h, fn) \
+    assert((h) != nullptr && "null handle passed to " fn ": was it created outside an actor?")
+
+
 using thespian::unx::acceptor_impl;
 using thespian::unx::connector_impl;
 using thespian::unx::mode;
@@ -31,6 +37,7 @@ auto thespian_unx_acceptor_create(const char *tag)
 auto thespian_unx_acceptor_listen(struct thespian_unx_acceptor_handle *handle,
                                   const char *path, thespian_unx_mode m)
     -> int {
+  ASSERT_HANDLE(handle, "thespian_unx_acceptor_listen");
   try {
     thespian::unx::acceptor_listen(
         reinterpret_cast<acceptor_impl *>(handle), // NOLINT
@@ -47,6 +54,7 @@ auto thespian_unx_acceptor_listen(struct thespian_unx_acceptor_handle *handle,
 
 auto thespian_unx_acceptor_close(struct thespian_unx_acceptor_handle *handle)
     -> int {
+  ASSERT_HANDLE(handle, "thespian_unx_acceptor_close");
   try {
     thespian::unx::acceptor_close(
         reinterpret_cast<acceptor_impl *>(handle)); // NOLINT
@@ -62,6 +70,7 @@ auto thespian_unx_acceptor_close(struct thespian_unx_acceptor_handle *handle)
 
 void thespian_unx_acceptor_destroy(
     struct thespian_unx_acceptor_handle *handle) {
+  ASSERT_HANDLE(handle, "thespian_unx_acceptor_destroy");
   try {
     thespian::unx::destroy_acceptor(
         reinterpret_cast<acceptor_impl *>(handle)); // NOLINT
@@ -90,6 +99,7 @@ auto thespian_unx_connector_create(const char *tag)
 auto thespian_unx_connector_connect(
     struct thespian_unx_connector_handle *handle, const char *path,
     thespian_unx_mode m) -> int {
+  ASSERT_HANDLE(handle, "thespian_unx_connector_connect");
   try {
     thespian::unx::connector_connect(
         reinterpret_cast<connector_impl *>(handle), // NOLINT
@@ -106,6 +116,7 @@ auto thespian_unx_connector_connect(
 
 auto thespian_unx_connector_cancel(struct thespian_unx_connector_handle *handle)
     -> int {
+  ASSERT_HANDLE(handle, "thespian_unx_connector_cancel");
   try {
     thespian::unx::connector_cancel(
         reinterpret_cast<connector_impl *>(handle)); // NOLINT
@@ -121,6 +132,7 @@ auto thespian_unx_connector_cancel(struct thespian_unx_connector_handle *handle)
 
 void thespian_unx_connector_destroy(
     struct thespian_unx_connector_handle *handle) {
+  ASSERT_HANDLE(handle, "thespian_unx_connector_destroy");
   try {
     thespian::unx::destroy_connector(
         reinterpret_cast<connector_impl *>(handle)); // NOLINT