docs(scanner): update Bruno requests for new scanner endpoints
- Update Scan Ebooks.bru to reflect async background scanning - Add Get Scan Status.bru for checking job progress - Add Start Watch Mode.bru for instant file monitoring - Add Stop Watch Mode.bru for stopping library monitoring - Add Get Watch Mode Status.bru for checking watched libraries - Document all new endpoints with examples and status codes
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
meta {
|
||||
name: Get Scan Status
|
||||
type: http
|
||||
seq: 4
|
||||
}
|
||||
|
||||
get {
|
||||
url: {{base_url}}/api/scanner/status/{{job_id}}
|
||||
auth: inherit
|
||||
}
|
||||
|
||||
settings {
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
}
|
||||
|
||||
docs {
|
||||
## Get Scan Status
|
||||
|
||||
Retrieves the status and progress of an asynchronous scan job.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/scanner/status/:jobId
|
||||
|
||||
**Authentication:** Required (Bearer token, Admin only)
|
||||
|
||||
**URL Parameters:**
|
||||
- `jobId` (string, required): The job ID returned from the scan endpoint
|
||||
- Example: `550e8400-e29b-41d4-a716-446655440000`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"job_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"status": "completed",
|
||||
"error": "",
|
||||
"result": {
|
||||
"message": "scan completed",
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
},
|
||||
"progress": 1.0
|
||||
}
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- `job_id` (string): Job identifier
|
||||
- `status` (string): Current status
|
||||
- `pending`: Job is queued
|
||||
- `running`: Job is currently processing
|
||||
- `completed`: Job finished successfully
|
||||
- `failed`: Job failed with error
|
||||
- `cancelled`: Job was cancelled
|
||||
- `error` (string): Error message if status is "failed"
|
||||
- `result` (object): Scan results when completed
|
||||
- `message` (string): Completion message
|
||||
- `library_id` (string): Library that was scanned
|
||||
- `progress` (number): Progress indicator (0.0 to 1.0)
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Job status retrieved successfully
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (admin access required)
|
||||
- 404: Job not found
|
||||
|
||||
**Example Workflow:**
|
||||
1. POST /api/scanner/scan with folder_paths
|
||||
2. Receive job_id in response
|
||||
3. Poll GET /api/scanner/status/{job_id} every few seconds
|
||||
4. When status is "completed" or "failed", stop polling
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
meta {
|
||||
name: Get Watch Mode Status
|
||||
type: http
|
||||
seq: 7
|
||||
}
|
||||
|
||||
get {
|
||||
url: {{base_url}}/api/scanner/watch/status
|
||||
auth: inherit
|
||||
}
|
||||
|
||||
docs {
|
||||
## Get Watch Mode Status
|
||||
|
||||
Retrieves the current status of watch mode for all libraries.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/scanner/watch/status
|
||||
|
||||
**Authentication:** Required (Bearer token, Admin only)
|
||||
|
||||
**Response:** HTTP 200 (OK)
|
||||
```json
|
||||
{
|
||||
"watching_libraries": [
|
||||
"550e8400-e29b-41d4-a716-446655440000",
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
],
|
||||
"total_watching": 2
|
||||
}
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- `watching_libraries` (array of strings): List of library IDs currently being watched
|
||||
- `total_watching` (number): Total number of libraries being watched
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Status retrieved successfully
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (admin access required)
|
||||
|
||||
**Use cases:**
|
||||
- Check which libraries are currently being monitored
|
||||
- Verify that watch mode started successfully after server boot
|
||||
- Debug file system monitoring issues
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
meta {
|
||||
name: Scan Ebooks
|
||||
name: Scan Ebooks (Background)
|
||||
type: http
|
||||
seq: 1
|
||||
}
|
||||
@@ -15,37 +15,48 @@ settings {
|
||||
timeout: 0
|
||||
}
|
||||
|
||||
body:json {
|
||||
{
|
||||
"folder_paths": ["/path/to/ebooks"]
|
||||
}
|
||||
}
|
||||
|
||||
docs {
|
||||
## Scan Ebooks
|
||||
## Scan Ebooks (Background)
|
||||
|
||||
Triggers a scanning operation to discover and index ebook files in the library.
|
||||
Triggers an asynchronous ebook scanning operation. The scan runs in the background and can be monitored using the job ID.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/scanner/scan
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
**Authentication:** Required (Bearer token, Admin only)
|
||||
|
||||
**Request Body:** (optional)
|
||||
- `library_id` (string, optional): Specific library ID to scan
|
||||
- `scan_depth` (number, optional): Maximum directory depth to scan
|
||||
- `file_types` (array, optional): File extensions to include
|
||||
**Request Body:**
|
||||
- `folder_paths` (array of strings, required): List of folder paths to scan
|
||||
- Example: `["/path/to/ebooks", "/another/path"]`
|
||||
|
||||
**Response:**
|
||||
- JSON object containing scan operation details
|
||||
- `scan_id` (string): Unique scan operation identifier
|
||||
- `status` (string): Scan status ("initiated", "running", "completed")
|
||||
- `library_id` (string): Library being scanned
|
||||
- `files_found` (number): Number of files discovered
|
||||
- `files_processed` (number): Number of files processed
|
||||
- `started_at` (string): Scan start timestamp
|
||||
- `estimated_completion` (string): Estimated completion time
|
||||
**Response:** HTTP 202 (Accepted)
|
||||
```json
|
||||
{
|
||||
"message": "scan job enqueued",
|
||||
"job_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"status": "pending"
|
||||
}
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- `message` (string): Confirmation message
|
||||
- `job_id` (string): Unique job identifier for tracking progress
|
||||
- `status` (string): Initial job status ("pending")
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Scan initiated successfully
|
||||
- 400: Invalid request parameters
|
||||
- 202: Scan job successfully enqueued
|
||||
- 400: Invalid request (missing folder_paths)
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (insufficient permissions)
|
||||
- 409: Scan already in progress
|
||||
- 500: Internal server error
|
||||
- 403: Forbidden (admin access required)
|
||||
- 500: Failed to enqueue scan job
|
||||
|
||||
**Next Steps:**
|
||||
Use the returned `job_id` with `GET /api/scanner/status/:jobId` to check scan progress.
|
||||
}
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
meta {
|
||||
name: Start Watch Mode
|
||||
type: http
|
||||
seq: 5
|
||||
}
|
||||
|
||||
post {
|
||||
url: {{base_url}}/api/scanner/watch/start
|
||||
body: json
|
||||
auth: inherit
|
||||
}
|
||||
|
||||
body:json {
|
||||
{
|
||||
"library_id": "{{library_id}}"
|
||||
}
|
||||
}
|
||||
|
||||
docs {
|
||||
## Start Watch Mode
|
||||
|
||||
Starts real-time file system monitoring for a specific library. New ebooks will be detected and processed almost instantly.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/scanner/watch/start
|
||||
|
||||
**Authentication:** Required (Bearer token, Admin only)
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, required): UUID of the library to watch
|
||||
- Example: `"550e8400-e29b-41d4-a716-446655440000"`
|
||||
|
||||
**Response:** HTTP 200 (OK)
|
||||
```json
|
||||
{
|
||||
"message": "watch mode started for library",
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
- Monitors all folders configured for the library
|
||||
- Automatically detects new ebook files (CREATE events)
|
||||
- Detects modifications to existing files (WRITE events)
|
||||
- Processes new files within milliseconds of detection
|
||||
- Automatically watches new subdirectories as they're created
|
||||
|
||||
**Supported file types:**
|
||||
- `.epub`, `.pdf`, `.mobi`, `.azw3`, `.fb2`, `.txt`
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Watch mode started successfully
|
||||
- 400: Invalid request (missing library_id)
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (admin access required)
|
||||
- 409: Already watching this library
|
||||
- 500: Failed to start watch mode (no folders configured, etc.)
|
||||
|
||||
**Note:** Watch mode is automatically started for all libraries when the server starts.
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
meta {
|
||||
name: Stop Watch Mode
|
||||
type: http
|
||||
seq: 6
|
||||
}
|
||||
|
||||
post {
|
||||
url: {{base_url}}/api/scanner/watch/stop
|
||||
body: json
|
||||
auth: inherit
|
||||
}
|
||||
|
||||
body:json {
|
||||
{
|
||||
"library_id": "{{library_id}}"
|
||||
}
|
||||
}
|
||||
|
||||
docs {
|
||||
## Stop Watch Mode
|
||||
|
||||
Stops real-time file system monitoring for a specific library.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/scanner/watch/stop
|
||||
|
||||
**Authentication:** Required (Bearer token, Admin only)
|
||||
|
||||
**Request Body:**
|
||||
- `library_id` (string, required): UUID of the library to stop watching
|
||||
- Example: `"550e8400-e29b-41d4-a716-446655440000"`
|
||||
|
||||
**Response:** HTTP 200 (OK)
|
||||
```json
|
||||
{
|
||||
"message": "watch mode stopped for library",
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Watch mode stopped successfully
|
||||
- 400: Invalid request (missing library_id)
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (admin access required)
|
||||
- 404: Not watching this library
|
||||
- 500: Internal server error
|
||||
|
||||
**Note:** If no libraries are being watched, the watch mode context is cleaned up automatically.
|
||||
}
|
||||
Reference in New Issue
Block a user