api

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: GPL-3.0 Imports: 55 Imported by: 0

Documentation

Overview

Package api serves the server's HTTP surface: the REST API under /api/v1 (generated from api/openapi.yaml), the health probes, the metrics and, later, the event stream and the web app.

Index

Constants

View Source
const (
	SessionCookie = "panelarr_session"
	CSRFCookie    = "panelarr_csrf"
	CSRFHeader    = "X-CSRF-Token"
	APIKeyHeader  = "X-Api-Key" //nolint:gosec // a header name, not a credential
)

Cookie and header names.

View Source
const (
	AccessPublic = "public"
	AccessUser   = "user"
	AccessAdmin  = "admin"
)

Access levels, from the spec's x-panelarr-access extension.

View Source
const (
	CodeInvalidRequest   = "invalid_request"
	CodeNotFound         = "not_found"
	CodeMethodNotAllowed = "method_not_allowed"
	CodeInternal         = "internal"
)

Error codes shared by many endpoints. Feature code adds its own.

View Source
const BasePath = "/api/v1"

BasePath is where the REST API is served.

View Source
const RequestIDHeader = "X-Request-Id"

RequestIDHeader carries the request ID in requests and responses.

View Source
const StatusClientClosedRequest = 499

StatusClientClosedRequest answers a request whose client went away before it finished (as nginx's 499); the client never sees it, but the request log does.

Variables

This section is empty.

Functions

func ClientIP

func ClientIP(ctx context.Context) string

ClientIP returns the request's client address.

func NewHandler

func NewHandler(deps Deps) (http.Handler, error)

NewHandler builds the root HTTP handler.

func RequestID

func RequestID(ctx context.Context) string

RequestID returns the request's ID, or "".

Types

type Check

type Check struct {
	Name     string
	Required bool
	Run      func(ctx context.Context) error
}

Check is one readiness dependency. A failing required check makes the server not ready (e.g. the database). A failing optional one only marks it degraded: the server keeps serving what it can (e.g. reading downloaded chapters while a connected service is down).

type Deps

type Deps struct {
	Log     *slog.Logger
	Metrics *metrics.Metrics // nil when metrics are off
	// MetricsOnAPI serves /metrics on this handler, to callers holding the
	// metrics:read scope.
	MetricsOnAPI bool
	// Checks are the readiness dependencies, e.g. the database.
	Checks []Check

	Auth    *auth.Service
	Users   *users.Service
	Meta    *meta.Service
	Images  *imagecache.Cache
	Plugins *plugins.Host
	// Signer signs image links the server hands out.
	Signer *imagecache.Signer
	Jobs   *jobs.Manager
	Queue  *queue.Queue
	Hub    *events.Hub
	// Store answers list queries that need no service logic.
	Store     *store.Store
	Library   *library.Service
	Chapters  *chapters.Service
	Reader    *reader.Service
	Downloads *downloads.Service
	Storages  *storage.Manager
	Network   *network.Service

	// SecureCookies marks session cookies Secure (https deployments).
	SecureCookies bool
	// TrustedProxies may set X-Forwarded-For.
	TrustedProxies []netip.Prefix
	// Web serves the web app for every path nothing else answers (optional).
	Web http.Handler
}

Deps are what the HTTP layer needs from the rest of the server.

type Problem

type Problem struct {
	Status int
	Code   string
	Detail string
	Fields []apigen.FieldError
	// CurrentRunID goes with already_running.
	CurrentRunID *uuid.UUID
	// CurrentRun is a plugin job's running run (its own ID).
	CurrentRun string
	// WorkID, WorkTitle and ChapterLabel say which chapter a reader
	// couldn't load (only when the caller may see it).
	WorkID       *uuid.UUID
	WorkTitle    string
	ChapterLabel string
}

Problem is an error a handler returns to send a specific problem response. Any other error becomes a 500 without details.

func NewProblem

func NewProblem(status int, code, detail string) *Problem

NewProblem builds a Problem.

func (*Problem) Error

func (p *Problem) Error() string

type Server

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

Server implements the generated strict API interface.

func (*Server) AcceptInvite

AcceptInvite creates an account from an invite and signs it in.

func (*Server) AddFromSource

AddFromSource adds a series seen on a source, or offers entries to pick.

func (*Server) AddToLibrary

AddToLibrary adds a catalogue entry to the caller's library.

func (*Server) AssignNetworkProfile

AssignNetworkProfile assigns a profile at a level.

func (*Server) AttachCandidate

AttachCandidate attaches a candidate.

func (*Server) AttachSeries

AttachSeries attaches a series by source and key, or by URL.

func (*Server) BrowseCatalog

BrowseCatalog lists the catalogue.

func (*Server) CancelJobRun

CancelJobRun cancels a running run.

func (*Server) CancelMetaJobRun

CancelMetaJobRun cancels a running meta job run.

func (*Server) CancelPluginJobRun

CancelPluginJobRun cancels a plugin job's running run.

func (*Server) CancelTask

CancelTask cancels a task.

func (*Server) ChangeMyPassword

ChangeMyPassword changes the caller's password.

func (*Server) CheckInvite

CheckInvite says whether an invite token is valid.

func (*Server) CheckMetaConnection

CheckMetaConnection checks the connection again now.

func (*Server) ClearMyHistory

ClearMyHistory takes everything the caller read up to now out of their history.

func (*Server) ClearPackageImageRetries

ClearPackageImageRetries removes a package's setting.

func (*Server) ClearSourceImageRetries

ClearSourceImageRetries removes a source's own setting.

func (*Server) CompleteSetup

CompleteSetup finishes the wizard.

func (*Server) ConfirmMetaDuplicate

ConfirmMetaDuplicate merges a pair.

func (*Server) CreateInvite

CreateInvite creates an invite.

func (*Server) CreateMyApiKey

CreateMyApiKey creates an API key for the caller.

func (*Server) CreateNetworkProfile

CreateNetworkProfile adds a profile.

func (*Server) CreateProxy

CreateProxy adds a proxy.

func (*Server) CreateSetupAdmin

CreateSetupAdmin creates the first account and signs it in.

func (*Server) CreateSolver

CreateSolver adds a solver.

func (*Server) CreateStorage

CreateStorage adds a storage after checking it works.

func (*Server) CreateUser

CreateUser creates a user with a password.

func (*Server) DeleteChapterFile

DeleteChapterFile deletes a chapter's downloaded file.

func (*Server) DeleteInvite

DeleteInvite revokes an invite.

func (*Server) DeleteMyApiKey

DeleteMyApiKey revokes one of the caller's API keys.

func (*Server) DeleteMySession

DeleteMySession ends one of the caller's sessions.

func (*Server) DeleteNetworkProfile

DeleteNetworkProfile removes a profile.

func (*Server) DeletePlugin

DeletePlugin removes a plugin.

func (*Server) DeleteProxy

DeleteProxy removes a proxy.

func (*Server) DeleteReaderSettings

DeleteReaderSettings removes one level of the caller's reader settings.

func (*Server) DeleteSolver

DeleteSolver removes a solver.

func (*Server) DeleteStorage

DeleteStorage removes an empty storage.

func (*Server) DeleteUser

DeleteUser deletes a user.

func (*Server) DetachSeries

DetachSeries rejects a series for the work.

func (*Server) DismissMetaDuplicate

DismissMetaDuplicate marks a pair as different works.

func (*Server) DownloadChapters

DownloadChapters queues downloads of a work's chapters.

func (*Server) GetCatalogEntry

GetCatalogEntry returns one entry in full.

func (*Server) GetCatalogEntryCover

GetCatalogEntryCover serves an entry's cover from the image cache.

func (*Server) GetChapterPage

GetChapterPage serves one page image.

func (*Server) GetChapterPages

GetChapterPages returns a chapter's pages for the reader.

func (*Server) GetJob

GetJob returns one job.

func (*Server) GetJobRun

GetJobRun returns one run in full.

func (*Server) GetMe

GetMe returns the caller.

func (*Server) GetMetaConnection

GetMetaConnection shows the connection and its state.

func (*Server) GetMetaDuplicate

GetMetaDuplicate returns one pair.

func (*Server) GetMetaDuplicateJudge

GetMetaDuplicateJudge returns the decision model settings.

func (*Server) GetMetaHealth

GetMetaHealth returns meta's own health.

func (*Server) GetMetaJob

GetMetaJob returns one of meta's jobs.

func (*Server) GetMetaJobRun

GetMetaJobRun returns a meta job's run in full.

func (*Server) GetMetaNetwork

GetMetaNetwork shows each metadata provider's profile in force and what meta applies.

func (*Server) GetMetaSearchEngine

GetMetaSearchEngine returns meta's search engine settings and state.

func (*Server) GetMetaSyncRun

GetMetaSyncRun returns one sync run.

func (*Server) GetMyHistory

GetMyHistory lists the chapters the caller read.

func (*Server) GetMyPreferences

GetMyPreferences returns the caller's app preferences.

func (*Server) GetMyUpdates

GetMyUpdates lists the chapters that appeared in the caller's library.

func (*Server) GetMyUpdatesStatus

GetMyUpdatesStatus says how the chapter checks of the caller's library stand.

func (*Server) GetNetworkProfile

GetNetworkProfile returns a profile.

func (*Server) GetPackage

GetPackage returns one of a plugin's packages.

func (*Server) GetPackageIcon

GetPackageIcon serves a package's icon through the server, cached.

func (*Server) GetPackageImageRetries

GetPackageImageRetries returns how a package's sources retry images.

func (*Server) GetPlugin

GetPlugin returns a plugin.

func (*Server) GetPluginConfig

GetPluginConfig returns a plugin's configuration.

func (*Server) GetPluginJob

GetPluginJob returns one of a plugin's jobs.

func (*Server) GetPluginJobRun

GetPluginJobRun returns a plugin job's run in full.

func (*Server) GetPluginNetwork

GetPluginNetwork shows the profile in force for each of a plugin's sources.

func (*Server) GetProxy

GetProxy returns a proxy.

func (*Server) GetQueue

GetQueue returns the queue per kind.

func (*Server) GetReaderSettings

GetReaderSettings returns the caller's reader settings for a place.

func (*Server) GetSetup

GetSetup reports the first-run wizard's state.

func (*Server) GetSolver

GetSolver returns a solver.

func (*Server) GetSourceImageRetries

GetSourceImageRetries returns how a source retries images.

func (*Server) GetSourceNetwork

GetSourceNetwork shows one source's profile and what its plugin applies.

func (*Server) GetSourceSettings

GetSourceSettings returns a source's own settings.

func (*Server) GetSystemHealth

GetSystemHealth shows every component's health, with errors (admins).

func (*Server) GetSystemInfo

GetSystemInfo identifies the server and says whether it needs setting up.

func (*Server) GetTask

GetTask returns a task.

func (*Server) GetUser

GetUser returns a user.

func (*Server) GetWork

GetWork returns a work with its matching per source.

func (*Server) GetWorkChapter

GetWorkChapter returns one chapter with its copies.

func (*Server) GetWorkCover

GetWorkCover serves a work's cover from the image cache.

func (*Server) GetWorkProgress

GetWorkProgress returns the caller's progress in a work.

func (*Server) InstallPackage

InstallPackage queues installing a package.

func (*Server) ListBookmarks

ListBookmarks lists the caller's bookmarked chapters of a work.

func (*Server) ListDownloads

ListDownloads lists downloads.

func (*Server) ListInvites

ListInvites lists open invites.

func (*Server) ListJobRuns

ListJobRuns lists a job's runs.

func (*Server) ListJobs

ListJobs lists the background jobs.

func (*Server) ListLibrary

ListLibrary lists the caller's library.

func (*Server) ListMetaDuplicates

ListMetaDuplicates lists suspected duplicate pairs.

func (*Server) ListMetaJobRuns

ListMetaJobRuns lists a meta job's runs.

func (*Server) ListMetaJobs

ListMetaJobs lists meta's jobs.

func (*Server) ListMetaProviders

ListMetaProviders lists meta's providers.

func (*Server) ListMetaSyncRuns

ListMetaSyncRuns lists provider sync runs.

func (*Server) ListMyApiKeys

ListMyApiKeys lists the caller's API keys.

func (*Server) ListMySessions

ListMySessions lists the caller's sessions.

func (*Server) ListNetworkAssignments

ListNetworkAssignments lists the assignments.

func (*Server) ListNetworkProfiles

ListNetworkProfiles lists profiles.

func (*Server) ListPackageOrigins

ListPackageOrigins lists where a plugin's packages come from.

func (*Server) ListPackages

ListPackages lists what a plugin offers and has installed.

func (*Server) ListPluginJobRuns

ListPluginJobRuns lists a plugin job's runs.

func (*Server) ListPluginJobs

ListPluginJobs lists a plugin's jobs.

func (*Server) ListPlugins

ListPlugins lists the plugins.

func (*Server) ListProxies

ListProxies lists the proxies.

func (*Server) ListSeriesChapters

ListSeriesChapters lists one source's chapters of a work.

func (*Server) ListSolvers

ListSolvers lists the solvers.

func (*Server) ListSources

ListSources lists the sources (admins), filtered.

func (*Server) ListStorages

ListStorages lists the storages.

func (*Server) ListTasks

ListTasks lists tasks, newest first.

func (*Server) ListUsers

ListUsers lists users by username.

func (*Server) ListWorkChapters

ListWorkChapters lists a work's unified chapters.

func (*Server) Login

Login signs a user in with a password.

func (*Server) Logout

Logout ends the current session.

func (*Server) MarkChaptersRead

MarkChaptersRead marks chapters read or unread.

func (*Server) MarkWorkSeen

MarkWorkSeen clears the caller's "new" badges of a work.

func (*Server) MatchWork

MatchWork queues matching of a work.

func (*Server) MoveStorage

MoveStorage queues moving every file to another storage.

func (*Server) PinChapterVariant

PinChapterVariant pins (or unpins) a chapter's copy.

func (*Server) PutMetaDuplicateJudge

PutMetaDuplicateJudge saves the decision model settings.

func (*Server) PutMetaSearchEngine

PutMetaSearchEngine saves meta's search engine settings.

func (*Server) PutMyPreferences

PutMyPreferences replaces the caller's app preferences.

func (*Server) PutReaderSettings

PutReaderSettings replaces one level of the caller's reader settings.

func (*Server) RefreshMetaEntry

RefreshMetaEntry asks an entry's providers for fresh data.

func (*Server) RefreshMyUpdates

RefreshMyUpdates queues chapter checks of the caller's library.

func (*Server) RefreshPackageOrigin

RefreshPackageOrigin refreshes one origin now.

func (*Server) RefreshWork

RefreshWork queues chapter checks of a work's series now.

func (*Server) RegisterPlugin

RegisterPlugin adds a plugin.

func (*Server) ReloadPackage

ReloadPackage loads an installed package again.

func (*Server) RemoveFromLibrary

RemoveFromLibrary takes a work out of the caller's library.

func (*Server) RemoveFromMyHistory

RemoveFromMyHistory takes a series out of the caller's history.

func (*Server) ReopenMetaDuplicate

ReopenMetaDuplicate takes back a dismissal.

func (*Server) ReplaceNetworkProfile

ReplaceNetworkProfile replaces a profile's settings.

func (*Server) ResetMetaDuplicateJudge

ResetMetaDuplicateJudge goes back to meta's configured settings.

func (*Server) ResetMetaSearchEngine

ResetMetaSearchEngine goes back to meta's configured search engine.

func (*Server) RetryTask

RetryTask queues a failed or cancelled task again.

func (*Server) RunJob

RunJob starts a job now.

func (*Server) RunMetaJob

RunMetaJob starts one of meta's jobs.

func (*Server) RunMetaProviderSync

RunMetaProviderSync starts a provider sync in the metadata service.

func (*Server) RunPluginJob

RunPluginJob starts one of a plugin's jobs.

func (*Server) SearchCatalog

SearchCatalog searches the catalogue.

func (*Server) SearchWorkSource

SearchWorkSource searches one of the work's sources to fix its match.

func (*Server) SetAutoDownload

SetAutoDownload turns automatic downloads of new chapters on or off.

func (*Server) SetBookmarks

SetBookmarks bookmarks chapters or removes their bookmarks.

func (*Server) SetChapterProgress

SetChapterProgress saves where the caller is in a chapter.

func (*Server) SetMetaConnection

SetMetaConnection tests and saves the connection.

func (*Server) SetPackageImageRetries

SetPackageImageRetries sets how a package's sources retry images.

func (*Server) SetPackageLanguages

SetPackageLanguages chooses a package's languages.

func (*Server) SetPluginConfig

SetPluginConfig replaces a plugin's configuration.

func (*Server) SetSourceHealthCheck

SetSourceHealthCheck turns a source's scheduled health checks on or off.

func (*Server) SetSourceImageRetries

SetSourceImageRetries sets a source's own setting.

func (*Server) SetSourceSettings

SetSourceSettings changes some of a source's settings.

func (*Server) SourceChapters

SourceChapters lists a series' chapters.

func (*Server) SourceFilters

SourceFilters returns a source's filters in the contract's JSON form.

func (*Server) SourceImage

SourceImage serves a signed image of a source, fetched through its plugin and cached.

func (*Server) SourceLatest

SourceLatest lists a source's latest updates.

func (*Server) SourcePopular

SourcePopular lists a source's popular series.

func (*Server) SourceSearch

SourceSearch searches a source.

func (*Server) SourceSeries

SourceSeries returns a series' details.

func (*Server) SyncPlugin

SyncPlugin refreshes a plugin now.

func (*Server) TestMetaDuplicateJudge

TestMetaDuplicateJudge tries decision model settings.

func (*Server) TestMetaSearchEngine

TestMetaSearchEngine tries search engine settings.

func (*Server) TestProxy

TestProxy checks a saved proxy.

func (*Server) TestProxySettings

TestProxySettings checks an unsaved proxy (or a saved one with changes).

func (*Server) TestSolver

TestSolver checks a saved solver.

func (*Server) TestSolverSettings

TestSolverSettings checks an unsaved solver.

func (*Server) TestStorage

TestStorage checks a storage now.

func (*Server) UnassignNetworkProfile

UnassignNetworkProfile removes an assignment.

func (*Server) UninstallPackage

UninstallPackage queues uninstalling a package.

func (*Server) UpdateMe

UpdateMe changes the caller's profile.

func (*Server) UpdatePackage

UpdatePackage queues updating a package.

func (*Server) UpdatePlugin

UpdatePlugin changes a plugin.

func (*Server) UpdateProxy

UpdateProxy changes a proxy.

func (*Server) UpdateQueueKind

UpdateQueueKind pauses or resumes a kind.

func (*Server) UpdateSolver

UpdateSolver changes a solver.

func (*Server) UpdateSource

UpdateSource turns a source on or off.

func (*Server) UpdateStorage

UpdateStorage changes a storage or makes it the default.

func (*Server) UpdateUser

UpdateUser changes a user.

func (*Server) UpdateWorkSeries

UpdateWorkSeries sets a series' priority.

Directories

Path Synopsis
Package apigen provides primitives to interact with the openapi HTTP API.
Package apigen provides primitives to interact with the openapi HTTP API.

Jump to

Keyboard shortcuts

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