fuse-transport 0.1.0__tar.gz

fuse_transport-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+build/
+build-*/
+out/
+cmake-build-*/
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+CTestTestfile.cmake
+Testing/
+compile_commands.json
+_deps/
+*.o
+*.obj
+*.so
+*.so.*
+*.dylib
+*.a
+*.dll
+*.exe
+.cache/
+.vscode/
+.idea/
+
+# Rust benchmark baseline build artifacts
+bench/quic/target/
+dist/
+dist-py/
+__pycache__/
+*.pyc

fuse_transport-0.1.0/CMakeLists.txt

@@ -0,0 +1,332 @@
+cmake_minimum_required(VERSION 3.16)
+
+project(fuse
+    VERSION 0.1.0
+    DESCRIPTION "Fuse: an experimental low-latency transport protocol"
+    HOMEPAGE_URL "https://github.com/kamalkoushikd/fuse-nw"
+    LANGUAGES C CXX
+)
+
+if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+    set(FUSE_IS_TOP_LEVEL ON)
+else()
+    set(FUSE_IS_TOP_LEVEL OFF)
+endif()
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+include(GenerateExportHeader)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+    set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "Build type" FORCE)
+    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS Debug Release RelWithDebInfo MinSizeRel)
+endif()
+
+option(BUILD_SHARED_LIBS "Build fuse as a shared library" ON)
+option(FUSE_BUILD_TESTS "Build the fuse test suite" ${FUSE_IS_TOP_LEVEL})
+option(FUSE_BUILD_EXAMPLES "Build the fuse example programs" ${FUSE_IS_TOP_LEVEL})
+option(FUSE_BUILD_BENCH "Build the fuse benchmark harness" ${FUSE_IS_TOP_LEVEL})
+option(FUSE_WITH_CRYPTO "Enable the wolfSSL-backed handshake/crypto module" ON)
+option(FUSE_FETCH_WOLFSSL "Fetch and build wolfSSL from source if it isn't found on the system" ON)
+option(FUSE_WARNINGS_AS_ERRORS "Treat compiler warnings as errors" OFF)
+
+if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    message(WARNING "fuse targets Linux; other platforms are untested")
+endif()
+
+if(FUSE_WITH_CRYPTO)
+    include(FuseWolfSSL)
+endif()
+
+configure_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/fuse/version.h.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/include/fuse/version.h"
+    @ONLY
+)
+
+add_library(fuse
+    src/varint.c
+    src/packet.c
+    src/socket.c
+    src/connection.c
+    src/crypto.c
+)
+add_library(fuse::fuse ALIAS fuse)
+
+generate_export_header(fuse
+    BASE_NAME fuse
+    EXPORT_FILE_NAME "${CMAKE_CURRENT_BINARY_DIR}/include/fuse/export.h"
+)
+
+target_include_directories(fuse
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+
+set_target_properties(fuse PROPERTIES
+    VERSION ${PROJECT_VERSION}
+    SOVERSION ${PROJECT_VERSION_MAJOR}
+    C_VISIBILITY_PRESET hidden
+    CXX_VISIBILITY_PRESET hidden
+    VISIBILITY_INLINES_HIDDEN ON
+)
+
+if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+    target_compile_options(fuse PRIVATE -Wall -Wextra)
+    if(FUSE_WARNINGS_AS_ERRORS)
+        target_compile_options(fuse PRIVATE -Werror)
+    endif()
+endif()
+
+if(FUSE_WITH_CRYPTO)
+    target_compile_definitions(fuse PUBLIC FUSE_WITH_CRYPTO=1)
+    target_link_libraries(fuse PRIVATE wolfssl::wolfssl)
+else()
+    target_compile_definitions(fuse PUBLIC FUSE_WITH_CRYPTO=0)
+endif()
+
+# --- fuse_proto: the staged datagram transport (Fuse work plan) ------------
+#
+# This is the protocol described in the staged build plan: a custom
+# datagram block layer with per-stream registries, bitmask loss tracking,
+# and (in later stages) worker threads and per-stream congestion control.
+# It is intentionally a separate target from the `fuse` C library above and
+# does NOT link wolfSSL — encryption is an opt-in later stage (DTLS/PSK),
+# not a dependency of the core data plane.
+
+add_library(fuse_proto
+    src/proto/block.cpp
+    src/proto/aux.cpp
+    src/proto/registry.cpp
+    src/proto/receiver.cpp
+    src/proto/udp.cpp
+    src/proto/setup.cpp
+    src/proto/worker.cpp
+    src/proto/reassembly.cpp
+    src/proto/topology.cpp
+    src/proto/dtls.cpp
+    src/proto/orchestrator.cpp
+    src/proto/session_crypto.cpp
+    src/proto/transfer.cpp
+    src/proto/sdk.cpp
+)
+add_library(fuse::proto ALIAS fuse_proto)
+
+# Stage 7: optional DTLS/PSK encryption. Compiled in when the wolfSSL crypto
+# backend is enabled; encryption still defaults to OFF at runtime
+# (encryption_required=false). Without it, requiring encryption fails closed
+# rather than silently running in plaintext.
+if(FUSE_WITH_CRYPTO)
+    target_compile_definitions(fuse_proto PUBLIC FUSE_PROTO_WITH_DTLS=1)
+    target_link_libraries(fuse_proto PRIVATE wolfssl::wolfssl)
+else()
+    target_compile_definitions(fuse_proto PUBLIC FUSE_PROTO_WITH_DTLS=0)
+endif()
+
+find_package(Threads REQUIRED)
+
+# Optional NUMA binding for topology-aware placement (Stage 6). Compiled in
+# only when libnuma's development headers are present; otherwise the NUMA
+# hook degrades to a documented no-op and CPU pinning still works.
+find_path(FUSE_NUMA_INCLUDE_DIR numa.h)
+find_library(FUSE_NUMA_LIBRARY numa)
+if(FUSE_NUMA_INCLUDE_DIR AND FUSE_NUMA_LIBRARY)
+    message(STATUS "fuse: libnuma found, enabling NUMA-aware placement")
+    target_compile_definitions(fuse_proto PRIVATE FUSE_HAVE_NUMA=1)
+    target_include_directories(fuse_proto PRIVATE ${FUSE_NUMA_INCLUDE_DIR})
+    target_link_libraries(fuse_proto PRIVATE ${FUSE_NUMA_LIBRARY})
+else()
+    message(STATUS "fuse: libnuma not found, NUMA hook will be a no-op (CPU pinning still active)")
+    target_compile_definitions(fuse_proto PRIVATE FUSE_HAVE_NUMA=0)
+endif()
+
+target_include_directories(fuse_proto
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        # version.h is generated, so the build tree needs the binary dir too.
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)
+
+# Worker threads (Stage 3) use std::thread; Threads is part of the public
+# link interface so downstream consumers of fuse::proto link pthread too.
+target_link_libraries(fuse_proto PUBLIC Threads::Threads)
+
+# NOTE: unlike the C `fuse` library, fuse_proto does not yet use an export
+# header, so its public symbols must stay visible (default visibility) for
+# the shared library to export them. Revisit with generate_export_header
+# once the Stage 1+ API surface settles.
+set_target_properties(fuse_proto PROPERTIES
+    VERSION ${PROJECT_VERSION}
+    SOVERSION ${PROJECT_VERSION_MAJOR}
+    # Without this the target exports as `fuse::fuse_proto`, since the
+    # `fuse::proto` ALIAS above exists only in the build tree. Downstream
+    # users would then have to link a different name than the one used
+    # in-tree and in the docs.
+    EXPORT_NAME proto
+)
+
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    target_compile_options(fuse_proto PRIVATE -Wall -Wextra)
+    if(FUSE_WARNINGS_AS_ERRORS)
+        target_compile_options(fuse_proto PRIVATE -Werror)
+    endif()
+endif()
+
+# --- Installation ---------------------------------------------------------
+
+# Let the installed libraries find their siblings (notably libwolfssl, which
+# is installed alongside them) from wherever the package ends up.
+#
+# This matters more than it looks: modern linkers emit RUNPATH rather than
+# RPATH, and the loader consults RUNPATH only for an object's *direct*
+# dependencies. So an executable's rpath does NOT help libfuse_proto.so find
+# libwolfssl.so — without $ORIGIN here, anything installed outside the system
+# library path fails at run time with a missing-library error, even though it
+# linked cleanly.
+set_target_properties(fuse fuse_proto PROPERTIES
+    INSTALL_RPATH "$ORIGIN"
+)
+
+install(TARGETS fuse fuse_proto
+    EXPORT fuse-targets
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+)
+
+install(DIRECTORY include/fuse
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    FILES_MATCHING PATTERN "*.h" PATTERN "*.hpp"
+)
+install(FILES
+    "${CMAKE_CURRENT_BINARY_DIR}/include/fuse/version.h"
+    "${CMAKE_CURRENT_BINARY_DIR}/include/fuse/export.h"
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/fuse
+)
+
+install(EXPORT fuse-targets
+    FILE fuse-targets.cmake
+    NAMESPACE fuse::
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fuse
+)
+
+configure_package_config_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/fuseConfig.cmake.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/fuseConfig.cmake"
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fuse
+)
+write_basic_package_version_file(
+    "${CMAKE_CURRENT_BINARY_DIR}/fuseConfigVersion.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+)
+install(FILES
+    "${CMAKE_CURRENT_BINARY_DIR}/fuseConfig.cmake"
+    "${CMAKE_CURRENT_BINARY_DIR}/fuseConfigVersion.cmake"
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fuse
+)
+
+# fuse.pc's `prefix=` line must reflect the prefix actually in effect
+# at install time (which `cmake --install --prefix` and CPack's
+# packaging-time re-rooting both override), not the prefix seen at
+# configure time. configure_file() alone would bake in the latter, so
+# the substitution is deferred into an install(CODE) script, where
+# CMAKE_INSTALL_PREFIX is re-evaluated as the real target of this
+# particular install.
+if(FUSE_WITH_CRYPTO)
+    set(FUSE_PC_REQUIRES_PRIVATE "wolfssl")
+else()
+    set(FUSE_PC_REQUIRES_PRIVATE "")
+endif()
+
+install(CODE "
+    file(READ \"${CMAKE_CURRENT_SOURCE_DIR}/cmake/fuse.pc.in\" _fuse_pc_content)
+    string(REPLACE \"@CMAKE_INSTALL_PREFIX@\" \"\${CMAKE_INSTALL_PREFIX}\" _fuse_pc_content \"\${_fuse_pc_content}\")
+    string(REPLACE \"@CMAKE_INSTALL_LIBDIR@\" \"${CMAKE_INSTALL_LIBDIR}\" _fuse_pc_content \"\${_fuse_pc_content}\")
+    string(REPLACE \"@CMAKE_INSTALL_INCLUDEDIR@\" \"${CMAKE_INSTALL_INCLUDEDIR}\" _fuse_pc_content \"\${_fuse_pc_content}\")
+    string(REPLACE \"@PROJECT_DESCRIPTION@\" \"${PROJECT_DESCRIPTION}\" _fuse_pc_content \"\${_fuse_pc_content}\")
+    string(REPLACE \"@PROJECT_VERSION@\" \"${PROJECT_VERSION}\" _fuse_pc_content \"\${_fuse_pc_content}\")
+    string(REPLACE \"@PROJECT_HOMEPAGE_URL@\" \"${PROJECT_HOMEPAGE_URL}\" _fuse_pc_content \"\${_fuse_pc_content}\")
+    string(REPLACE \"@FUSE_PC_REQUIRES_PRIVATE@\" \"${FUSE_PC_REQUIRES_PRIVATE}\" _fuse_pc_content \"\${_fuse_pc_content}\")
+    file(WRITE \"${CMAKE_CURRENT_BINARY_DIR}/fuse.pc\" \"\${_fuse_pc_content}\")
+")
+install(FILES "${CMAKE_CURRENT_BINARY_DIR}/fuse.pc"
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig
+)
+
+# --- Subprojects -----------------------------------------------------------
+
+if(FUSE_BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+endif()
+
+if(FUSE_BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+
+if(FUSE_BUILD_BENCH)
+    add_subdirectory(bench)
+endif()
+
+# --- Packaging (CPack) ------------------------------------------------------
+#
+# Produces a single combined package per generator (library, headers,
+# CMake/pkg-config files, and - since FUSE_FETCH_WOLFSSL builds and
+# installs its own wolfSSL alongside fuse - that too). This is
+# deliberately not split into separate runtime/-dev packages yet: doing
+# that properly would require retrofitting COMPONENT tags onto
+# wolfSSL's own install() rules, which fuse doesn't control. A single
+# "install everything needed to build against and run fuse" package is
+# the standard approach for a pre-1.0 library distributed outside of a
+# distro's own repositories.
+
+if(FUSE_IS_TOP_LEVEL)
+    set(CPACK_PACKAGE_NAME "fuse")
+    set(CPACK_PACKAGE_VENDOR "The Fuse Project")
+    set(CPACK_PACKAGE_VERSION_MAJOR ${PROJECT_VERSION_MAJOR})
+    set(CPACK_PACKAGE_VERSION_MINOR ${PROJECT_VERSION_MINOR})
+    set(CPACK_PACKAGE_VERSION_PATCH ${PROJECT_VERSION_PATCH})
+    set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "${PROJECT_DESCRIPTION}")
+    set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
+    set(CPACK_PACKAGE_CONTACT "The Fuse Project <kamalkoushik24@gmail.com>")
+    set(CPACK_PACKAGING_INSTALL_PREFIX "/usr")
+    set(CPACK_STRIP_FILES ON)
+
+    set(CPACK_DEBIAN_PACKAGE_MAINTAINER "${CPACK_PACKAGE_CONTACT}")
+    set(CPACK_DEBIAN_PACKAGE_SECTION "libdevel")
+    set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
+    set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
+
+    set(CPACK_RPM_PACKAGE_LICENSE "MIT")
+    set(CPACK_RPM_PACKAGE_GROUP "Development/Libraries")
+    set(CPACK_RPM_PACKAGE_AUTOREQPROV ON)
+    set(CPACK_RPM_FILE_NAME RPM-DEFAULT)
+
+    set(CPACK_GENERATOR "TGZ")
+    find_program(FUSE_DPKG_DEB_EXECUTABLE dpkg-deb)
+    find_program(FUSE_RPMBUILD_EXECUTABLE rpmbuild)
+    if(FUSE_DPKG_DEB_EXECUTABLE)
+        list(APPEND CPACK_GENERATOR "DEB")
+    endif()
+    if(FUSE_RPMBUILD_EXECUTABLE)
+        list(APPEND CPACK_GENERATOR "RPM")
+    endif()
+
+    include(CPack)
+endif()

fuse_transport-0.1.0/CMakePresets.json

@@ -0,0 +1,40 @@
+{
+  "version": 6,
+  "cmakeMinimumRequired": { "major": 3, "minor": 21, "patch": 0 },
+  "configurePresets": [
+    {
+      "name": "default",
+      "displayName": "Default (Release)",
+      "binaryDir": "${sourceDir}/build/${presetName}",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo"
+      }
+    },
+    {
+      "name": "debug",
+      "displayName": "Debug",
+      "inherits": "default",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug"
+      }
+    },
+    {
+      "name": "no-crypto",
+      "displayName": "No crypto (fast core-only build, no wolfSSL fetch)",
+      "inherits": "default",
+      "cacheVariables": {
+        "FUSE_WITH_CRYPTO": "OFF"
+      }
+    }
+  ],
+  "buildPresets": [
+    { "name": "default", "configurePreset": "default" },
+    { "name": "debug", "configurePreset": "debug" },
+    { "name": "no-crypto", "configurePreset": "no-crypto" }
+  ],
+  "testPresets": [
+    { "name": "default", "configurePreset": "default", "output": { "outputOnFailure": true } },
+    { "name": "debug", "configurePreset": "debug", "output": { "outputOnFailure": true } },
+    { "name": "no-crypto", "configurePreset": "no-crypto", "output": { "outputOnFailure": true } }
+  ]
+}

fuse_transport-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Fuse Project Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fuse_transport-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: fuse-transport
+Version: 0.1.0
+Summary: Socket-style Python bindings for the Fuse UDP transport protocol
+Keywords: networking,transport,udp,protocol,sockets,quic
+Author: Kamal Koushik D
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/kamalkoushikd/fuse-nw
+Project-URL: Documentation, https://github.com/kamalkoushikd/fuse-nw/blob/main/docs/SDK.md
+Project-URL: Source, https://github.com/kamalkoushikd/fuse-nw
+Project-URL: Issues, https://github.com/kamalkoushikd/fuse-nw/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# fuse-transport
+
+Socket-style Python bindings for [Fuse](https://github.com/kamalkoushikd/fuse-nw),
+an experimental UDP transport with **per-stream congestion control** — so a
+stalled bulk transfer cannot throttle unrelated latency-sensitive traffic on
+the same session, which is the thing QUIC's connection-wide controller cannot
+do.
+
+```sh
+pip install fuse-transport
+# or
+uv add fuse-transport
+```
+
+Linux only. Wheels bundle the compiled transport and its wolfSSL, so there is
+no compiler, no CMake, and no system library to install.
+
+```python
+import fuse
+```
+
+## Server
+
+```python
+import threading
+import fuse
+
+def handle(conn):
+    with conn:
+        for message in conn:        # iterates until the peer closes
+            conn.send(b"ECHO:" + message)
+
+with fuse.listen(port=4433) as server:
+    for conn in server:             # iterates incoming connections
+        threading.Thread(target=handle, args=(conn,), daemon=True).start()
+```
+
+## Client
+
+```python
+import fuse
+
+with fuse.connect("192.0.2.10", 4433, timeout=5) as conn:
+    conn.send(b"hello")             # str is UTF-8 encoded for you
+    print(conn.recv(timeout=5).decode())
+```
+
+## Two ways this differs from a TCP socket
+
+**Messages, not a byte stream.** One `send` becomes exactly one `recv`.
+Boundaries are preserved (like `SOCK_SEQPACKET`), so you never length-prefix,
+never scan for delimiters, and a partial read cannot happen.
+
+**`send` means delivered.** It returns once the peer has acknowledged the
+message, not when it was queued locally. A successful send is proof of arrival.
+
+Retransmission, ordering, congestion control and adaptive block sizing are
+handled underneath.
+
+## Encryption
+
+Set the same key on both ends for AES-256-GCM:
+
+```python
+fuse.listen(port=4433, key="shared-secret")
+fuse.connect("192.0.2.10", 4433, key="shared-secret")
+```
+
+A client presenting the wrong key is rejected during the handshake and never
+exchanges data. Note this is a **pre-shared key, so there is no forward
+secrecy**: someone who records traffic and later obtains the key can decrypt
+it. If that matters, run Fuse inside a tunnel that provides it.
+
+## API
+
+| call | notes |
+|---|---|
+| `fuse.listen(port, bind="0.0.0.0", key=None, timeout=None)` | → `Listener` |
+| `fuse.connect(host, port, key=None, timeout=None)` | → `Connection` |
+| `Listener.accept(timeout=None)` | → `Connection`; iterate the listener for a loop |
+| `Listener.port` | actual port (pass `port=0` to let the OS pick) |
+| `Connection.send(data)` | `bytes` / `bytearray` / `memoryview` / `str` |
+| `Connection.recv(timeout=None)` | → `bytes`; iterate for a message loop |
+| `Connection.peer` | `(address, port)` |
+| `Connection.stats` | counters, including `rtt_us` |
+| `Connection.closed` | `bool` |
+| `.close()` | also via `with` blocks; idempotent |
+
+Timeouts are **seconds** (float): `None` waits indefinitely, `0` polls.
+
+Exceptions all derive from `fuse.FuseError`: `Timeout`, `ConnectionClosed`,
+`AuthError`, `ConfigError`, `MessageTooLarge`.
+
+Blocking calls release the GIL, so other threads keep running while one is
+parked in `recv`.
+
+## Checking an install
+
+```sh
+python -m fuse selftest
+```
+
+Prints the version, which library got loaded, and whether encryption is
+available, then runs a loopback round-trip — which also confirms this kernel
+supports the socket features Fuse needs.
+
+## Also in this project
+
+A C/C++ SDK with the same API (`#include <fuse/sdk.h>`), and a separate
+higher-throughput API for moving whole files or large buffers. Both come from
+the standalone installer:
+
+```sh
+curl -fsSL https://github.com/kamalkoushikd/fuse-nw/releases/latest/download/install.sh | sh
+```
+
+- **Full SDK guide:** https://github.com/kamalkoushikd/fuse-nw/blob/main/docs/SDK.md
+- **Benchmarks vs QUIC:** https://github.com/kamalkoushikd/fuse-nw/blob/main/bench/RESULTS.md
+
+## License
+
+MIT. Note that the bundled wolfSSL is GPLv2 (a commercial license is
+available from wolfSSL Inc.), so a wheel that links it is a combined work
+subject to the GPL when redistributed.