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
- func ParseProgress(progress string) (models.ReadingLocator, bool)
- func RegisterRoutes(e *echo.Echo, db *bun.DB, bookService *books.Service)
- type AuthorizeResponse
- type Documents
- func (d *Documents) Progress(ctx context.Context, user *models.User, device *devices.Device, ...) (ProgressResponse, error)
- func (d *Documents) Resolve(ctx context.Context, user *models.User, device *devices.Device, ...) (*models.DocumentHash, error)
- func (d *Documents) Source(ctx context.Context, user *models.User, position *models.ReadingPosition) (string, string, error)
- type ProgressResponse
- type ProtocolErrorResponse
- type UpdateProgressPayload
- type UpdateProgressResponse
Constants ¶
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.
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
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.