Files
eleith edfed39347 perf: Eliminate N+1 API calls and refactor for reliability
This commit resolves a critical N+1 performance issue in the article sync process and introduces a major refactoring to simplify authentication, improve API reliability, and enhance the developer experience.

Major Changes:

- **Perf: Eliminate N+1 API Calls in Sync**
  - Reworked the /api/kobo/get handler to fetch all bookmark details in a single batch request to Readeck's /api/bookmarks/sync endpoint.
  - This replaces the previous method of making an individual API call for each article, resolving a significant performance bottleneck that caused server instability under load.

- **Refactor: Simplify Authentication**
  - Removed the  package and all related encryption logic. The application now uses plain-text Readeck access tokens directly in the configuration, greatly simplifying setup.
  - Replaced the old token generation script with a simpler Generated a new token for your device:

  b25ae315-36cc-4a8c-9515-2d729c2db526

Please add this token to your 'config.yaml' file under the 'users' section.
For example:

users:
  - token: "b25ae315-36cc-4a8c-9515-2d729c2db526"
    readeck_access_token: "your-plain-text-readeck-access-token"

You can get your Readeck access token from your Readeck instance's settings page..

- **Fix: API and Sync Reliability**
  - Corrected the Readeck API request payload for the new batch sync, fixing a bug that caused empty results.
  - Implemented robust URL matching for the /download endpoint to handle variations in query parameters and  prefixes.

- **Feat: Developer Experience and Testing**
  - Introduced a new  package for leveled logging.
  - Added debug-level logging for all incoming Kobo API requests to aid troubleshooting.
  - Added a suite of end-to-end shell scripts in  for manual testing of all API endpoints.

- **Test: Refactor and Enhance Unit Tests**
  - Refactored the application and client test suites to reflect the new single-batch API call, removing mocks for the old N+1 behavior.
  - Added comprehensive unit tests for the new URL comparison logic.
  - Corrected and improved mock responses and assertions across the test suite to align with the updated API payloads and application behavior.

- **Docs: Improve Clarity and Accuracy**
  - Rewrote the API Endpoints section in  for clarity.
  - Updated documentation to reflect the new authentication model and E2E tests.
2025-11-08 15:59:21 -08:00

59 lines
1.7 KiB
Go

package readeck
import (
"time"
)
type BookmarkSync struct {
ID string `json:"id"`
Time time.Time `json:"time"`
Type string `json:"type"` // Literal["update"] | Literal["delete"]
}
type ResourceImage struct {
Src string `json:"src"`
Width int `json:"width"`
Height int `json:"height"`
}
type ResourceLink struct {
Src string `json:"src"`
}
type Resources struct {
Article *ResourceLink `json:"article"`
Icon *ResourceImage `json:"icon"`
Image *ResourceImage `json:"image"`
Log *ResourceLink `json:"log"`
Props *ResourceLink `json:"props"`
Thumbnail *ResourceImage `json:"thumbnail"`
}
type Bookmark struct {
Authors []string `json:"authors"`
Created time.Time `json:"created"`
Description string `json:"description"`
DocumentType string `json:"document_type"`
HasArticle bool `json:"has_article"`
Href string `json:"href"`
ID string `json:"id"`
IsArchived bool `json:"is_archived"`
IsDeleted bool `json:"is_deleted"`
IsMarked bool `json:"is_marked"`
Labels []string `json:"labels"`
Lang string `json:"lang"`
Loaded bool `json:"loaded"`
ReadProgress int `json:"read_progress"`
Resources Resources `json:"resources"`
Site string `json:"site"`
SiteName string `json:"site_name"`
State int `json:"state"`
TextDirection string `json:"text_direction"`
Title string `json:"title"`
Type string `json:"type"`
Updated time.Time `json:"updated"`
URL string `json:"url"`
WordCount int `json:"word_count"`
Published time.Time `json:"published"`
}