Skip to content

Commit d4856a6

Browse files
committed
docs: stale code-block sweep + slim binding stubs + 0.1.2 install commands
Code-block sweep across the site to align with the actual public API that shipped in aster-rpc 0.1.2 / @aster-rpc/aster 0.1.2: - All `from aster.decorators import ...` -> `from aster import ...` - All `from aster.codec import wire_type` -> `from aster import wire_type` - All `from aster.types import SerializationMode` -> `from aster import SerializationMode` (the `aster.types` module never existed -- previous docs would ModuleNotFoundError on copy-paste) - `scoped="stream"` -> `scoped="session"` (stream is a back-compat alias, session is canonical and matches the framework's logging/error output) - `AsterClient(endpoint_addr=...)` -> `AsterClient(address="aster1...")` (endpoint_addr is a back-compat alias; address is canonical and matches the Mission Control guide) - `pip install aster-python` -> `pip install aster-rpc` / `aster-cli` (aster-python was never published; the actual PyPI distributions are aster-rpc and aster-cli, both at 0.1.2) Quickstart (python.mdx): - TypeScript section no longer uses @wiretype for the Hello example. TS auto-derives wire tags the same way Python does, so the simplest service is genuinely two decorators (@service + @rpc), not three. Merged types.ts into service.ts to match the Python "one file" feel. - Consumer uses the dynamic proxy (`client.proxy("HelloService")`) which speaks JSON and needs no local type definitions, matching the Mission Control guide style. Define-a-service guide: - Removed stray trailing ``` that opened an empty code block in the bidi streaming section (markdown rendering glitch). - Session-scoped service example now uses scoped="session" and documents the framework's `cls(peer)` constructor contract. - Serialization modes table updated: NATIVE now reads "deployments where interoperability is second to performance" (clearer than the old "single-language deployments where performance matters"). - Added "Proxy method shapes" callout showing all four RPC pattern call forms in one place (unary/server-stream/client-stream/bidi), to head off the recurring "I tried `await mc.tailLogs(...)` and it crashed" QA finding. Concepts (serialization.mdx): - Restructured around the actual modes Aster ships: XLANG, NATIVE, ROW, JSON. JSON is now described as the debuggability escape hatch (the gRPC pain point Aster addresses). - The dynamic proxy speaks JSON automatically, so any service that supports JSON mode can be called from the shell without codegen. Bindings/python: - Drop create_local_client and create_session from the API surface table -- those are internal helpers, not part of the public API. - Sessions section now documents the actual two-sided story: `@service(scoped="session")` on the producer + `await client.session("Name")` on the consumer, which returns a SessionProxyClient that multiplexes method calls over a single bidi stream. Reference/cli.mdx: - Install instructions point at aster-cli on PyPI (was aster-python). Slim: - Delete the empty placeholder index pages for bindings/{dotnet,go,jvm,rust}. Those bindings are in progress in the framework repo but the public docs site is Python+TypeScript only at 0.1.2; the orphaned stubs were misleading. Will be re-added when each binding ships. - Sidebars updated to drop the deleted entries. - Homepage (src/pages/index.tsx + custom.css) slimmed to match the smaller binding scope. Mission Control guide left intact: it is the canonical user-facing walkthrough and was already polished.
1 parent 8a1e1b0 commit d4856a6

21 files changed

Lines changed: 213 additions & 374 deletions

docs/bindings/dotnet/index.mdx

Lines changed: 0 additions & 57 deletions
This file was deleted.

docs/bindings/go/index.mdx

Lines changed: 0 additions & 58 deletions
This file was deleted.

docs/bindings/jvm/index.mdx

Lines changed: 0 additions & 57 deletions
This file was deleted.

docs/bindings/python/index.mdx

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,11 @@ Production-ready for 0.1-alpha. The Python binding is the first-class implementa
1717
## Installation
1818

1919
```bash
20-
pip install aster-python
20+
pip install aster-rpc # framework
21+
pip install aster-cli # optional: shell, contract gen, trust commands
2122
```
2223

23-
**Requirements:** Python 3.9+, macOS / Linux / Windows.
24+
**Requirements:** Python 3.9 -- 3.13, macOS / Linux / Windows.
2425

2526
The package includes a native extension (compiled Rust via PyO3), so wheels are provided for common platforms. Building from source requires a Rust toolchain and maturin.
2627

@@ -29,8 +30,7 @@ The package includes a native extension (compiled Rust via PyO3), so wheels are
2930
```python
3031
import asyncio
3132
from dataclasses import dataclass
32-
from aster import AsterServer, AsterClient
33-
from aster.decorators import service, rpc
33+
from aster import AsterServer, AsterClient, service, rpc
3434

3535
@dataclass
3636
class HelloRequest:
@@ -52,7 +52,7 @@ async def main():
5252
addr = srv.address
5353

5454
# Consumer
55-
async with AsterClient(endpoint_addr=addr) as client:
55+
async with AsterClient(address=addr) as client:
5656
hello = await client.client(HelloService)
5757
resp = await hello.say_hello(HelloRequest(name="World"))
5858
print(resp.message) # "Hello, World!"
@@ -86,10 +86,8 @@ Define services and methods with decorators on plain Python classes:
8686

8787
| API | Purpose |
8888
|-----|---------|
89-
| `AsterClient(endpoint_addr=...)` | High-level declarative consumer. Handles admission and service discovery. |
89+
| `AsterClient(address="aster1...")` | High-level declarative consumer. Handles admission and service discovery. |
9090
| `create_client(ServiceClass, connection=conn)` | Lower-level client. Wraps an existing QUIC connection. |
91-
| `create_local_client(ServiceClass, server)` | In-process client using `LocalTransport` (for testing). |
92-
| `create_session(ServiceClass, connection=conn)` | Session-scoped client with per-connection state. |
9391

9492
### Configuration
9593

@@ -126,8 +124,8 @@ Built-in middleware chain:
126124

127125
| API | Purpose |
128126
|-----|---------|
129-
| `@service(scoped="stream")` | Per-connection service instances. |
130-
| `create_session(ServiceClass, connection=conn)` | Open a session-scoped stream from the client. |
127+
| `@service(scoped="session")` | Producer-side: per-connection service instances (the class `__init__` receives a `peer` argument). |
128+
| `await client.session("ServiceName")` | Consumer-side: open a multiplexed session against a session-scoped service. Returns a `SessionProxyClient` whose method calls share one bidi stream. |
131129

132130
## Architecture
133131

docs/bindings/rust/index.mdx

Lines changed: 0 additions & 51 deletions
This file was deleted.

docs/concepts/serialization.mdx

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ import LanguageTabs, {TabItem} from '@site/src/components/LanguageTabs';
88

99
Aster uses [Apache Fory](https://fury.apache.org) for serialization. Fory is a high-performance, cross-language serialization framework that operates on native language objects -- no IDL compilation required, no generated code to maintain.
1010

11-
## Three serialization modes
11+
## Four serialization modes
1212

13-
Fory provides three distinct serialization modes. Each serves a different use case, and Aster exposes all three. The mode is declared per-service, with per-method override available.
13+
Aster exposes four serialization modes -- three from Fory and one universal JSON escape hatch. The mode is declared per-service, with per-method override available.
1414

1515
### XLANG (cross-language)
1616

@@ -29,33 +29,30 @@ NATIVE mode uses the language's own serialization primitives -- Fory replaces pi
2929

3030
Use NATIVE when:
3131
- Both sides of the call are in the same language.
32-
- Maximum serialization performance is the priority.
33-
- Cross-language interoperability is not needed for this service.
32+
- Deployments where interoperability is second to performance.
3433

3534
### ROW (zero-copy random access)
3635

37-
ROW mode produces a columnar binary format that supports zero-copy field access. Individual fields can be read without deserializing the entire message. This is useful for data-heavy workloads where only a subset of fields is needed per operation, or where integration with columnar data systems (e.g., Apache Arrow) is valuable.
36+
ROW mode produces a row-oriented binary format from Fory that supports zero-copy field access. Individual fields can be read without deserializing the entire message. Useful for data-heavy workloads where the consumer reads only a subset of fields per record, or where the schema is sent once and many rows follow.
3837

3938
Use ROW when:
4039
- Payloads are large and consumers often access only a few fields.
41-
- Partial deserialization improves performance.
42-
- Columnar data integration is needed.
40+
- You're streaming many records with a stable schema (the schema is hoisted into the first frame and amortized across the stream).
41+
- You're integrating with columnar data systems.
4342

44-
### JSON (universal fallback)
43+
### JSON (debuggable, universal)
4544

4645
JSON mode uses UTF-8 JSON for request and response payloads. All frames on a stream -- including the `StreamHeader` and `RpcStatus` trailer -- are JSON objects. Field names use camelCase.
4746

48-
JSON mode exists for language bindings where the Fory XLANG implementation is not yet production-ready (e.g., TypeScript). All Aster servers accept JSON mode alongside their declared Fory modes -- no configuration needed.
49-
5047
Use JSON when:
51-
- The client is in a language without a mature Fory XLANG implementation.
52-
- Debugging wire traffic (JSON is human-readable).
53-
- Building quick prototypes with the proxy client.
48+
- You want readable wire traffic for debugging (`tcpdump` / `wireshark` show payloads as plain text instead of opaque binary -- the classic gRPC pain point).
49+
- You're building quick prototypes with the dynamic proxy client (`client.proxy("ServiceName")`), which always speaks JSON.
50+
- A client is in a language without a mature Fory XLANG implementation.
5451

55-
Clients that support Fory XLANG should prefer it for performance. JSON mode is a universal fallback, not the primary path.
52+
Clients that support Fory XLANG should prefer it for performance and payload size. JSON mode is the escape hatch, not the primary path.
5653

5754
:::info
58-
The Python proxy client (`client.proxy("ServiceName")`) uses JSON mode automatically. Generated typed clients use Fory XLANG.
55+
The dynamic proxy client (`client.proxy("ServiceName")`) uses JSON mode automatically -- so any service that supports JSON mode can be called from the shell or from a Python/TypeScript proxy without generating a typed client first. Generated typed clients use Fory XLANG by default.
5956
:::
6057

6158
## Mode selection
@@ -66,7 +63,7 @@ A service declares its default serialization mode. Individual methods can overri
6663
<TabItem value="python" label="Python">
6764

6865
```python
69-
from aster import service, rpc, server_stream, SerializationMode
66+
from aster import service, rpc, SerializationMode
7067

7168
@service(
7269
name="Analytics",

0 commit comments

Comments
 (0)