Workspace API Implementation

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/services/workspace/server.ts
• src/lib/services/workspace/methods/crud.ts
• src/app/api/services/workspace/route.ts
• src/lib/services/workspace/client.ts
• src/lib/services/workspace/types.ts
• src/lib/services/workspace/index.ts
• src/lib/services/workspace/helpers.ts

Introduction

The Workspace API Implementation provides a robust interface for managing user data, file structures, and permissions within the DXKB ecosystem. It serves as a bridge between the frontend application and the BV-BRC Workspace service, facilitating complex operations such as file CRUD (Create, Read, Update, Delete), directory listing, and metadata management.

The system is designed with a layered architecture comprising a base JSON-RPC client, specialized method classes (CRUD, Listing, Permissions), and a server-side proxy. This structure ensures secure authentication via BV-BRC tokens and consistent data transformation between the raw upstream API and the application's internal data models.

Architecture and Components

The implementation follows a modular pattern where the WorkspaceApi class acts as a central orchestrator. It instantiates specialized method handlers that consume a common WorkspaceApiClient.

Core API Client

The WorkspaceApiClient handles the underlying HTTP communication. It communicates with an internal proxy route (/api/services/workspace) to ensure authentication cookies are included in requests. It is responsible for wrapping parameters into JSON-RPC 2.0 structures and processing raw results into usable objects using helpers like metaListToObj.

Key methods include:

• makeRequest<T>: The primary engine for executing JSON-RPC calls. It handles method-specific result processing, such as mapping Workspace.ls outputs or returning raw arrays for CRUD operations.
• createWorkspaceApiClient: A factory function for generating client instances.

Sources: src/lib/services/workspace/client.ts:18-103, src/lib/services/workspace/client.ts:133-138

Data Flow: Proxy Implementation

Requests from the client-side components do not go directly to the upstream BV-BRC API. Instead, they pass through a Next.js Route Handler that injects authentication and sanitizes errors.

Error Handling and Sanitization

The proxy includes a sanitizeUpstreamError function to ensure that sensitive stack traces or internal configurations are not leaked to the client. It specifically extracts the code and message from upstream failures.

Sources: src/app/api/services/workspace/route.ts:11-30

CRUD Operations and Metadata

The WorkspaceCrudMethods class provides a high-level API for manipulating workspace objects. It supports both structured object parameters and simplified path-based operations.

Key CRUD Functions

Function	Description	Upstream Method
createFolderByPath	Creates a directory using a full path string.	Workspace.create
createUploadNode	Generates a Shock URL (link_reference) for file uploads.	Workspace.create
deleteMultipleObjects	Removes an array of objects by their full paths.	Workspace.delete
updateObjectType	Modifies the metadata type of an existing object.	Workspace.update_metadata
saveObject	Saves file content (base64) along with metadata.	Workspace.save

Sources: src/lib/services/workspace/methods/crud.ts:40-109, src/lib/services/workspace/methods/crud.ts:186-218

Object Transformation

Raw data from the Workspace API is typically returned as an array (tuple). The metaListToObj helper maps these indices to descriptive property names used throughout the application.

Index	Field	Description
0	name	The object filename or folder name.
1	type	The workspace type (e.g., contigs, folder, job_result).
2	path	The parent directory path.
4	id	Unique UUID for the object.
7	userMeta	User-defined metadata object.
11	link_reference	URL for external storage (Shock).

Sources: src/lib/services/workspace/helpers.ts:16-31

Server-Side Implementation

For React Server Components (RSC), a dedicated server.ts module provides direct access to the Workspace API. This bypasses the client-side fetch cycle but still utilizes the same WORKSPACE_API_URL and authentication logic.

Conclusion

The Workspace API Implementation provides a secure and structured environment for managing biological data. By centralizing logic in the WorkspaceApiClient and delegating specific tasks to specialized method classes, the system maintains high maintainability. The dual-path approach (Proxy for client-side and server.ts for server-side) ensures performance and security across the various rendering modes of the application.