Initial implementation

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, v0 ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    # TODO(preview): other platforms
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Lint
+        run: |
+          uv run ruff format --check
+          uv run ruff check
+
+      - name: Type check
+        # TODO(preview): Get both passing
+        run: |
+          uv run pyright . || true
+          uv run mypy --check-untyped-defs . || true
+
+      - name: Run tests
+        run: |
+          uv run pytest --cov=src --cov-report=html:coverage_html_report
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html-report-${{ matrix.python-version }}
+          path: coverage_html_report/
+
+      - name: Build API docs
+        run: uv run pydoctor src/nexusrpc
+      # TODO(prerelease)
+      # - name: Deploy prod API docs
+      #   if: ${{ github.ref == 'refs/heads/main' }}
+      #   env:
+      #     VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      #     VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      #   run: npx vercel deploy build/apidocs -t ${{ secrets.VERCEL_TOKEN }} --prod --yes

.gitignore

@@ -1,10 +1,5 @@
-# Python-generated files
-__pycache__/
-*.py[oc]
-build/
-dist/
-wheels/
-*.egg-info
-
-# Virtual environments
+__pycache__
 .venv
+apidocs
+dist
+docs

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+### Type-checking, Linting, and Formatting
+
+```sh
+uv run pyright
+uv run mypy --check-untyped-defs .
+uv run ruff check --select I
+uv run ruff format --check
+```
+
+### Formatting
+```
+uv run ruff check --select I --fix
+uv run ruff format
+```
+
+### API docs
+```
+uv run pydoctor src/nexusrpc
+```

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Temporal Technologies Inc. All Rights Reserved
+
+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.

README.md

@@ -0,0 +1,14 @@
+# Nexus Python SDK
+
+## What is Nexus?
+
+Nexus is a synchronous RPC protocol. Arbitrary duration operations are modelled on top
+of a set of pre-defined synchronous RPCs.
+
+A Nexus caller calls a handler. The handler may respond inline (synchronous response) or
+return a token referencing the ongoing operation (asynchronous response). The caller can
+cancel an asynchronous operation, check for its outcome, or fetch its current state. The
+caller can also specify a callback URL, which the handler uses to deliver the result of
+an asynchronous operation when it is ready.
+
+TODO(prerelease): README content

pyproject.toml

@@ -6,9 +6,36 @@ readme = "README.md"
 authors = [
     { name = "Dan Davison", email = "dandavison7@gmail.com" }
 ]
