ton/NATSBridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

update docs

Browse Source
This commit is contained in:
narawat
2026-05-13 17:35:46 +07:00
parent c25c6a8a43
commit b0acee053c
5 changed files with 120 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/specification.md
View File

@@ -1,7 +1,7 @@
# Specification: NATSBridge
**Version**: 1.1.0
**Date**: 2026-03-23
**Version**: 1.2.0
**Date**: 2026-05-13
**Status**: Active
**Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl)
**Specification Format**: JSON Schema + AsyncAPI
@@ -418,11 +418,11 @@ When `transport = "link"`, the `data` field contains a URL pointing to the uploa
```julia
function smartsend(
subject::String,
data::AbstractArray{Tuple{String, Any, String}};
broker_url::String = "nats://localhost:4222",
fileserver_url::String = "http://localhost:8080",
data::AbstractArray{Tuple{String, T1, String}, 1};
broker_url::String = DEFAULT_BROKER_URL,
fileserver_url::String = DEFAULT_FILESERVER_URL,
fileserver_upload_handler::Function = plik_oneshot_upload,
size_threshold::Int = 500_000,
size_threshold::Int = DEFAULT_SIZE_THRESHOLD,
correlation_id::String = string(uuid4()),
msg_purpose::String = "chat",
sender_name::String = "NATSBridge",
@@ -430,13 +430,13 @@ function smartsend(
receiver_id::String = "",
reply_to::String = "",
reply_to_msg_id::String = "",
is_publish::Bool = true,
NATS_connection::Union{NATS.Connection, Nothing} = nothing,
msg_id::String = string(uuid4()),
sender_id::String = string(uuid4())
)::Tuple{msg_envelope_v1, String}
)::Tuple{msg_envelope_v1, String} where {T1<:Any}
```
**Note**: NATS publishing is the caller's responsibility. Returns `(env::msg_envelope_v1, env_json_str::String)`.
#### Python
```python
@@ -454,13 +454,13 @@ async def smartsend(
receiver_id: str = "",
reply_to: str = "",
reply_to_msg_id: str = "",
is_publish: bool = True,
nats_connection: Any = None,
msg_id: str = None,
sender_id: str = None
) -> Tuple[Dict, str]:
```
**Note**: NATS publishing is the caller's responsibility.
#### JavaScript (Node.js)
```typescript
@@ -479,14 +479,14 @@ async function smartsend(
receiver_id?: string;
reply_to?: string;
reply_to_msg_id?: string;
is_publish?: boolean;
nats_connection?: NATS.Connection;
msg_id?: string;
sender_id?: string;
}
): Promise<[Object, string]>;
```
**Note**: NATS publishing is the caller's responsibility.
#### JavaScript (Browser)
```typescript
@@ -505,51 +505,27 @@ async function smartsend(
receiver_id?: string;
reply_to?: string;
reply_to_msg_id?: string;
is_publish?: boolean;
nats_connection?: NATSClient | NATS.Connection;
msg_id?: string;
sender_id?: string;
}
): Promise<[Object, string]>;
// NATSClient class for connection management
class NATSClient {
constructor(url: string, keepAlive?: boolean);
connect(): Promise<NATS.Connection>;
publish(subject: string, message: string, correlationId: string): Promise<void>;
close(): Promise<void>;
getConnection(): NATS.Connection | null;
isConnected(): boolean;
}
// NATSConnectionPool for managing multiple connections
class NATSConnectionPool {
constructor(url: string, maxSize?: number);
acquire(): Promise<NATSClient>;
release(client: NATSClient): void;
closeAll(): Promise<void>;
}
// publishMessage function for manual publishing
async function publishMessage(
brokerUrlOrClient: string | NATSClient | NATS.Connection,
subject: string,
message: string,
correlationId: string,
closeConnection?: boolean
): Promise<void>;
```
**Note**: NATS publishing is the caller's responsibility.
#### MicroPython
```python
def smartsend(
subject: str,
data: List[Tuple[str, Any, str]],
size_threshold: int = 100_000, # Lower threshold for memory constraints
**kwargs
) -> Tuple[Dict, str]:
```
**Note**: NATS publishing is the caller's responsibility.
#### Dart (Desktop/Flutter)
```dart
@@ -567,12 +543,11 @@ Future<[Map<String, dynamic>, String]> smartsend(
String receiverId = '',
String replyTo = '',
String replyToMsgId = '',
bool isPublish = true,
dynamic natsConnection,
String? msgId,
String? senderId,
}) async {
// Returns [envelope, jsonString]
// NATS publishing is caller's responsibility
}
```
@@ -593,12 +568,11 @@ Future<[Map<String, dynamic>, String]> smartsend(
String receiverId = '',
String replyTo = '',
String replyToMsgId = '',
bool isPublish = true,
dynamic natsConnection,
String? msgId,
String? senderId,
}) async {
// Returns [envelope, jsonString]
// NATS publishing is caller's responsibility
}
```
@@ -608,7 +582,7 @@ Future<[Map<String, dynamic>, String]> smartsend(
```julia
function smartreceive(
msg::NATS.Msg;
msg_json_str::String; # Pass String(nats_msg.payload) from NATS subscription
fileserver_download_handler::Function = _fetch_with_backoff,
max_retries::Int = 5,
base_delay::Int = 100,
@@ -616,11 +590,13 @@ function smartreceive(
)::JSON.Object{String, Any}
```
**Note**: Input is JSON string from NATS message payload, not NATS.Msg directly.
#### Python
```python
async def smartreceive(
msg: Any,
msg_json_str: str, # JSON string from NATS message payload
fileserver_download_handler: Callable = fetch_with_backoff,
max_retries: int = 5,
base_delay: int = 100,
@@ -628,11 +604,13 @@ async def smartreceive(
) -> Dict[str, Any]:
```
**Note**: Input is JSON string from NATS message payload.
#### JavaScript (Node.js)
```typescript
async function smartreceive(
msg: Object,
msg_json_str: string, // JSON string from NATS message payload
options?: {
fileserver_download_handler?: Function;
max_retries?: number;
@@ -646,7 +624,7 @@ async function smartreceive(
```typescript
async function smartreceive(
msg: Object,
msg_json_str: string, // JSON string from NATS message payload
options?: {
fileserver_download_handler?: Function;
max_retries?: number;
@@ -656,17 +634,22 @@ async function smartreceive(
): Promise<Object>;
```
**Note**: Input is JSON string from NATS message payload.
#### MicroPython
```python
def smartreceive(msg: Any, **kwargs) -> Dict[str, Any]:
def smartreceive(msg_json_str: str, **kwargs) -> Dict[str, Any]:
```
**Note**: Input is JSON string from NATS message payload.
#### Dart (Desktop/Flutter)
```dart
Future<Map<String, dynamic>> smartreceive(
Map<String, dynamic> msg, {
Map<String, dynamic> msg_json_str, // JSON object from NATS message payload
{
Function? fileserverDownloadHandler,
int maxRetries = 5,
int baseDelay = 100,
@@ -680,7 +663,8 @@ Future<Map<String, dynamic>> smartreceive(
```dart
Future<Map<String, dynamic>> smartreceive(
Map<String, dynamic> msg, {
Map<String, dynamic> msg_json_str, // JSON object from NATS message payload
{
Function? fileserverDownloadHandler,
int maxRetries = 5,
int baseDelay = 100,
@@ -703,6 +687,12 @@ function fileserver_upload_handler(
dataname::String,
data::Vector{UInt8}
)::Dict{String, Any}
# Overload: Upload file from disk
function fileserver_upload_handler(
file_server_url::String,
filepath::String
)::Dict{String, Any}
```
**Return Format**:
@@ -1057,6 +1047,12 @@ flowchart TD
| Date | Version | Changes | Requirement ID(s) |
|------|---------|---------|-------------------|
| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/NATSBridge.jl) | All |
| - | - | Updated smartsend signatures: removed is_publish, nats_connection; added sender_name | FR-001 through FR-014 |
| - | - | Updated smartreceive signatures: takes msg_json_str::String instead of msg | FR-001 through FR-014 |
| - | - | Removed publishMessage function and NATSClient/NATSConnectionPool classes from browser section | FR-013, FR-014 |
| - | - | Added plik_oneshot_upload(filepath) overload to file server interface | FR-008, FR-009 |
| - | - | Fixed SIZE_THRESHOLD default to 500,000 bytes | FR-003, FR-004 |
| 2026-03-23 | 1.1.0 | Updated to ASG Framework specification guidelines | All |
| 2026-03-15 | 1.1.0 | Browser connection management | FR-001 through FR-014 |
| 2026-03-13 | 1.0.0 | Initial specification | FR-001 through FR-014, NFR-101 through NFR-405 |