JSON-RPC & Backend Communication
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The DXKB project utilizes a standardized JSON-RPC 2.0 protocol for primary communication between the frontend and backend services, specifically targeting BV-BRC (Bacterial and Viral Bioinformatics Resource Center) infrastructure. This system provides a robust interface for job submission, workspace management, and data retrieval, ensuring consistency across various bioinformatics tools.
Backend communication is primarily abstracted through specialized client classes that handle request encapsulation, authentication header injection (using Bearer or OAuth tokens), and error normalization. This architecture allows the application to interact with high-level services like the AppService for computational tasks and the Workspace service for file management while maintaining a uniform transport layer.
Sources: src/types/workspace.ts:1-18, src/lib/jsonrpc-client.ts, src/app/(footer)/privacy-policy/data/privacy-policy-sections.ts:50-57
Core Communication Architecture
The communication layer is built upon a generic JsonRpcClient which is then extended or utilized by domain-specific services. The system supports both single calls and batch requests to optimize network performance.
JSON-RPC Transport Layer
The base transport layer follows the JSON-RPC 2.0 specification, requiring an id, method, params, and the jsonrpc version string in every request.
The diagram shows the hierarchy of service clients inheriting from or utilizing the base JSON-RPC transport to communicate with backend endpoints.
Sources: src/lib/jsonrpc-client.ts, src/types/workspace.ts:2-18
Authentication Handling
Authentication is handled via Authorization headers. The system distinguishes between standard Bearer tokens and specialized OAuth prefixes depending on the target service. For instance, file uploads to the Shock service require an "OAuth" prefix, while general RPC calls typically use the raw token or a "Bearer" prefix.
Sources: src/lib/tests/jsonrpc-client.test.ts:153-162, src/app/api/services/workspace/upload/tests/route.test.ts:133-150
Service Implementation
AppService
The AppService manages the lifecycle of bioinformatics jobs, including submission, monitoring, and result retrieval. It interfaces with methods such as AppService.start_app2 for job submission and AppService.query_task_details for status updates.
| Method | RPC Method | Description |
|---|---|---|
submitService | AppService.start_app2 | Submits a new job with specified app name and parameters. |
queryJobDetails | AppService.query_task_details | Retrieves status and metadata for a specific job ID. |
killJob | AppService.kill_task | Cancels a running task. |
enumerateTasksFiltered | AppService.enumerate_tasks_filtered | Lists jobs with support for pagination and filtering. |
Sources: src/lib/tests/app-service.test.ts:31-180, src/types/workspace.ts:98-135
Workspace Service
The Workspace service provides a virtual filesystem for user data. It supports operations like directory listing (ls), file retrieval (get), and permission management.
This sequence illustrates the data flow and transformation from raw backend tuples to sanitized frontend objects.
Sources: src/lib/services/workspace/tests/client.test.ts:88-120, src/app/api/services/workspace/tests/route.test.ts:47-65
Data Models & Schemas
Job Representation
Jobs are represented by a state machine that transitions through various statuses.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the job. |
status | JobStatus | Current state (pending, running, completed, failed, etc.). |
submit_time | string | ISO timestamp of job submission. |
parameters | Record<string, unknown> | Input configuration provided to the app. |
Sources: src/types/workspace.ts:21-47
Error Handling
The system uses a custom JsonRpcError class to handle protocol-level errors. Backend errors are captured and normalized, often including a numeric code and descriptive data.
export interface JsonRpcResponse<T = unknown> {
id: number;
result?: T;
error?: {
code: number;
message: string;
data?: unknown;
};
jsonrpc: "2.0";
}
Sources: src/types/workspace.ts:10-18, src/lib/tests/jsonrpc-client.test.ts:182-195
Summary
The JSON-RPC and backend communication system in DXKB provides a structured, type-safe way to interact with complex bioinformatics backends. By abstracting the transport layer and automating authentication, the architecture allows developers to focus on service-specific logic while maintaining high reliability and consistent error handling across the application.
Sources: src/lib/jsonrpc-client.ts, src/lib/app-service.ts, src/types/workspace.ts