-requires-python = ">=3.13"
-dependencies = []
+requires-python = ">=3.9"
+dependencies = [
+    "typing-extensions>=4.12.2",
+]
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "mypy>=1.15.0",
+    "pydoctor>=25.4.0",
+    "pyright>=1.1.400",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "pytest-cov>=6.1.1",
+    "pytest-pretty>=1.3.0",
+    "ruff>=0.12.0",
+]
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nexusrpc"]
+
+[tool.pyright]
+include = ["src", "tests"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true

src/nexusrpc/__init__.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+from enum import Enum
+
+from ._serializer import Content as Content, LazyValue as LazyValue
+from ._service import (
+    Operation as Operation,
+    ServiceDefinition as ServiceDefinition,
+    service as service,
+)
+
+
+@dataclass
+class Link:
+    """
+    Link contains a URL and a Type that can be used to decode the URL.
+    Links can contain any arbitrary information as a percent-encoded URL.
+    It can be used to pass information about the caller to the handler, or vice versa.
+    """
+
+    # The URL must be percent-encoded.
+    url: str
+    # Can describe an actual data type for decoding the URL. Valid chars: alphanumeric, '_', '.',
+    # '/'
+    type: str
+
+
+class OperationState(Enum):
+    """
+    Describes the current state of an operation.
+    """
+
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELED = "canceled"
+    RUNNING = "running"
+
+
+@dataclass
+class OperationInfo:
+    """
+    Information about an operation.
+    """
+
+    # Token identifying the operation (returned on operation start).
+    token: str
+
+    # The operation's state
+    state: OperationState

src/nexusrpc/_serializer.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    Any,
+    AsyncIterable,
+    Awaitable,
+    Iterable,
+    Mapping,
+    Optional,
+    Protocol,
+    Type,
+    Union,
+)
+
+
+@dataclass
+class Content:
+    """
+    A container for a map of headers and a byte array of data.
+
+    It is used by the SDK's Serializer interface implementations.
+    """
+
+    headers: Mapping[str, str]
+    """
+    Header that should include information on how to deserialize this content.
+    Headers constructed by the framework always have lower case keys.
+    User provided keys are treated case-insensitively.
+    """
+
+    data: Optional[bytes] = None
+    """Request or response data. May be undefined for empty data."""
+
+
+class Serializer(Protocol):
+    """
+    Serializer is used by the framework to serialize/deserialize input and output.
+    """
+
+    def serialize(self, value: Any) -> Union[Content, Awaitable[Content]]:
+        """Serialize encodes a value into a Content."""
+        ...
+
+    # TODO(prerelease): does None work as the sentinel type here, meaning do not attempt
+    # type conversion, despite the fact that Python treats None as a valid type?
+    def deserialize(
+        self, content: Content, as_type: Optional[Type[Any]] = None
+    ) -> Union[Any, Awaitable[Any]]:
+        """Deserialize decodes a Content into a value.
+
+        Args:
+            content: The content to deserialize.
+            as_type: The type to convert the result of deserialization into.
+                     Do not attempt type conversion if this is None.
+        """
+        ...
+
+
+class LazyValue:
+    """
+    A container for a value encoded in an underlying stream.
+
+    It is used to stream inputs and outputs in the various client and server APIs.
+    """
+
+    def __init__(
+        self,
+        serializer: Serializer,
+        headers: Mapping[str, str],
+        stream: Optional[Union[AsyncIterable[bytes], Iterable[bytes]]] = None,
+    ) -> None:
+        """
+        Args:
+            serializer: The serializer to use for consuming the value.
+            headers: Headers that include information on how to process the stream's content.
+                     Headers constructed by the framework always have lower case keys.
+                     User provided keys are treated case-insensitively.
+            stream:  Iterable that contains request or response data. None means empty data.
+        """
+        self.serializer = serializer
+        self.headers = headers
+        self.stream = stream
+
+    async def consume(self, as_type: Optional[Type[Any]] = None) -> Any:
+        """
+        Consume the underlying reader stream, deserializing via the embedded serializer.
+        """
+        # TODO(prerelease): HandlerError(BAD_REQUEST) on error while deserializing?
+        if self.stream is None:
+            return await self.serializer.deserialize(
+                Content(headers=self.headers), as_type=as_type
+            )
+        elif not isinstance(self.stream, AsyncIterable):
+            raise ValueError("When using consume, stream must be an AsyncIterable")
+
+        return await self.serializer.deserialize(
+            Content(
+                headers=self.headers,
+                data=b"".join([c async for c in self.stream]),
+            ),
+            as_type=as_type,
+        )
+
+    # TODO(prerelease): we have a syncio module now for the syncio version of SyncOperationHandler
+    # SHould this go in a syncio module?
+    def consume_sync(self, as_type: Optional[Type[Any]] = None) -> Any:
+        """
+        Consume the underlying reader stream, deserializing via the embedded serializer.
+        """
+        # TODO(prerelease): HandlerError(BAD_REQUEST) on error while deserializing?
+        if self.stream is None:
+            return self.serializer.deserialize(
+                Content(headers=self.headers), as_type=as_type
+            )
+        elif not isinstance(self.stream, Iterable):
+            raise ValueError("When using consume_sync, stream must be an Iterable")
+
+        return self.serializer.deserialize(
+            Content(
+                headers=self.headers,
+                data=b"".join([c for c in self.stream]),
+            ),
+            as_type=as_type,
+        )