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.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
+
+      - 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,74 @@
+# Nexus Python SDK
+
+## What is Nexus?
+
+[Nexus](https://github.com/nexus-rpc/) is a synchronous RPC protocol. Arbitrary duration operations are modeled 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.
+
+## Installation
+
+```
+uv add nexus-rpc
+```
+or
+```
+pip install nexus-rpc
+```
+
+## Usage
+
+The SDK currently supports two use cases:
+
+1. As an end user, defining Nexus services and operations.
+
+2. Implementing a Nexus handler that can accept and respond to incoming Nexus requests, dispatching to the corresponding user-defined Nexus operation.
+
+The handler in (2) would form part of a server or worker that processes Nexus requests; the SDK does not yet provide reference implementations of these, or of a Nexus client.
+
+### Defining Nexus services and operations
+
+```python
+from dataclasses import dataclass
+
+import nexusrpc
+from nexusrpc.handler import StartOperationContext, service_handler, sync_operation
+
+
+@dataclass
+class MyInput:
+    name: str
+
+
+@dataclass
+class MyOutput:
+    message: str
+
+
+@nexusrpc.service
+class MyNexusService:
+    my_sync_operation: nexusrpc.Operation[MyInput, MyOutput]
+
+
+@service_handler(service=MyNexusService)
+class MyNexusServiceHandler:
+    # You can create an __init__ method accepting what is needed by your operation
+    # handlers to handle requests. You will typically instantiate your service handler class
+    # when starting your Nexus server/worker.
+
+    # This is a Nexus operation that responds synchronously to all requests. That means
+    # that the `start` method returns the final operation result.
+    #
+    # Sync operations are free to make arbitrary network calls.
+    @sync_operation
+    async def my_sync_operation(
+        self, ctx: StartOperationContext, input: MyInput
+    ) -> MyOutput:
+        return MyOutput(message=f"Hello {input.name}!")
+```
+

pyproject.toml

@@ -6,9 +6,35 @@ readme = "README.md"
 authors = [
     { name = "Dan Davison", email = "[email protected]" }
 ]
-requires-python = ">=3.13"
-dependencies = []
+requires-python = ">=3.9"
+dependencies = [
+    "typing-extensions>=4.12.2",
+]
+
+[dependency-groups]
+dev = [
+    "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,68 @@
+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,
+)
+from ._types import InputT as InputT, OutputT as OutputT
+
+
+@dataclass(frozen=True)
+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(frozen=True)
+class OperationInfo:
+    """
+    Information about an operation.
+    """
+
+    # Token identifying the operation (returned on operation start).
+    token: str
+
+    # The operation's state
+    state: OperationState
+
+
+class OperationErrorState(Enum):
+    """
+    The state of an operation as described by an OperationError.
+    """
+
+    FAILED = "failed"
+    CANCELED = "canceled"
+
+
+class OperationError(Exception):
+    """
+    An error that represents "failed" and "canceled" operation results.
+    """
+
+    def __init__(self, message: str, *, state: OperationErrorState):
+        super().__init__(message)
+        self.state = state