koreader

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package koreader serves KOReader's progress sync protocol, so KOReader keeps its place through Shisho as a custom sync server. KOReader names a document by a hash of its bytes (ADR 0014).

Index

Constants

View Source
const (

	// FinishedAt is the percentage that counts as the end. KOReader's
	// continuous view never reports 100%, and the last pages are back matter,
	// so reaching them finishes the book, as a streaming service counts an
	// episode watched once the credits start.
	FinishedAt = 0.99
)

Variables

This section is empty.

Functions

func ParseProgress added in v0.8.0

func ParseProgress(progress string) (models.ReadingLocator, bool)

ParseProgress reads KOReader's progress: an XPointer, which is a path, or the 1-based page as a string.

func RegisterRoutes

func RegisterRoutes(e *echo.Echo, db *bun.DB, bookService *books.Service)

RegisterRoutes registers the protocol under the prefix users enter as KOReader's custom sync server.

Types

type AuthorizeResponse

type AuthorizeResponse struct {
	Authorized string `json:"authorized"`
}

AuthorizeResponse answers a successful login.

type Documents added in v0.8.0

type Documents struct {
	// contains filtered or unexported fields
}

Documents finds the File a KOReader document hash names, and gives KOReader a Reading Position in that copy, labelled with where it came from. Progress sync and the KOReader plugin both use it.

func NewDocuments added in v0.8.0

func NewDocuments(db *bun.DB, bookService *books.Service) *Documents

NewDocuments returns Documents for db, reaching Books through bookService.

func (*Documents) Progress added in v0.8.0

func (d *Documents) Progress(ctx context.Context, user *models.User, device *devices.Device, document string, file *models.DocumentHash, position *models.ReadingPosition) (ProgressResponse, error)

Progress is what device gets for position in the copy file names.

A position another source wrote is labelled with that source's identity in Shisho, so KOReader takes it for another device's and offers the jump. A reflowable one is translated into this copy's XPointer: the web reader's CFI, another KOReader's XPointer in a copy with or without a KePub's span markup, or this Device's own from its other copy.

A copy a user linked (ADR 0017), or a position kept as a percentage only, has no place KOReader's progress sync can go to, so it gets none.

func (*Documents) Resolve added in v0.8.0

func (d *Documents) Resolve(ctx context.Context, user *models.User, device *devices.Device, document string) (*models.DocumentHash, error)

Resolve returns the File a document hash names for this request, or nil when it names none the request reaches. Identical bytes can map to several Files, so it's the ones the user's library access and the Device's scope reach, preferring one the user already has a position in, so reading doesn't split across them, and then the oldest. Only when Shisho produced none of them is it the File the user linked the copy to (ADR 0017), marked UserMade.

func (*Documents) Source added in v0.8.0

func (d *Documents) Source(ctx context.Context, user *models.User, position *models.ReadingPosition) (string, string, error)

Source names the reader that wrote position, and gives it an id, as KOReader shows another device's: the Device's own, or a stand-in for the web reader or a Device since removed.

type ProgressResponse

type ProgressResponse struct {
	Document   string   `json:"document,omitempty"`
	Progress   string   `json:"progress,omitempty"`
	Percentage *float64 `json:"percentage,omitempty"`
	Device     string   `json:"device,omitempty"`
	DeviceID   string   `json:"device_id,omitempty"`
	// Timestamp is when the position was reported, in Unix seconds. KOReader
	// compares it to its own clock.
	Timestamp *int64 `json:"timestamp,omitempty"`
}

ProgressResponse answers a pull. With no position to give, every field is absent: an empty object is KOReader's "no progress".

type ProtocolErrorResponse

type ProtocolErrorResponse struct {
	Message string `json:"message"`
}

ProtocolErrorResponse is an error in the protocol's shape, not Shisho's usual one. KOReader shows Message to the user as it stands.

type UpdateProgressPayload

type UpdateProgressPayload struct {
	// Document is the document hash.
	Document string `json:"document" validate:"required,max=64"`
	// Progress is an XPointer, or the 1-based page as a string for page-based
	// documents.
	Progress   string   `json:"progress" validate:"required,max=4096"`
	Percentage *float64 `json:"percentage" validate:"required,min=0,max=1" tstype:",required"`
	// Device and DeviceID are how KOReader names itself. Shisho knows the
	// Device from its credential; it stores these with the position and sends
	// them back to the same Device, which then knows the position as its own.
	Device   string `json:"device,omitempty" validate:"max=256"`
	DeviceID string `json:"device_id,omitempty" validate:"max=256"`
	// Metadata is what KOReader knows about the book, when its "send
	// metadata" option is on. It's only logged, to name a book Shisho doesn't
	// recognize.
	Metadata json.RawMessage `json:"metadata,omitempty" tstype:"unknown"`
	// Timestamp is when KOReader was at the position, in Unix seconds. No
	// KOReader release sends it yet; one that does dates its offline pushes.
	Timestamp *int64 `json:"timestamp,omitempty" validate:"omitempty,min=1"`
}

UpdateProgressPayload is KOReader pushing its position in a document.

type UpdateProgressResponse

type UpdateProgressResponse struct {
	Document  string `json:"document"`
	Timestamp int64  `json:"timestamp"`
}

UpdateProgressResponse answers a push. Timestamp is in Unix seconds.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址