Miniflux - As-Is Product Behaviour

MINIFLUXVersion 1.0Created 2026-09-09 by Alice Alicedottir <alice@example.org>

This document records the as-is product behaviour of Miniflux 2, reverse-engineered from the repository as a baseline for a reimplementation. It states what the code does today, not what it is intended or documented to do.

Definitions are normative and read on their own. Content pieces are informative: a piece of type evidence names the files and tests a requirement was established from and is expected to be discarded once the document has been reviewed; notes and examples record reasoning, caveats, open questions and places where the code and its own documentation disagree, and are meant to stay.

Voice is simple present, declarative, third person. Where the code admits two readings, the definition states the reading the code implements and a note records the ambiguity. Where the code and the documentation disagree, the definition follows the code and a note states the documentation's claim without deciding between them.

Architecture, coding conventions, the presentation layer, the Go client library, packaging and the database migrations are out of scope.

1Accounts and access

1.1Local credentials

MINIFLUX-1Password minimum length

A password shorter than six characters is refused when an account is created and when a password is changed. There is no maximum length, no character-class requirement and no check against a list of common passwords.

Evidence

internal/validator/user.go:163-168 (validatePassword), reached from ValidateUserCreationWithPassword and ValidateUserModification.

MINIFLUX-2Password storage

A password is stored as a bcrypt hash produced at the library's default cost. The plaintext is never stored, and the hash is excluded from every JSON representation of a user.

Evidence

internal/crypto/crypto.go (HashPassword, using bcrypt.DefaultCost); internal/model/user.go:17, where the Password field carries the JSON tag -.

Note

The cost is whatever golang.org/x/crypto/bcrypt defines as its default rather than a value Miniflux chooses, so it can move when the dependency is upgraded.

MINIFLUX-3Username character set

A username may contain letters, numbers, and the characters _, -, @ and .. Any other character causes the account creation or modification to be refused. The check is applied only to the value being submitted, so an account created before the rule existed keeps its username.

Evidence

internal/validator/user.go:176-189 (validateUsername).

Note

The function's own doc comment says the check rejects any character "that isn't alphanumerical nor _ and -", but the body also accepts @ and .. The definition above states what the code does. The comment goes on to explain why those two are needed - an OAuth2 or OpenID Connect account uses the email address as its username - so the comment, not the code, looks like the thing that was left behind.

MINIFLUX-4Username uniqueness

A username is unique across the installation. Creating an account with a username that already exists is refused, and so is renaming an account to a username another account holds.

Evidence

internal/validator/user.go:23 and :43, both returning error.user_already_exists.

MINIFLUX-5Local authentication switch

Setting DISABLE_LOCAL_AUTH to 1 refuses every username-and-password sign-in attempt, and the login form no longer offers the fields. Accounts continue to exist and remain reachable through the other authentication sources.

Evidence

internal/ui/login_check.go:26-32; internal/ui/form/settings.go:95 and :135; internal/template/functions.go:52.

MINIFLUX-6Authentication source requirement

Starting the service with DISABLE_LOCAL_AUTH enabled and neither OAUTH2_PROVIDER nor AUTH_PROXY_HEADER configured is refused at configuration-parsing time with the message DISABLE_LOCAL_AUTH is enabled but neither OAUTH2_PROVIDER nor AUTH_PROXY_HEADER is set. Please enable at least one authentication source. The service does not start.

Evidence

internal/config/parser.go:59-61.

MINIFLUX-7Last login timestamp

Every successful authentication records the moment it happened against the account, whichever source authenticated it: local credentials, an API key, Basic authentication, OAuth2 or the authentication proxy.

Evidence

SetLastLogin called from internal/ui/login_check.go:80, internal/api/middleware.go:78, internal/ui/auth_proxy_middleware.go:94 and the OAuth2 callback.

1.2Browser sessions

MINIFLUX-8Session identity

A browser session is identified by a random identifier and authenticated by a separate random secret. Both are generated when the session is created, and the session exists before the visitor is authenticated so that transient state can be attached to it.

Evidence

internal/model/web_session.go:54-62 (NewWebSession), both values from crypto/rand.Text.

MINIFLUX-9Session secret storage

The database stores a SHA-256 hash of the session secret, never the secret itself. A presented secret is compared against the stored hash in constant time, so a session cookie captured from the database is not usable.

Evidence

internal/model/web_session.go: the SecretHash field, hashWebSessionSecret, and the crypto/subtle comparison.

MINIFLUX-10Session state

A session carries transient state as a JSON document alongside its identity: the CSRF token, a pending success or error message, the in-flight OAuth2 state and PKCE code verifier, in-flight WebAuthn data, the moment of the last forced refresh, and the language and theme chosen before sign-in.

Evidence

internal/model/web_session.go:36-45 (webSessionState).

MINIFLUX-11Anonymous session presentation

A session that has not been authenticated presents the interface in en_US using the system_serif theme, unless the visitor has chosen otherwise on the login page.

Evidence

internal/model/web_session.go:20-21 (defaultSessionLanguage, defaultSessionTheme).

MINIFLUX-12CSRF token requirement

A request to the web interface using any method other than GET, HEAD or OPTIONS carries the session's CSRF token, either as the form field csrf or as the header X-Csrf-Token. The submitted value is compared against the session's token in constant time, and a request without a session is refused.

Evidence

internal/ui/csrf_middleware.go:29-67.

Note

The middleware runs inside the session middleware, so the session is always present in the request context by the time it is consulted.

MINIFLUX-13CSRF failure response

A request that fails the CSRF check is answered with 400 Bad Request and the message invalid or missing CSRF. A failure on the login path is answered with a redirect to the application root instead, so that a visitor whose login form went stale is returned to a fresh one rather than shown an error.

Evidence

internal/ui/csrf_middleware.go:60-65.

MINIFLUX-14Post-login redirect

A sign-in that carried a redirect_url returns the visitor to that address only when it is a relative path. Any other value is ignored and the visitor is sent to their configured home page instead.

Evidence

internal/ui/login_check.go:86-89, using urllib.IsRelativePath.

Note

This is the open-redirect guard. IsRelativePath also rejects a value with surrounding whitespace, which is what a recent fix to internal/urllib addressed; a reimplementation that trims before checking would reopen the hole.

1.3API authentication

MINIFLUX-15API key authentication

A request to the REST API carrying the header X-Auth-Token is authenticated as the account that owns the key. A request without the header is passed on to Basic authentication rather than refused.

Evidence

internal/api/middleware.go:36-49.

MINIFLUX-16Unknown API key rejection

A request carrying an X-Auth-Token that matches no key is answered with 401 Unauthorized, and is not passed on to Basic authentication.

Evidence

internal/api/middleware.go:57-67.

MINIFLUX-17API key usage timestamp

Authenticating with an API key records the moment against that key, so a reader can tell which of an account's keys are still in use.

Evidence

internal/api/middleware.go:79 (SetAPIKeyUsedTimestamp); internal/model/api_key.go, where LastUsedAt is nullable because a key may never have been used.

MINIFLUX-18Basic authentication fallback

A request to the REST API that was not authenticated by an API key is authenticated by HTTP Basic credentials. A request with no credentials, or with an empty username or password, is answered with 401 Unauthorized and the header WWW-Authenticate: Basic realm="Restricted".

Evidence

internal/api/middleware.go:88-120.

MINIFLUX-19API cross-origin policy

Every REST API response carries Access-Control-Allow-Origin: *, permits the methods GET, POST, PUT, DELETE and OPTIONS, and permits the headers X-Auth-Token, Authorization, Content-Type and Accept. An OPTIONS request is answered with 204 No Content and a one-hour preflight cache.

Evidence

internal/api/middleware.go:23-34.

Note

The policy is unconditional and not configurable. Because the API authenticates by header or Basic credentials rather than by cookie, the wildcard origin does not by itself expose an authenticated session, but a reimplementation should not widen this to cookie authentication without revisiting it.

1.4OAuth2 and OpenID Connect

MINIFLUX-20Supported identity providers

Two OAuth2 providers are available, selected by OAUTH2_PROVIDER: google, and oidc for any OpenID Connect provider described by the discovery document at OAUTH2_OIDC_DISCOVERY_ENDPOINT. At most one is configured at a time.

Evidence

internal/oauth2/manager.go:34 (NewManager); internal/oauth2/google.go; internal/oauth2/oidc.go.

Linked Resources
OpenID Connect Discovery OPENID-CONNECT-DISCOVERY 1.0

MINIFLUX-21Authorization request protection

An authorization request carries a random state parameter and a PKCE code challenge. Both are generated per request and held in the browser session for the duration of the flow.

Evidence

internal/oauth2/authorization.go:37-45 (GenerateAuthorization, state from crypto.GenerateRandomStringHex(24)); internal/model/web_session.go (WebSessionOAuth2).

Linked Resources
OAuth 2.0 for Native Apps - PKCE OAUTH-2-0-FOR-NATIVE-APPS-PKCE RFC 7636

MINIFLUX-22Callback state validation

A callback is accepted only when its state parameter matches the value held in the session, compared in constant time. A callback with no state, an unexpected state, or no authorization code is abandoned and the visitor is redirected to the application root. The stored flow state is cleared as soon as it has been read, so a callback cannot be replayed.

Evidence

internal/ui/oauth2_callback.go:27-46; the clearing at :47-48.

Linked Resources
OAuth 2.0 for Native Apps - PKCE OAUTH-2-0-FOR-NATIVE-APPS-PKCE RFC 7636

MINIFLUX-23Account linking

A callback received while already signed in links the returned identity to the signed-in account. Linking is refused when the identity is already linked to a different account, and when the signed-in account is already linked to a different identity from the same provider. Either refusal returns the user to their settings page with an error message.

Evidence

internal/ui/oauth2_callback.go:71-107.

MINIFLUX-24Account creation on first sign-in

A callback for an identity no account holds creates an account only when OAUTH2_USER_CREATION is enabled. Otherwise the sign-in is refused. The new account takes the email address from the provider's profile as its username.

Evidence

internal/ui/oauth2_callback.go:113-120; internal/validator/user.go:176-189, whose comment explains that the username rule cannot be applied to these accounts.

MINIFLUX-25Unlinking restriction

An account cannot be unlinked from its identity provider while DISABLE_LOCAL_AUTH is enabled, because doing so would leave it with no way to sign in.

Evidence

internal/ui/oauth2_unlink.go:17.

1.5Reverse-proxy authentication

MINIFLUX-26Proxy header trust

Reverse-proxy authentication is active only when AUTH_PROXY_HEADER names a header. A request carrying that header is trusted only when the immediate peer's address falls inside TRUSTED_REVERSE_PROXY_NETWORKS; a request from any other address is passed on unauthenticated, with a warning recorded.

Evidence

internal/ui/auth_proxy_middleware.go:28-44.

Note

The address checked is the peer address, not a value read from a forwarding header, so a client cannot claim to be the proxy.

MINIFLUX-27Proxy account creation

A trusted proxy naming a username no account holds creates that account only when AUTH_PROXY_USER_CREATION is enabled. Otherwise the request is answered with 403 Forbidden. An account created this way has no password and is not an administrator.

Evidence

internal/ui/auth_proxy_middleware.go:66-83, creating the account from a UserCreationRequest carrying only the username.

MINIFLUX-28Proxy sign-in outcome

A request authenticated by the proxy establishes a browser session and is redirected to the account's configured home page, rather than being served the originally requested page.

Evidence

internal/ui/auth_proxy_middleware.go:95-101.

MINIFLUX-29Proxy header precedence

Reverse-proxy authentication is skipped entirely for a request that already carries an authenticated session, and for a request whose named header is empty. In both cases the request proceeds unchanged.

Evidence

internal/ui/auth_proxy_middleware.go:28-31 and :46-50.

2Subscriptions

2.1Feed discovery

MINIFLUX-30Discovery order

Discovery fetches the submitted address once and then tries seven steps in a fixed order, returning the first that yields any result: the response is itself a feed; the canonical address is resolved from the document; YouTube; GitHub; feed links declared in the HTML; RSS-Bridge; well-known feed paths. When no step yields anything, discovery returns no subscriptions rather than an error.

Evidence

internal/reader/subscription/finder.go:60-135 (FindSubscriptions), whose steps are numbered in the code.

MINIFLUX-31Direct feed detection

When the fetched document is itself a feed in a recognised format, that address is offered as the only subscription and the body already downloaded is reused, so subscribing does not fetch the same document twice.

Evidence

internal/reader/subscription/finder.go:66-71; the retained body at :61-65 and IsFeedAlreadyDownloaded at :36.

MINIFLUX-32Canonical address resolution

Before the site-specific steps run, the address is replaced by the one declared in the document's link rel="canonical" element when there is one. The subsequent steps see the canonical address, so a site reached through an alias is recognised.

Evidence

internal/reader/subscription/finder.go:78-80 and findCanonicalURL at :394; the element matcher is case-insensitive.

MINIFLUX-33YouTube channel discovery

An address on a youtube.com host whose path contains channel/UC yields four subscriptions built from the channel identifier: the channel feed itself, and the three playlist feeds for videos, short videos and live streams. None of these is fetched to confirm it exists.

Evidence

internal/reader/subscription/finder.go:301-333; the playlist prefixes UULF, UUSH and UULV replace the leading UC of the channel identifier.

MINIFLUX-34YouTube playlist discovery

An address on a youtube.com host whose path begins /watch or /playlist and which carries a list query parameter yields a single subscription to that playlist's feed.

Evidence

internal/reader/subscription/finder.go:334-341.

MINIFLUX-35YouTube host matching

The YouTube step applies to any host whose name ends in youtube.com, and is skipped for every other host.

Evidence

internal/reader/subscription/finder.go:316-319, a suffix test rather than an equality test.

Note

A suffix test also matches a host such as notyoutube.com. The consequence is limited - the step only constructs addresses under www.youtube.com from the path, so a look-alike host yields feeds pointing at the real YouTube - but it is a difference from the GitHub step below, which compares the host exactly.

MINIFLUX-36GitHub profile discovery

An address on github.com or www.github.com whose path is a single segment yields one subscription to that user or organisation's activity feed, at the profile address with .atom appended.

Evidence

internal/reader/subscription/finder.go:369-374.

Note

The function's comment records why this step exists: GitHub does not advertise these feeds in the HTML of its pages, so the ordinary declared-link step would not find them.

MINIFLUX-37GitHub repository discovery

An address on GitHub whose path is exactly two segments yields three subscriptions for that repository: commits, releases and tags. A path of three or more segments, and the GitHub root itself, yield nothing.

Evidence

internal/reader/subscription/finder.go:375-390.

MINIFLUX-38Declared feed links

Feeds declared in the document's head are offered as subscriptions, resolved against the document's base address so that a relative declaration becomes absolute.

Evidence

internal/reader/subscription/finder.go:136-194 (findSubscriptionsFromWebPage); the base address from getBaseURL at :413.

MINIFLUX-39Well-known feed paths

As a last resort, nine conventional paths are probed - atom.xml, feed.atom, feed.xml, feed/, index.rss, index.xml, rss.xml, rss/ and rss/feed.xml - relative to the site root and, when the submitted address was deeper, relative to its directory as well.

Evidence

internal/reader/subscription/finder.go:195-235.

MINIFLUX-40Well-known path redirect handling

Each well-known path is probed with redirects disabled, so a site that answers unknown addresses with a redirect to its home page does not cause all nine paths to be offered as valid feeds. Redirects remain enabled for every other request the finder makes.

Evidence

internal/reader/subscription/finder.go:228-235, which clones the request builder rather than modifying the shared one; the reason is recorded in the code comment.

MINIFLUX-41RSS-Bridge discovery

When an RSS-Bridge instance is configured, a site for which no feed was found is offered to that instance, and any bridge it reports is offered as a subscription. The step is skipped entirely when no instance is configured.

Evidence

internal/reader/subscription/finder.go:114-124 and findSubscriptionsFromRSSBridge at :266.

MINIFLUX-42Discovery body limit

The document discovery reads is truncated at the configured maximum response size, the same limit that applies to a feed fetch.

Evidence

internal/reader/subscription/finder.go:53, reading with config.Opts.HTTPClientMaxBodySize().

2.2Creating and editing a feed

MINIFLUX-43Mandatory feed fields

Creating a feed requires a feed address and a category. A request missing either is refused with error.feed_mandatory_fields.

Evidence

internal/validator/feed.go:17-19.

MINIFLUX-44Feed address form

A feed address is an absolute URL. A relative or otherwise non-absolute value is refused with error.invalid_feed_url.

Evidence

internal/validator/feed.go:21-23, using urllib.IsAbsoluteURL.

MINIFLUX-45Duplicate feed prevention

An account cannot subscribe twice to the same feed address. A second attempt is refused with error.feed_already_exists. The address is compared exactly; two addresses that differ only in case or trailing slash are treated as different feeds.

Evidence

internal/validator/feed.go:25-27 (FeedURLExists).

MINIFLUX-46Feed category ownership

The category a feed is placed in belongs to the same account. A category that does not exist, or belongs to another account, is refused with error.feed_category_not_found.

Evidence

internal/validator/feed.go:29-47 (CategoryIDExists is scoped by user).

Note

A comment in this function records a known shortcoming: the validation type cannot carry an underlying error, so a database failure while checking the category is reported to the user as "category not found". The failure is written to the log to keep it observable. A reimplementation should distinguish the two.

MINIFLUX-47Feed regex rule validation

The blocklist and keeplist expressions on a feed are compiled when the feed is created or changed. An expression that does not compile is refused with error.feed_invalid_blocklist_rule or error.feed_invalid_keeplist_rule, so an invalid expression is never stored.

Evidence

internal/validator/feed.go:49-55 (IsValidRegex).

Note

This is validation at the boundary only. An expression stored before the check existed, or reaching the feed by another route, is ignored at filtering time rather than refused - see the entry-filtering requirements.

Linked Resources
RE2 Syntax RE2-SYNTAX Go regexp/syntax

MINIFLUX-48Feed filter rule validation

The block and keep filter rules on a feed are checked when they are not empty, and a malformed rule is refused. Block and keep rules are checked against their own kind, so a rule valid in one list is not automatically valid in the other.

Evidence

internal/validator/feed.go:57-64, calling IsValidFilterRules with "block" and "keep".

2.3Categories

MINIFLUX-49Category title requirement

A category has a non-empty title. Creating or renaming a category with an empty title is refused with error.title_required.

Evidence

internal/validator/category.go:14-16 and :29-31.

MINIFLUX-50Category title uniqueness

A category title is unique within an account. Creating a category whose title an existing one holds, or renaming a category onto another's title, is refused with error.category_already_exists.

Evidence

internal/validator/category.go:18-20 and :33-35; renaming uses AnotherCategoryExists, so a category may be saved under its own unchanged title.

MINIFLUX-51Category modification scope

A category modification carrying no title leaves the title unchanged and is not refused, so a request that changes only another attribute does not have to restate it.

Evidence

internal/validator/category.go:28, where the title is a pointer and the checks run only when it is set.

2.4OPML import and export

MINIFLUX-52Export contents

An OPML export lists every feed of the account with its title, feed address, site address and description, grouped by category. It also carries the account's per-feed settings as Miniflux-specific attributes: the scraper, rewrite, URL-rewrite, blocklist, keeplist and filter rules, the user agent, and the crawler, cache, proxy, disabled, media-player, hidden, self-signed-certificate, HTTP/2 and entry-update flags.

Evidence

internal/reader/opml/handler.go:21-56; the attribute names in internal/reader/opml/opml.go:58-75.

Note

Credentials are deliberately not exported: a feed's username, password and cookie are absent from the list above, so an export can be shared without leaking them. An import therefore cannot restore them.

Linked Resources
OPML 2.0 Specification OPML-2-0-SPECIFICATION 2.0

MINIFLUX-53Import duplicate handling

An import skips any entry whose feed address the account is already subscribed to, leaving the existing subscription and its settings untouched. Import therefore adds feeds but never updates them.

Evidence

internal/reader/opml/handler.go:66-68.

Linked Resources
OPML 2.0 Specification OPML-2-0-SPECIFICATION 2.0

MINIFLUX-54Import category resolution

An imported feed is placed in the category named in the document, creating that category when the account does not have it. An entry that names no category is placed in the account's first category.

Evidence

internal/reader/opml/handler.go:97-122 (resolveCategory).

MINIFLUX-55Import without a category

An import of an entry that names no category into an account that has no categories at all fails with ErrNoCategory rather than creating one.

Evidence

internal/reader/opml/handler.go:103-106.

Note

This path is the subject of a recent fix - commit a7f93d8b, "avoid panic when creating a feed without any category" - so the error return above replaced a crash. A reimplementation must decide deliberately whether an account can exist with no categories at all.

MINIFLUX-56Import validation

Each imported entry is validated exactly as a feed creation request is, so the address form, duplicate, category and rule checks all apply. An entry that fails validation aborts the import with a message naming the offending feed address.

Evidence

internal/reader/opml/handler.go:75-78 and validateSubscription at :144-173, which builds a FeedCreationRequest and calls validator.ValidateFeedCreation.

MINIFLUX-57Import atomicity

An import is not a single transaction. Feeds are created one at a time as the document is read, so a failure part-way through leaves the feeds already created in place and does not import the remainder.

Evidence

internal/reader/opml/handler.go:60-95: the loop returns on the first error, after earlier iterations have already called CreateFeed.

Note

Recorded because it is the kind of behaviour a reimplementation is likely to change by accident in either direction. Whether the partial import is intended is not stated anywhere in the repository.

3Refresh scheduling

3.1Choosing the next check

MINIFLUX-58Scheduler selection

One of two schedulers decides when a feed is next checked, chosen for the whole installation by POLLING_SCHEDULER: round_robin, the default, or entry_frequency. The choice is not per feed and not per account.

Evidence

internal/model/feed.go:14-17; internal/model/feed.go:122-150 (ScheduleNextCheck); internal/config/options.go, key POLLING_SCHEDULER.

MINIFLUX-59Round-robin interval

Under the round-robin scheduler every feed is given the same base interval, SCHEDULER_ROUND_ROBIN_MIN_INTERVAL, which is 60 minutes by default. The feed's own history does not affect it.

Evidence

internal/model/feed.go:125; the default at internal/config/options.go, key SCHEDULER_ROUND_ROBIN_MIN_INTERVAL.

MINIFLUX-60Entry-frequency interval

Under the entry-frequency scheduler the base interval is one week divided by the feed's entry count over the past week multiplied by SCHEDULER_ENTRY_FREQUENCY_FACTOR. A feed that published nothing in the past week is given the maximum interval instead of a division.

Evidence

internal/model/feed.go:127-136.

Example

A feed publishing 14 entries a week, with the factor at its default of 1, is given a base interval of 7 days / 14, or 12 hours.

MINIFLUX-61Entry-frequency floor

The interval the entry-frequency scheduler computes is never shorter than SCHEDULER_ENTRY_FREQUENCY_MIN_INTERVAL, five minutes by default, so a very busy feed cannot be polled arbitrarily often.

Evidence

internal/model/feed.go:134.

MINIFLUX-62Entry-frequency ceiling

The interval the entry-frequency scheduler computes is never longer than SCHEDULER_ENTRY_FREQUENCY_MAX_INTERVAL, 24 hours by default.

Evidence

internal/model/feed.go:133, and again at :146 after the publisher-requested delay has been applied.

MINIFLUX-63Publisher-requested delay

A delay the publisher asks for raises the interval: the scheduled interval is never shorter than the largest of the feed's own TTL, the response's Cache-Control maximum age, and its Expires header. A publisher can therefore slow polling down but never speed it up.

Evidence

internal/reader/handler/handler.go:305-309, which takes the maximum of the three; applied as a floor at internal/model/feed.go:139.

MINIFLUX-64Misconfigured feed ceiling

After the publisher-requested delay has been applied, the interval is capped again at the active scheduler's maximum - SCHEDULER_ROUND_ROBIN_MAX_INTERVAL or SCHEDULER_ENTRY_FREQUENCY_MAX_INTERVAL, both 24 hours by default - so a feed advertising an implausible TTL is still checked daily.

Evidence

internal/model/feed.go:141-147; the code comment names the case as "misconfigured feeds".

MINIFLUX-65Rate-limit backoff

A response that reports rate limiting reschedules the feed using the delay the server asked for, before the response body is considered. The rescheduling happens whether or not the rest of the refresh succeeds.

Evidence

internal/reader/handler/handler.go:254-265, using ParseRetryDelay and re-running ScheduleNextCheck.

MINIFLUX-66Provisional scheduling

A feed's next check is set before its refresh is attempted, using a delay of zero, and set again once the response is known. A refresh that fails outright therefore still leaves the feed with a next check in the future rather than looping immediately.

Evidence

internal/reader/handler/handler.go:230, the first call to ScheduleNextCheck.

3.2Selecting the batch

MINIFLUX-67Polling cycle

A background scheduler builds one batch of feeds to refresh every POLLING_FREQUENCY, 60 minutes by default, and hands it to the worker pool. A cycle that finds no due feeds pushes nothing.

Evidence

internal/cli/scheduler.go:32-50 (feedScheduler).

MINIFLUX-68Batch eligibility

A feed enters the batch when its next check is in the past, it is not disabled, and its consecutive parsing-error count is below POLLING_PARSING_ERROR_LIMIT. All three conditions apply together.

Evidence

internal/cli/scheduler.go:35-40; the conditions in internal/storage/batch.go:46-63.

MINIFLUX-69Batch ordering

Feeds are taken in order of how overdue they are, oldest next check first, so a feed that has been waiting longest is refreshed first.

Evidence

internal/storage/batch.go:82, ORDER BY next_check_at ASC.

MINIFLUX-70Batch size

A batch holds at most BATCH_SIZE feeds, 100 by default. Feeds beyond that stay due and are picked up by a later cycle.

Evidence

internal/storage/batch.go:84-86; the default and its lower bound of 1 at internal/config/options.go:103-133.

MINIFLUX-71Per-host batch limit

When POLLING_LIMIT_PER_HOST is greater than zero, a batch carries at most that many feeds from any one hostname. Feeds over the limit are dropped from this batch rather than deferred, and are reconsidered on the next cycle. The limit is disabled by default.

Evidence

internal/storage/batch.go:98-119; the counting is applied to the rows already limited by batch size.

Note

Because the per-host limit is applied after the query's LIMIT, a batch can come back smaller than BATCH_SIZE even when more eligible feeds exist. The log line at :126-131 records the rows read, the feeds skipped and the jobs produced separately, which suggests the difference is understood rather than accidental.

MINIFLUX-72Worker pool size

Refresh jobs are executed by a fixed pool of WORKER_POOL_SIZE workers, 16 by default, created at start-up and living for the lifetime of the process.

Evidence

internal/worker/pool.go (NewPool); the default at internal/config/options.go, key WORKER_POOL_SIZE.

MINIFLUX-73Job queue handover

The queue between the scheduler and the workers is unbuffered, so pushing a batch blocks until a worker takes each job. A cycle that produces more jobs than the workers can absorb holds the scheduler rather than accumulating a backlog in memory.

Evidence

internal/worker/pool.go: queue: make(chan model.Job), with no capacity.

MINIFLUX-74Shutdown behaviour

Shutting the pool down stops it accepting new jobs and waits for the jobs already in progress to finish. Jobs pushed after shutdown are discarded rather than blocking the caller.

Evidence

internal/worker/pool.go (Shutdown, Push); asserted by TestPushAfterShutdownDiscardsJobs in internal/worker/pool_test.go, which fails the test if Push has not returned within five seconds.

MINIFLUX-75Scheduler service switch

Setting DISABLE_SCHEDULER_SERVICE stops the background scheduler from running at all. Feeds are then refreshed only on demand, through the interface, the API, or the command line.

Evidence

internal/config/options.go, key DISABLE_SCHEDULER_SERVICE; consulted in internal/cli/daemon.go.

3.3Refreshing a feed

MINIFLUX-76Conditional request

A refresh sends the entity tag and last-modified value recorded at the previous fetch, so an unchanged feed can be answered without a body. The values are omitted when the feed has HTTP caching turned off, and when the refresh was forced.

Evidence

internal/reader/handler/handler.go:244-249.

Linked Resources
RFC 9111 - HTTP Caching RFC-9111-HTTP-CACHING RFC 9111

MINIFLUX-77Unmodified response handling

A feed the server reports as unmodified is not parsed and its entries are not touched. Its last-modified value is still updated when the response carried one, because that value can change while the entity tag does not.

Evidence

internal/reader/handler/handler.go:359-372; the code cites RFC 9111 sections 3.2 and 4.3.4 as the reason.

Linked Resources
RFC 9111 - HTTP Caching RFC-9111-HTTP-CACHING RFC 9111

MINIFLUX-78Redirect to an existing feed

A refresh whose final address is already the address of another feed in the same account fails with error.duplicated_feed rather than creating a duplicate or silently merging the two.

Evidence

internal/reader/handler/handler.go:275-278 (AnotherFeedURLExists against the effective address).

MINIFLUX-79Existing entry updates

A refresh updates entries it has seen before only when neither the crawler nor the ignore-entry-updates setting is on for that feed. A forced refresh updates them regardless.

Evidence

internal/reader/handler/handler.go:334-336; the reasoning is in the code comment - with the crawler on, only entries not already present are crawled.

MINIFLUX-80Feed metadata refresh

A successful refresh replaces the feed's stored entity tag, last-modified value, language and icon address with those from the response.

Evidence

internal/reader/handler/handler.go:350-354.

MINIFLUX-81Icon refresh policy

An ordinary refresh fetches the feed's icon only when the feed has none. A forced refresh fetches it again and replaces the stored one, which is how a changed site icon is picked up.

Evidence

internal/reader/handler/handler.go:355-360: UpdateOrCreateFeedIcon when forced, CreateFeedIconIfMissing otherwise.

MINIFLUX-82Integration dispatch

Entries that are new in a refresh are handed to the account's configured integrations, in the background, after they have been stored. A refresh that produced no new entries dispatches nothing.

Evidence

internal/reader/handler/handler.go:341-349; the dispatch is a goroutine, so the refresh does not wait for it.

MINIFLUX-83Integration failure isolation

A failure to read the account's integration settings is recorded and the refresh continues without running any integration. It does not fail the refresh.

Evidence

internal/reader/handler/handler.go:342-347; the log message states the intent explicitly.

MINIFLUX-84Error recording

A refresh that fails records the reason against the feed, translated into the owning account's language, and increments the feed's consecutive error count. The message is what the interface shows next to the feed.

Evidence

internal/reader/handler/handler.go:29-37 (getTranslatedLocalizedError), called from every failure path in RefreshFeed.

MINIFLUX-85Error counter reset

A refresh that completes without error clears the feed's error count and its recorded error message, so a feed that recovers returns to the batch immediately rather than after a delay.

Evidence

internal/reader/handler/handler.go:374 (ResetErrorCounter); internal/model/feed.go:105-111.

MINIFLUX-86Repeated failure exclusion

A feed whose consecutive error count reaches POLLING_PARSING_ERROR_LIMIT, three by default, stops being included in scheduled batches. It is not disabled, and an on-demand refresh still runs and can clear the count.

Evidence

internal/storage/batch.go:46-52 (WithErrorLimit), used only by the scheduled path in internal/cli/scheduler.go:39.

Note

Setting the limit to zero or less removes the condition entirely rather than excluding every feed, because WithErrorLimit adds no condition unless the limit is positive.

MINIFLUX-87Feed refresh site address fallback

A feed that declares no site address takes its feed address as its site address the first time it is checked.

Evidence

internal/model/feed.go:114-120 (CheckedNow).

3.4Refreshing on demand

MINIFLUX-88Forced refresh rate limit

A visitor may force a refresh of all their feeds at most once every FORCE_REFRESH_INTERVAL, 30 minutes by default. A second attempt inside that window is refused with a message naming the interval in minutes. The limit is held against the browser session.

Evidence

internal/ui/category_refresh.go:33-35 and :60; the session field at internal/model/web_session.go:43.

Note

Because the timestamp lives in the browser session rather than against the account, the limit is per session: signing in from a second browser gives a fresh allowance.

MINIFLUX-89Forced refresh effects

A forced refresh ignores the stored entity tag and last-modified value, updates entries that already exist, and fetches the feed icon again. An ordinary scheduled refresh does none of those three.

Evidence

internal/reader/handler/handler.go:244, :334 and :355-359, all keyed off the same forceRefresh argument.

4Fetching over HTTP

4.1Request construction

MINIFLUX-90Request method

Every outgoing fetch is a GET. Conditional fetching is done with request headers rather than with HEAD.

Evidence

internal/reader/fetcher/request_builder.go:260.

MINIFLUX-91Accept header

A request that does not already carry an Accept header is given one advertising the feed formats ahead of HTML: application/xml, application/atom+xml, application/rss+xml, application/rdf+xml, application/feed+json, text/html, then anything else at a lower preference.

Evidence

internal/reader/fetcher/request_builder.go:27 and :274-277.

Note

The header is only defaulted, never overwritten. The code comment gives the reason: a media proxy request forwards the browser's own Accept header and must keep it.

MINIFLUX-92Compression negotiation

A request advertises support for Brotli and gzip. A request made with compression disabled advertises identity instead.

Evidence

internal/reader/fetcher/request_builder.go:267-272; the decoders at response_handler.go:144-150.

MINIFLUX-93Connection handling

Every request asks the server to close the connection afterwards, so connections are not pooled across fetches.

Evidence

internal/reader/fetcher/request_builder.go:279.

MINIFLUX-94User agent selection

A request carries the feed's own user agent when one is set, and otherwise the installation-wide HTTP_CLIENT_USER_AGENT. Both are sent verbatim.

Evidence

internal/reader/fetcher/request_builder.go:81-88.

Note

The manual page states that when HTTP_CLIENT_USER_AGENT is empty "Miniflux uses a default User-Agent that includes" the version. The builder itself simply sets whatever string it is given, so that default is composed by the caller rather than here; a reimplementation should locate it deliberately rather than assume the builder supplies one.

Linked Resources
Miniflux Manual Page MINIFLUX-MANUAL-PAGE miniflux.1 in this repository

MINIFLUX-95Feed credentials

A feed with both a username and a password is fetched with HTTP Basic credentials. A feed with only one of the two is fetched without credentials rather than with an empty half.

Evidence

internal/reader/fetcher/request_builder.go:96-101, which requires both to be non-empty.

MINIFLUX-96Feed cookies

A feed configured with a cookie string sends it as the request's Cookie header, unparsed. This is how a feed behind a login wall is reached.

Evidence

internal/reader/fetcher/request_builder.go:90-95.

MINIFLUX-97Conditional request headers

A stored entity tag is sent as If-None-Match and a stored last-modified value as If-Modified-Since. An empty stored value sends no header at all rather than an empty one.

Evidence

internal/reader/fetcher/request_builder.go:68-80.

Linked Resources
RFC 9111 - HTTP Caching RFC-9111-HTTP-CACHING RFC 9111

MINIFLUX-98Request builder isolation

A request builder can be copied, and changing the copy - disabling redirects for one probe, for instance - leaves the original unchanged, headers included.

Evidence

internal/reader/fetcher/request_builder.go:55-62 (Clone), which clones the header map rather than sharing it.

4.2Limits and timeouts

MINIFLUX-99Request timeout

A fetch is abandoned after HTTP_CLIENT_TIMEOUT, 20 seconds by default. The timeout covers the whole exchange, not just the connection.

Evidence

internal/reader/fetcher/request_builder.go:26 and :249-251, set as the HTTP client's Timeout.

MINIFLUX-100Connection timeouts

Establishing a connection is abandoned after 10 seconds, and an idle keep-alive is held for 15 seconds. Idle pooled connections are closed after 10 seconds and at most 50 are kept. None of these four values is configurable.

Evidence

internal/reader/fetcher/request_builder.go:168-176 and :201-206; each carries a comment naming the Go default it replaces.

MINIFLUX-101Response size limit

A response body is read up to HTTP_CLIENT_MAX_BODY_SIZE, 15 MiB by default. Exceeding it fails the fetch with error.http_response_too_large rather than truncating the document, so a partially read feed is never parsed.

Evidence

internal/reader/fetcher/response_handler.go:156-166.

MINIFLUX-102Empty response rejection

A response whose body is empty fails the fetch with error.http_empty_response_body. A declared content length of zero is treated the same way, except on a not-modified response, where an empty body is expected.

Evidence

internal/reader/fetcher/response_handler.go:168-172 and :220-226; the code notes that a missing Content-Length header reads as -1, not 0.

4.3Network restrictions

MINIFLUX-103Private network refusal

A fetch whose resolved address is not a public one is refused before the connection is opened, and fails with refusing to access private network host. Setting FETCHER_ALLOW_PRIVATE_NETWORKS to 1 lifts the restriction; it is off by default, so private addresses are refused.

Evidence

internal/reader/fetcher/request_builder.go:184-199; asserted by the tests at request_builder_test.go:429 and :448.

Note

The check runs in the dialer's Control callback, after name resolution and immediately before the connection is made, so the address checked is the address connected to. The code comment states this is deliberate, to close DNS-rebinding and time-of-check/time-of-use holes. An implementation that checked the hostname, or resolved separately from connecting, would not have this property.

MINIFLUX-104Redirect target restriction

The private-address restriction applies to the target of every redirect as well as to the address first requested, so a public address cannot redirect a fetch onto the internal network.

Evidence

Asserted by the test at internal/reader/fetcher/request_builder_test.go:538-560, which redirects to a loopback server and expects the refusal.

MINIFLUX-105Proxy exemption

An explicitly configured proxy is a trusted hop: the connection to the proxy itself is permitted even when it is on a private address, while direct connections and redirect targets remain restricted.

Evidence

internal/reader/fetcher/request_builder.go:208-221; the exemption is matched on the normalised proxy address only.

MINIFLUX-106Proxy address normalisation

A proxy address is matched with its host lowercased and its port made explicit, defaulting to 80 for http, 443 for https and 1080 for socks5 and socks5h. A proxy using any other scheme is not matched, and so is not exempted.

Evidence

internal/reader/fetcher/request_builder.go:305-324 (normalizeProxyDialAddress).

MINIFLUX-107Integration network restriction

Requests made by third-party integrations are governed by their own setting, INTEGRATION_ALLOW_PRIVATE_NETWORKS, which is also off by default. Allowing private addresses for feed fetching does not allow them for integrations.

Evidence

internal/config/options.go, key INTEGRATION_ALLOW_PRIVATE_NETWORKS, separate from FETCHER_ALLOW_PRIVATE_NETWORKS.

4.4Proxies

MINIFLUX-108Proxy precedence

At most one proxy is used per request, chosen in a fixed order: the feed's own proxy address if it has one; otherwise the installation proxy, but only for a feed marked to use it; otherwise the next proxy from the rotation pool when one is configured. A request matching none of the three goes direct.

Evidence

internal/reader/fetcher/request_builder.go:147-165, a switch whose cases are evaluated in that order.

MINIFLUX-109Invalid feed proxy handling

A feed whose own proxy address cannot be parsed fails the fetch, naming the offending address. It does not fall back to the installation proxy or to a direct connection.

Evidence

internal/reader/fetcher/request_builder.go:149-154.

MINIFLUX-110Proxy rotation

When HTTP_CLIENT_PROXIES lists several proxies, requests are distributed across them strictly in turn, cycling back to the first after the last. The position is shared across all concurrent fetches.

Evidence

internal/proxyrotator/proxyrotator.go (GetNextProxy), advancing a single index under a mutex.

Note

Rotation is round-robin by request, not by host or by feed, so successive requests to the same site normally come from different proxies.

MINIFLUX-111Proxy credential redaction

A proxy address written to the log has its credentials removed, so a proxy configured with a username and password does not leak them into the log.

Evidence

internal/reader/fetcher/request_builder.go:243-247, using URL.Redacted.

MINIFLUX-112Environment proxy

When no proxy is chosen for the request, the transport still honours the proxy environment variables of the process.

Evidence

internal/reader/fetcher/request_builder.go:201-203, Proxy: http.ProxyFromEnvironment, replaced only when a proxy was chosen.

4.5Transport options

MINIFLUX-113HTTP/2 negotiation

HTTP/2 is attempted by default. A feed marked to disable it is fetched over HTTP/1.1, which is offered as a way to change the client's network fingerprint.

Evidence

internal/reader/fetcher/request_builder.go:204 and :236-241; README, "Bot Protection Bypass Mechanisms".

Note

The code comment records why ForceAttemptHTTP2 has to be set explicitly: supplying a custom DialContext otherwise disables HTTP/2 silently.

MINIFLUX-114Self-signed certificate acceptance

A feed marked to allow self-signed certificates is fetched with certificate verification turned off, and additionally offers the insecure cipher suites, so that a badly configured server can still be reached. The setting is per feed; there is no installation-wide equivalent.

Evidence

internal/reader/fetcher/request_builder.go:222-235; the reason for widening the cipher list is in the code comment.

MINIFLUX-115Redirect following

Redirects are followed by default, and the address finally reached is what the refresh treats as the feed's effective address. A request made with redirects disabled returns the redirect response itself instead.

Evidence

internal/reader/fetcher/request_builder.go:253-258; EffectiveURL at response_handler.go:32.

4.6Interpreting the response

MINIFLUX-116Modification detection

A response is treated as unmodified when its status says so. Otherwise, when it carries an entity tag, the tag decides; when it carries no tag but a last-modified value, that decides; and a response carrying neither is always treated as modified.

Evidence

internal/reader/fetcher/response_handler.go:102-116 (IsModified).

Linked Resources
RFC 9111 - HTTP Caching RFC-9111-HTTP-CACHING RFC 9111

MINIFLUX-117Recognised redirect statuses

The statuses treated as redirects are 301, 302, 303, 307 and 308.

Evidence

internal/reader/fetcher/response_handler.go:118-125.

MINIFLUX-118Rate-limit detection

A response with status 429 is treated as rate limiting, and the delay is read from the response rather than assumed.

Evidence

internal/reader/fetcher/response_handler.go:98-100 and ParseRetryDelay at :82.

MINIFLUX-119Cloudflare challenge detection

A response is reported as a Cloudflare challenge, rather than as an ordinary refusal, when all three of the following hold: the status is 403, the header cf-mitigated equals challenge ignoring case, and the content type begins text/html.

Evidence

internal/reader/fetcher/response_handler.go:231-243.

Note

The check reads headers only. The code comment gives the reason: it must be cheap and must run before the body is read, since reading the body is what the size limit governs.

MINIFLUX-120Status-specific failures

Nine statuses produce their own message rather than a generic one: 401, 403, 404, 410, 429, 500, 502, 503 and 504. Any other status of 400 or above produces a message naming the status code.

Evidence

internal/reader/fetcher/response_handler.go:196-218; 404 and 410 share the same message.

MINIFLUX-121Transport failure classification

A failure with no response is classified before it is reported: a certificate problem, a network operation failure, a timeout, and an unexpected end of stream each produce their own message, and anything else produces a generic client error.

Evidence

internal/reader/fetcher/response_handler.go:176-190, with isSSLError and isNetworkError at :245-270.

Note

The cases are evaluated in order and an unexpected end of stream is also a network error, so it is reported as error.network_operation rather than as error.http_empty_response. The later case is unreachable for that input.

5Parsing feeds

5.1Format detection

MINIFLUX-122Supported feed formats

Four feed formats are parsed: Atom, RSS, RDF and JSON Feed. A document in any other form is rejected with parser: unable to detect feed format, reported to the account as error.feed_format_not_detected.

Evidence

internal/reader/parser/parser.go:20-33; the distinct error message at internal/reader/handler/handler.go:296-301.

MINIFLUX-123Format detection by content

The format is decided from the document's own bytes, not from its content type or its file name. JSON is tested first, and the document is then read as XML.

Evidence

internal/reader/parser/format.go:27-63 (DetectFeedFormat).

MINIFLUX-124JSON detection

A document is treated as JSON when its first non-whitespace character opens a JSON value. Leading whitespace is skipped, and an empty document is not JSON.

Evidence

internal/reader/parser/format.go:65-90 (detectJSONFormat), reading in 32-byte chunks.

MINIFLUX-125XML root element detection

An XML document is identified by its first recognised root element: rss is RSS, RDF is RDF, and feed is Atom. The element name is matched without regard to its namespace.

Evidence

internal/reader/parser/format.go:44-58, switching on element.Name.Local.

Linked Resources
RSS 2.0 Specification RSS-2-0-SPECIFICATION 2.0

MINIFLUX-126Atom version detection

An Atom document declaring version="0.3" on its root element is parsed as Atom 0.3. Every other Atom document is parsed as Atom 1.0.

Evidence

internal/reader/parser/format.go:48-55.

Linked Resources
RFC 4287 - The Atom Syndication Format RFC-4287-THE-ATOM-SYNDICATION-FORMAT RFC 4287

MINIFLUX-127Detection token budget

Detection gives up after 50 XML tokens. A document whose recognisable root element appears later than that is reported as an unknown format.

Evidence

internal/reader/parser/format.go:24 (maxTokensToConsider) and :38-42.

Note

The budget bounds the work done on a hostile or malformed document. It also means a feed preceded by a long run of comments or processing instructions is not recognised; no test in the repository covers that boundary.

MINIFLUX-128Detection leaves the document readable

Detection rewinds the document before and after it reads, so the same bytes can then be parsed without being fetched again.

Evidence

internal/reader/parser/format.go:28-29, a seek to the start and a deferred seek back.

5.2Character encoding

MINIFLUX-129Declared encoding conversion

A document that declares an encoding other than UTF-8 is converted to UTF-8 before it is parsed, using the declared label.

Evidence

internal/reader/encoding/encoding.go:25-41 (CharsetReader), wired in at internal/reader/xml/decoder.go:38.

MINIFLUX-130Wrongly declared encoding

A document whose bytes are already valid UTF-8 is used as-is, whatever encoding it declares. A feed that declares the wrong encoding is therefore read correctly rather than being double-converted into mojibake.

Evidence

internal/reader/encoding/encoding.go:33-37; the doc comment enumerates the four cases this handles.

Example

The test corpus carries this case directly: internal/reader/encoding/testdata/utf8-incorrect-prolog.xml and windows-1252-incorrect-prolog.xml.

MINIFLUX-131Illegal XML character removal

Characters that XML does not permit are removed from the document before it is parsed, rather than causing the parse to fail. Bytes that are not valid UTF-8 are dropped along with them.

Evidence

internal/reader/xml/decoder.go:61-82 (filterValidXMLChars), applied on both the UTF-8 and the converted paths.

Note

The two paths exist because Go's XML decoder does not call the charset reader for content already declared as UTF-8, so that case has to be filtered separately. A TODO at decoder.go:24-26 records that the UTF-8 path does not sniff the actual encoding from the bytes and simply expects invalid characters to be stripped.

MINIFLUX-132Lenient XML parsing

XML is parsed in non-strict mode with the HTML entity table loaded, so a feed using HTML named entities or minor well-formedness violations is still read.

Evidence

internal/reader/xml/decoder.go:41-42.

5.3Dates

MINIFLUX-133Date format coverage

A publication date is matched against a long list of formats found in real feeds, tried in order, and the first that parses wins. A value that matches none of them fails with a message quoting the value.

Evidence

internal/reader/date/parser.go:320-345; the lists at :15-19 and :22 onwards, the latter noted in the code as taken from github.com/mjibson/goread.

MINIFLUX-134Numeric dates

A date that is entirely digits is read as a Unix timestamp in seconds, before any textual format is tried.

Evidence

internal/reader/date/parser.go:326-328.

MINIFLUX-135Date text normalisation

Common misspellings in feed dates are corrected before parsing - abbreviated and non-English month names, and the day abbreviations Thurs and Thur - so that a feed with a slightly wrong date string is still read.

Evidence

internal/reader/date/parser.go:305-313 (the replacer), applied at :330.

MINIFLUX-136Ambiguous timezone abbreviations

A date ending in PST or PDT is read in the America/Los_Angeles zone, and one ending in EST or EDT in America/New_York. Every other local-time format is read as UTC.

Evidence

internal/reader/date/parser.go:349-360 (parseLocalTimeDates).

Note

These four abbreviations are ambiguous worldwide; the choice of the two American zones is a decision the code takes without recording a reason. The preceding comment explains only why the RFC 822, 850 and 1123 layouts are handled separately from the others.

MINIFLUX-137Timezone range check

A parsed date whose zone offset is outside the range real zones use is corrected rather than stored, so a malformed offset does not place an entry far outside its true time.

Evidence

internal/reader/date/parser.go, checkTimezoneRange, applied to the result of both format lists.

MINIFLUX-138Empty date handling

An empty or whitespace-only date fails with date parser: empty value rather than yielding the zero time.

Evidence

internal/reader/date/parser.go:321-324.

5.4Mapping an item onto an entry

MINIFLUX-139Entry address resolution

An entry's address is resolved against the feed's site address, so a relative link in a feed becomes absolute. A link that cannot be resolved is kept as it was given.

Evidence

internal/reader/rss/adapter.go:91-97.

MINIFLUX-140Entry address fallback

An item with no link of its own takes the feed's site address, and then the address of its first enclosure when it has one. An entry therefore always has an address.

Evidence

internal/reader/rss/adapter.go:99-107.

MINIFLUX-141Entry title fallback

An item with no title takes the first 100 characters of its content with markup removed, and takes its own address when that too is empty. An entry therefore always has a title.

Evidence

internal/reader/rss/adapter.go:110-116.

MINIFLUX-142Entry author fallback

An item with no author of its own takes the feed's author.

Evidence

internal/reader/rss/adapter.go:118-121.

MINIFLUX-143Entry language fallback

An entry takes its language from its own Dublin Core language element, normalised, and falls back to the feed's language. The comment in the code gives the reason: items belong to the channel's content.

Evidence

internal/reader/rss/adapter.go:123-128.

MINIFLUX-144Entry tag fallback

An item with no categories of its own takes the feed's categories as its tags.

Evidence

internal/reader/rss/adapter.go:167-171.

MINIFLUX-145Comments address

An item's comments address is kept only when it is an absolute address. A relative one is discarded rather than resolved.

Evidence

internal/reader/rss/adapter.go:154-157.

Note

This differs from the entry address, which is resolved against the site address rather than discarded. Whether the asymmetry is deliberate is not recorded.

MINIFLUX-146Podcast duration

An item carrying an iTunes duration takes that value, in minutes, as its reading time, instead of having one estimated from its text.

Evidence

internal/reader/rss/adapter.go:159-165.

5.5Entry identity

MINIFLUX-147Identity from the item identifier

An entry's identity is the SHA-256 hash of the item's own identifier when it has one. This is what lets a changed item be recognised as the same entry across refreshes.

Evidence

internal/reader/rss/adapter.go:137-149.

Linked Resources
RSS 2.0 Specification RSS-2-0-SPECIFICATION 2.0

MINIFLUX-148Repeated item identifiers

When a feed reuses one identifier across several items, the first keeps the plain hash and each later one is disambiguated - by its address when it has one, and otherwise by its position in the feed. Entries already stored therefore continue to match.

Evidence

internal/reader/rss/adapter.go:80-82 and :138-149; the reasoning is spelled out in the comment at :130-136.

Note

Disambiguation by position is not stable: an item that moves within the feed changes identity and is stored again as a new entry. The code names this a last resort, so the instability appears to be accepted rather than overlooked.

Linked Resources
RSS 2.0 Specification RSS-2-0-SPECIFICATION 2.0

MINIFLUX-149Identity without an item identifier

An item with no identifier takes the hash of its link. An item with neither takes the hash of its title and content together, so an entry that is edited in place changes identity and is stored as a new entry.

Evidence

internal/reader/rss/adapter.go:150-153.

MINIFLUX-150Identity address form

The address hashed for identity is the one as the feed gave it, before it was resolved against the site address. A feed that changes from relative to absolute links therefore keeps its entries' identities only when they carry item identifiers.

Evidence

internal/reader/rss/adapter.go:150-151, which hashes entryURL rather than entry.URL.

Note

Recorded because the two variables differ by one line of resolution and the choice is easy to get wrong in a reimplementation. Nothing in the repository states which was intended.

5.6Feed extensions

MINIFLUX-151Recognised namespaces

Four extension vocabularies are read alongside the base formats: Dublin Core, Media RSS, iTunes and Google Play. Each contributes fields the base format does not carry, such as an item's language, media enclosures, duration and podcast metadata.

Evidence

internal/reader/dublincore/, internal/reader/media/, internal/reader/itunes/, internal/reader/googleplay/, all referenced from the RSS and Atom adapters.

MINIFLUX-152Enclosure address resolution

Enclosure addresses are resolved against the feed's site address in the same way as entry addresses.

Evidence

internal/reader/rss/adapter.go:88, which passes the site address into findEntryEnclosures.

6Processing entries

6.1The processing pipeline

MINIFLUX-153Processing order

Entries are processed oldest first, in reverse of the order the feed lists them, so that an older entry always receives a creation timestamp earlier than a newer one.

Evidence

internal/reader/processor/processor.go:64, iterating with slices.Backward; the reason is in the comment above it.

MINIFLUX-154Pipeline stages

Each entry passes through a fixed sequence: filtering, tracking-parameter removal, address rewriting, full-text scraping, content rewriting, filtering again when scraping replaced the content, sanitising, and reading-time estimation. An entry blocked at either filtering point is dropped and takes no further part.

Evidence

internal/reader/processor/processor.go:64-168.

MINIFLUX-155Sanitiser position

Sanitising is always the last transformation applied to an entry's content, after scraping and after every rewrite rule, so that no later stage can reintroduce unsafe markup.

Evidence

internal/reader/processor/processor.go:163-164; the code comment states the requirement directly.

MINIFLUX-156Blocked entries are discarded

An entry blocked by a filter rule is left out of the feed's entry list entirely. It is not stored and marked hidden, so a rule that is later removed does not bring it back.

Evidence

internal/reader/processor/processor.go:74-84 and :145-156, both continue without appending; the surviving entries replace feed.Entries at :173.

MINIFLUX-157Processing failure isolation

A failure to read the account while preparing to process a feed abandons the whole batch of entries silently, recording the database error. Individual entry failures - a scrape that fails, a watch time that cannot be fetched - are recorded and the entry continues through the pipeline.

Evidence

internal/reader/processor/processor.go:30-34 for the batch case; :128-141 for the per-entry case.

6.2Filtering entries

MINIFLUX-158Filter rule sources

Block rules and keep rules are each assembled from two sources: the account's own rules first, then the feed's. Both lists are evaluated as one, so an account-wide rule and a feed rule have equal standing.

Evidence

internal/reader/filter/filter.go:74-88 (ParseRules), called at internal/reader/processor/processor.go:39-40.

MINIFLUX-159Filter rule form

A rule is one line of the form Type=value. Whitespace around either half is removed, a carriage return is discarded, and a line without an equals sign is not a rule. Only the first equals sign separates the two halves, so a value may contain more.

Evidence

internal/reader/filter/filter.go:90-100 (parseRule), splitting with a limit of two.

MINIFLUX-160Filter rule types

Six fields can be matched by a rule: EntryTitle, EntryURL, EntryCommentsURL, EntryContent, EntryAuthor and EntryTag. A rule naming any other type never matches. A tag rule matches when any one of the entry's tags matches.

Evidence

internal/reader/filter/filter.go:189-205.

MINIFLUX-161Filter expression syntax

A rule's value is a regular expression in RE2 syntax, matched anywhere in the field rather than anchored.

Evidence

internal/reader/filter/filter.go:20, and the use of MatchString throughout matchesRule.

Linked Resources
RE2 Syntax RE2-SYNTAX Go regexp/syntax

MINIFLUX-162Invalid expression handling

A rule whose expression does not compile never matches, and the entry is not blocked by it. The failure is recorded once and does not stop the other rules being evaluated.

Evidence

internal/reader/filter/filter.go:52-72 (cachedRegex returning nil) and :186-188; asserted by TestMatchesRuleWithInvalidRegex.

Note

The failing-open direction matters: an invalid block rule lets everything through, and an invalid keep rule does not blank the feed. A reimplementation that failed closed would silently empty a feed.

Linked Resources
RE2 Syntax RE2-SYNTAX Go regexp/syntax

MINIFLUX-163Expression cache

Compiled expressions are cached and shared across accounts and feeds. When the cache reaches 1024 entries it is emptied entirely rather than evicting individually.

Evidence

internal/reader/filter/filter.go:44 and :52-72.

Note

A failed compilation is cached as a nil value, so a broken expression is not recompiled on every entry.

MINIFLUX-164Block rule precedence

An entry that matches a block rule is discarded even when it also matches a keep rule. Block rules are evaluated first and evaluation stops at the first that matches.

Evidence

internal/reader/filter/filter.go:101-104; asserted by TestAllowRulesWithBlockRulesPrecedence at filter_test.go:294-333, whose first case gives both lists an identical EntryTitle rule and expects the entry to be blocked.

MINIFLUX-165Keep rules are exclusive

When any keep rule exists, an entry matching none of them is discarded. Keep rules therefore turn the feed into an allow-list rather than merely protecting matching entries.

Evidence

internal/reader/filter/filter.go:111-118; asserted by TestAllowRulesExclusiveBehavior.

MINIFLUX-166Legacy regex rule stages

Two older per-feed expressions are evaluated alongside the rules above: a blocklist expression immediately after the block rules, and a keeplist expression last. Each is matched against the entry's address, title and author, and against any one of its tags.

Evidence

internal/reader/filter/filter.go:105-109 and :119-127; the fields matched are listed in matchesEntryRegexRules at :150-183.

Note

The package comment at filter.go:11-18 describes the order as user block, feed block, user keep, feed keep, and does not mention these two stages at all. The definition above states what the code does. The comment, not the code, appears to be the thing left behind when the typed rules were added.

MINIFLUX-167Legacy keeplist failure handling

When a feed's keeplist expression is invalid, the entry is kept rather than discarded, because an expression that could not be compiled is treated as absent rather than as unmatched.

Evidence

internal/reader/filter/filter.go:120-125, which requires the expression to be valid before treating a non-match as a reason to block.

MINIFLUX-168Date filter patterns

An EntryDate rule takes one of five patterns: future; before: or after: followed by a date; between: followed by two dates separated by a comma; or max-age: followed by a duration. Dates are written as YYYY-MM-DD, and both bounds of a range are exclusive.

Evidence

internal/reader/filter/filter.go:207-252 (isDateMatchingPattern).

MINIFLUX-169Date filter durations

A max-age duration may be given in days using a d suffix, which Go's own duration parser does not support, or in hours, minutes or seconds. A bare d means zero days.

Evidence

internal/reader/filter/filter.go:262-282 (parseDuration); the reason for handling days separately is in the comment.

MINIFLUX-170Malformed date pattern handling

A date rule whose pattern is malformed - a missing colon, an unparseable date, a range without exactly two dates, an unrecognised keyword - never matches, and so never blocks or keeps an entry.

Evidence

internal/reader/filter/filter.go:213-252: every failure path returns false; asserted by TestIsDateMatchingPatternEdgeCases.

MINIFLUX-171Filtering after scraping

Filter rules are evaluated a second time only when scraping actually replaced the entry's content. An entry whose content was unchanged is not re-filtered, so the second pass costs nothing when the crawler is off.

Evidence

internal/reader/processor/processor.go:145, guarded by contentExtractedSuccessfully; the two passes are distinguished in the log by filter_stage.

6.3Cleaning addresses

MINIFLUX-172Tracking parameter removal

Known tracking parameters are removed from an entry's address. Parameter names are matched without regard to case, and an address carrying no query string is left alone.

Evidence

internal/reader/urlcleaner/urlcleaner.go:129-174 (RemoveTrackingParameters).

MINIFLUX-173Tracking parameter list

The parameters removed cover the click identifiers and campaign parameters of the major advertising and analytics platforms - Google, Facebook, Yandex, Twitter, Microsoft, Mailchimp and others - as a fixed list rather than a pattern.

Evidence

internal/reader/urlcleaner/urlcleaner.go:19 onwards; the sources the list was assembled from are cited in the comment above it.

MINIFLUX-174Outbound-source parameters

A second group of parameters is removed only when the value names the feed's own host or the site's host, so a parameter that identifies where the reader came from is stripped while the same parameter carrying an unrelated value is kept.

Evidence

internal/reader/urlcleaner/urlcleaner.go:153-162; the loop over repeated values handles an address that carries the parameter more than once.

MINIFLUX-175Address preservation

An address from which nothing was removed is returned exactly as it arrived, without being re-encoded. An address that was changed has its query string rebuilt, and a trailing question mark left by removing the last parameter is dropped.

Evidence

internal/reader/urlcleaner/urlcleaner.go:165-173; the comment states the intent not to modify an address needlessly.

Note

This matters beyond tidiness: re-encoding would change the address, and an entry whose identity derives from its address would change identity and be stored again.

MINIFLUX-176URL rewrite rules

A feed's URL-rewrite rules are applied to the entry's address after tracking parameters have been removed, so a feed that publishes redirector links can be made to point at the real article.

Evidence

internal/reader/processor/processor.go:92 (rewrite.RewriteEntryURL); the rules in internal/reader/rewrite/url_rewrite.go.

6.4Full-text extraction

MINIFLUX-177Scraping precondition

The original page is fetched only for a feed with the crawler enabled, and only for an entry that is new or when the refresh was forced. An entry already stored is not re-scraped during an ordinary refresh.

Evidence

internal/reader/processor/processor.go:95.

MINIFLUX-178Extraction method

Content is extracted with the feed's own CSS selector rules when it has them, with a predefined rule set when one exists for that site, and otherwise by a readability algorithm. Custom rules are used only when the page is on the same site as the address requested.

Evidence

internal/reader/scraper/scraper.go:38-62; the predefined rules in internal/reader/scraper/rules.go, keyed by domain.

Note

The same-site condition prevents a selector written for one site being applied to whatever a redirect led to.

MINIFLUX-179Scraping failure handling

A scrape that fails leaves the entry's original content in place and records a warning. The entry is stored, not dropped.

Evidence

internal/reader/processor/processor.go:128-141; the code comment states that content is replaced only when the scraper returned no error.

MINIFLUX-180Empty extraction handling

A scrape that succeeds but extracts nothing leaves the entry's original content in place. Extraction never blanks an entry.

Evidence

internal/reader/processor/processor.go:137-141, which requires the extracted content to be non-empty.

MINIFLUX-181Scraped content base address

Relative addresses in scraped content are resolved against the address the scraped page was finally served from, and against the entry's own address when the scraper did not report one.

Evidence

internal/reader/processor/processor.go:118-121 and :158-161.

MINIFLUX-182On-demand extraction

A reader may fetch the original page for a single stored entry on demand. That path applies address rewriting, extraction, content rewriting and sanitising, and re-estimates the reading time, but does not apply filter rules.

Evidence

internal/reader/processor/processor.go:177-224 (ProcessEntryWebPage).

Note

Unlike the refresh path, a failed scrape here is returned to the caller as an error rather than swallowed, because the reader asked for it explicitly.

MINIFLUX-183Content rewrite rules

A feed's content-rewrite rules are applied after extraction and before sanitising. They are named transformations rather than expressions, and are applied on both the refresh path and the on-demand path.

Evidence

internal/reader/processor/processor.go:143 and :222; the transformations in internal/reader/rewrite/content_rewrite_functions.go.

6.5Sanitising content

MINIFLUX-184Allow-list sanitising

Entry content is filtered against a fixed allow-list of elements, each with its own list of permitted attributes. An element not on the list is removed while its text content is kept, and an attribute not permitted for its element is dropped.

Evidence

internal/reader/sanitizer/sanitizer.go:21-113 (the allow-list), :252-256 and :480-484.

MINIFLUX-185Permitted markup

The allow-list covers ordinary prose and structural markup, tables, media elements, ruby annotations, and the MathML element set. Scripts, styles, forms, event-handler attributes and inline styling are absent from it and so are removed.

Evidence

internal/reader/sanitizer/sanitizer.go:21-113; the MathML block is separated by its own comment citing the specification.

Linked Resources
MathML Core MATHML-CORE W3C Candidate Recommendation

MINIFLUX-186Malformed content handling

Content that cannot be parsed as HTML sanitises to an empty string rather than being passed through. The same applies when rendering the filtered document fails part-way.

Evidence

internal/reader/sanitizer/sanitizer.go:180-182 and :194-198.

Note

Failing to empty rather than to the input is the safe direction, but it means a parser failure silently blanks an entry with no message to the reader.

MINIFLUX-187Embedded frame allow-list

An embedded frame is kept only when its source is on one of thirteen permitted domains, covering the major audio and video platforms. A frame from any other domain is removed.

Evidence

internal/reader/sanitizer/sanitizer.go:116-130 (iframeAllowList) and findAllowedIframeSourceDomain at :203.

MINIFLUX-188Embedded frame schemes

An embedded frame's source must use http or https, or be protocol-relative. A frame using any other scheme is removed regardless of its domain.

Evidence

internal/reader/sanitizer/sanitizer.go:209-216; the comments record that only web addresses are allowed and that protocol-relative sources are deliberately preserved.

MINIFLUX-189Embedded frames carry no children

An embedded frame is rendered without its child nodes, whatever the source document contained.

Evidence

internal/reader/sanitizer/sanitizer.go:279-281.

MINIFLUX-190External link attributes

A link to another site is rewritten to carry rel="noopener noreferrer" and referrerpolicy="no-referrer", so the destination learns neither the referring page nor gains access to the opening window.

Evidence

internal/reader/sanitizer/sanitizer.go:579-580; README, "Privacy and Security".

MINIFLUX-191Embedded player referrer policy

An embedded player is given referrerpolicy="strict-origin-when-cross-origin" rather than the stricter policy applied to links.

Evidence

internal/reader/sanitizer/sanitizer.go:590-593; the comment records the reason - the stricter policy causes a YouTube player configuration error.

Note

This is a deliberate weakening of the privacy default for one third party's benefit. A reimplementation removing it should expect embedded YouTube playback to break.

MINIFLUX-192Tracking resource removal

Resources whose address contains one of eleven known tracking or sharing-widget substrings - social sharing endpoints, FeedBurner, analytics beacons - are removed from the content.

Evidence

internal/reader/sanitizer/sanitizer.go:132-145 (blockedResourceURLSubstrings).

MINIFLUX-193Inline image data

An inline data address is kept only when it declares one of nine image types: AVIF, APNG, PNG, SVG, JPEG, GIF or WebP. Any other inline data, including a scripted SVG payload under a different declaration, is removed.

Evidence

internal/reader/sanitizer/sanitizer.go:146-158 (dataAttributeAllowedPrefixes).

MINIFLUX-194Link target preference

Whether an external link opens in a new tab follows the reader's own preference, passed into the sanitiser for each account rather than fixed for the installation.

Evidence

internal/reader/sanitizer/sanitizer.go:160-163 (SanitizerOptions); supplied at internal/reader/processor/processor.go:164.

6.6Reading time

MINIFLUX-195Reading time preference

Reading time is estimated only for an account that has asked to see it. For every other account the estimate is skipped entirely, and no watch time is fetched.

Evidence

internal/reader/processor/reading_time.go:60-64.

MINIFLUX-196Text reading time estimate

Reading time is the entry's word count divided by the account's reading speed, rounded up to the next whole minute. Markup is removed before words are counted.

Evidence

internal/reader/readingtime/readingtime.go:15-27.

MINIFLUX-197CJK reading time estimate

Content detected as Chinese, Japanese or Korean is measured in characters rather than words, against the account's separate CJK reading speed. Detection reads the first 100 characters of the stripped text.

Evidence

internal/reader/readingtime/readingtime.go:17-25 and isCJK at :36; digits and control characters are excluded from the detection because the comment notes they are common in CJK text too.

MINIFLUX-198Video watch time

An entry recognised as a video on YouTube, Nebula, Odysee or Bilibili takes the video's duration as its reading time instead of an estimate. The four platforms are tried in that order and the first that recognises the entry is used.

Evidence

internal/reader/processor/reading_time.go:66-102.

MINIFLUX-199Watch time reuse

A watch time is fetched from the platform only for an entry that is new. An entry already stored takes the reading time already recorded for it, so a refresh does not fetch every video page again.

Evidence

internal/reader/processor/reading_time.go:82-98, the entryIsNew branch and its GetReadTime fallback.

MINIFLUX-200Watch time failure fallback

A watch time that cannot be fetched leaves the reading time unset, and the text estimate is then applied. An entry never ends up with no reading time because a platform was unreachable.

Evidence

internal/reader/processor/reading_time.go:83-93 and the fallback at :104-107.

MINIFLUX-201Watch time fetching switches

Fetching watch time is off by default for all four platforms and is enabled per platform by FETCH_YOUTUBE_WATCH_TIME, FETCH_NEBULA_WATCH_TIME, FETCH_ODYSEE_WATCH_TIME and FETCH_BILIBILI_WATCH_TIME.

Evidence

internal/config/options.go, the four keys, all defaulting to 0; consulted by the shouldFetch functions in internal/reader/processor/.

MINIFLUX-202Bulk YouTube watch time

When a YouTube API key is configured, watch times for a refresh are fetched for all its entries in one request after the entries have been processed, instead of one page fetch per entry.

Evidence

internal/reader/processor/processor.go:169-172; internal/reader/processor/youtube.go.

MINIFLUX-203Podcast duration precedence

A reading time already set from a feed's own duration metadata is kept, because the text estimate is applied only when no reading time has been established.

Evidence

internal/reader/processor/reading_time.go:104-107, guarded on the reading time being zero.

7Reading entries

7.1Status and starring

MINIFLUX-204Entry statuses

An entry is in one of two states, unread or read. There is no third state; an entry that has been removed by retention is gone rather than archived into a status of its own.

Evidence

internal/model/entry.go:11-15.

Note

The Google Reader compatibility layer speaks of streams rather than statuses, and maps its read and kept-unread streams onto these two values.

MINIFLUX-205Starring is independent of status

Starring an entry is a separate flag from its read status. An entry may be starred whether it is read or unread, and changing one does not change the other.

Evidence

internal/model/entry.go: Status and Starred are separate fields; internal/storage/entry_query_builder.go:62-70 filters on them separately.

MINIFLUX-206Bulk status change

Several entries can be given a status in one operation, scoped to the account that owns them, so an entry belonging to another account is never affected.

Evidence

internal/storage/entry.go:412-430 (SetEntriesStatus), whose query is scoped by user.

MINIFLUX-207Mark all as read

An account can mark all of its entries read in one operation, and can mark read only those published before a given moment.

Evidence

internal/storage/entry.go:505-535 (MarkAllAsRead, MarkAllAsReadBeforeDate).

MINIFLUX-208Mark on view

Whether opening an entry marks it read follows the reader's own preference rather than being fixed.

Evidence

internal/model/user.go, the MarkReadOnView field.

MINIFLUX-209Mark on playback completion

An account may ask that an entry be marked read when its attached media finishes playing, as a separate preference from marking on view.

Evidence

internal/model/user.go, the MarkReadOnMediaPlayerCompletion field.

MINIFLUX-210Playback position

The playback position of an entry's enclosure is stored, so that resuming a podcast or video continues where it left off.

Evidence

internal/model/enclosure.go; the saving endpoint at internal/ui/entry_enclosure_save_position.go and PUT /v1/enclosures/{enclosureID}.

7.2Listing entries

MINIFLUX-211Default sort order

Entries are listed by publication date, oldest first, unless the caller asks otherwise.

Evidence

internal/model/entry.go:13-14 (DefaultSortingOrder, DefaultSortingDirection).

MINIFLUX-212Sort direction validation

A sort direction is either asc or desc; any other value is refused. A direction that reaches the query builder unrecognised adds no ordering at all rather than defaulting.

Evidence

internal/validator/validator.go:34-40 (ValidateDirection); internal/storage/entry_query_builder.go:191-199, whose switch has no default branch.

MINIFLUX-213Sort column safety

A sort column is quoted as an identifier before it is placed in the query, so a column name cannot alter the query's structure.

Evidence

internal/storage/entry_query_builder.go:194-196, using pq.QuoteIdentifier.

MINIFLUX-214Listing limit ceiling

An entry listing returns at most 1000 entries. A request for more is refused with 400 Bad Request and the message limit value should be <= 1000.

Evidence

internal/model/entry.go:20 (MaxEntryLimit); internal/validator/validator.go:27-29, called from internal/api/entry_handlers.go:144.

MINIFLUX-215Unbounded listing prevention

A limit of zero or a negative limit is replaced by the maximum rather than returning everything, so no query can ask for an unbounded result set.

Evidence

internal/storage/entry_query_builder.go:201-217; the intent is stated in the doc comment.

Note

The two rules interact in a way worth knowing before reimplementing: a request with limit=0 passes validation, because only a negative limit is refused, and is then clamped to 1000. A caller asking for zero entries receives a thousand.

MINIFLUX-216Identifier listing ceiling

An endpoint returning entry identifiers rather than entries returns at most 10,000 of them. A request above that is clamped to the maximum rather than refused.

Evidence

internal/model/entry.go:24 (MaxEntryIDsLimit); internal/api/entry_handlers.go:626-630.

Note

The two ceilings behave differently on the same input: an over-large limit is a client error on the entry listing and a silent clamp on the identifier listing.

MINIFLUX-217Per-page preference

An account's entries-per-page preference is between 1 and 1000. A value outside that range is refused with error.entries_per_page_invalid.

Evidence

internal/validator/user.go:214-219; asserted at the boundaries by internal/validator/user_test.go:113-120.

MINIFLUX-218Negative offset handling

A negative offset is refused by the API, and an offset of zero or less adds no offset to the query rather than producing an error deeper down.

Evidence

internal/validator/validator.go:19-21; internal/storage/entry_query_builder.go:219-224.

MINIFLUX-219Content omission

A listing can be asked to omit entry content, and then returns an empty string in its place rather than omitting the field. A caller can therefore parse both shapes the same way.

Evidence

internal/storage/entry_query_builder.go:40-44 and :515-520, which selects '' AS content.

MINIFLUX-220Globally hidden feeds

A feed or category marked hidden is left out of listings that show everything, while remaining reachable when its own feed or category is opened directly.

Evidence

internal/storage/entry_query_builder.go:226-231 (WithGloballyVisible), which excludes both a hidden category and a hidden feed.

7.3Search

MINIFLUX-221Search implementation

Search is full-text search in the database, matching a query against a stored document vector for each entry rather than scanning the text at query time.

Evidence

internal/storage/entry_query_builder.go:45-58, matching e.document_vectors; README, "Provides full-text search (powered by Postgres)".

MINIFLUX-222Search query syntax

A search query is interpreted with web-search syntax, so quoted phrases and negation work as a reader would expect from a search box, and a malformed query does not produce an error.

Evidence

internal/storage/entry_query_builder.go:48, using websearch_to_tsquery.

MINIFLUX-223Search result ranking

Search results are ordered by textual relevance with a small penalty for age, so that among similarly relevant entries the more recent ones come first. The penalty is 0.1 of a rank point per day since publication.

Evidence

internal/storage/entry_query_builder.go:53-56; the constant is explained by the comment 0.0000001 = 0.1 / (seconds_in_a_day).

MINIFLUX-224Empty search handling

An empty search query adds no condition and no ranking, so the listing behaves as an ordinary one rather than returning nothing.

Evidence

internal/storage/entry_query_builder.go:46-47.

7.4Sharing entries

MINIFLUX-225Share code generation

Sharing an entry gives it a random 20-byte code, generated the first time it is shared. Sharing the same entry again returns the code it already has, so a link that has been handed out keeps working.

Evidence

internal/storage/entry.go:644-667 (EntryShareCode).

MINIFLUX-226Shared entry access

An entry with a share code is readable by anyone holding the code, without signing in. The code is the only credential.

Evidence

internal/ui/share.go:47, selecting by share code alone; internal/storage/entry_query_builder.go:178-183.

MINIFLUX-227Unsharing

Unsharing an entry clears its code, and a link previously handed out stops working. Sharing it again produces a new code rather than restoring the old one.

Evidence

internal/storage/entry.go:669-676 (UnshareEntry), followed by the generation branch in EntryShareCode.

MINIFLUX-228Shared entry retention

A shared entry is never removed by the retention task, so a link that has been published does not break when the entry ages out.

Evidence

internal/storage/entry.go:380, which excludes entries with a share code from archiving.

MINIFLUX-229Shared entry listing

An account can list the entries it currently shares, so that shares can be found and withdrawn.

Evidence

internal/ui/shared_entries.go:24, using WithShareCodeNotEmpty.

7.5Icons

MINIFLUX-230Icon discovery

A feed's icon is taken from the address the feed declares when it has one, from the icons declared in the site's HTML otherwise, and from the site's conventional icon path as a last resort.

Evidence

internal/reader/icon/finder.go:49-104 (findIcon, fetchDefaultIcon, fetchIconsFromHTMLDocument).

MINIFLUX-231Inline icon data

An icon declared as inline data is decoded from the declaration itself rather than fetched over the network.

Evidence

internal/reader/icon/finder.go:318 (parseImageDataURL).

MINIFLUX-232Icon resizing

A downloaded icon is resized before being stored, so that the size held in the database is bounded whatever the site served.

Evidence

internal/reader/icon/finder.go:186 (resizeIcon).

MINIFLUX-233Icon sharing

Icons are stored once and referenced by the feeds that use them, so several feeds from one site do not each hold a copy.

Evidence

internal/storage/icon.go; the orphan cleanup at :158-162 exists precisely because an icon can outlive the feed that fetched it.

7.6Media proxy

MINIFLUX-234Proxy modes

MEDIA_PROXY_MODE takes one of three values: none proxies nothing, http-only proxies only insecure resources, and all proxies both. The default is http-only, and any other value is refused at start-up.

Evidence

internal/config/options.go:370-377, validated against the three choices; the behaviour at internal/mediaproxy/rewriter.go:110-125.

MINIFLUX-235Proxied resource types

MEDIA_PROXY_RESOURCE_TYPES selects which kinds of resource are proxied, defaulting to images only. Audio and video are proxied only when named.

Evidence

internal/config/options.go:382-390; the per-type handling at internal/mediaproxy/rewriter.go:39-96.

MINIFLUX-236Proxy address signing

A proxied address is signed with an HMAC-SHA256 over the original address, using the installation's private key. The address and its signature are both encoded into the path, so the proxy serves only addresses this installation produced.

Evidence

internal/mediaproxy/url.go:16-32 (ProxifyRelativeURL).

Note

Without the signature the proxy would be an open relay for arbitrary addresses. A reimplementation must keep the key secret and must verify the signature before fetching.

MINIFLUX-237Proxy base path

A proxied address carries the installation's configured base path, so proxying still works when Miniflux is served from a subdirectory.

Evidence

internal/mediaproxy/url.go:30-31; the reason is stated in the code comment.

MINIFLUX-238External proxy

When MEDIA_PROXY_CUSTOM_URL names an external proxy, media addresses are rewritten to point at it, encoded but unsigned, and Miniflux does no proxying of its own.

Evidence

internal/mediaproxy/url.go:21-23 and :53-60 (proxifyURLWithCustomProxy).

Note

The signature is not applied on this path, because the external proxy is responsible for its own access control. That is a meaningful difference in the security model between the two modes.

MINIFLUX-239Absolute proxy addresses

An absolute proxied address is the relative one joined onto the installation's root address. When that join fails the original media address is returned unproxied rather than a broken one.

Evidence

internal/mediaproxy/url.go:34-51 (ProxifyAbsoluteURL).

MINIFLUX-240Proxy timeout

A proxied media fetch is allowed MEDIA_PROXY_HTTP_CLIENT_TIMEOUT, 120 seconds by default - considerably longer than a feed fetch, because media are larger.

Evidence

internal/config/options.go:362-369, against the 20-second HTTP_CLIENT_TIMEOUT.

MINIFLUX-241Source set proxying

Every candidate in an image's source set is proxied, not only its primary source, so a responsive image does not fall back to an unproxied variant.

Evidence

internal/mediaproxy/rewriter.go:97-108 (proxifySourceSet).

8Retention

8.1Removing old entries

MINIFLUX-242Read entry retention

The cleanup task deletes read entries created more than CLEANUP_ARCHIVE_READ_DAYS ago, 60 days by default.

Evidence

internal/storage/entry.go:368-400 (ArchiveEntries), called at internal/cli/cleanup_tasks.go:25; the default at internal/config/options.go:134-138.

Note

The operation is named "archive" throughout the configuration and the code, but nothing is archived: the rows are deleted. The manual page is accurate about this - it says archiving "deletes non-bookmarked, non-shared read entries from the database". The name is the misleading part, not the documentation.

Linked Resources
Miniflux Manual Page MINIFLUX-MANUAL-PAGE miniflux.1 in this repository

MINIFLUX-243Unread entry retention

The cleanup task deletes unread entries created more than CLEANUP_ARCHIVE_UNREAD_DAYS ago, 180 days by default. An entry is removed whether or not it was ever read.

Evidence

internal/cli/cleanup_tasks.go:37; the default at internal/config/options.go:139-143.

MINIFLUX-244Retention exemptions

A starred entry and an entry carrying a share code are never removed by retention, whatever their age or status.

Evidence

internal/storage/entry.go:378-380, which requires starred is false and an empty share code.

MINIFLUX-245Retention tombstones

Deleting an entry records a tombstone of its feed and content hash, so a later refresh of that feed does not present the same entry as new. An entry with no hash produces no tombstone.

Evidence

internal/storage/entry.go:384-393; the insert skips rows where hash <> '' is false and ignores conflicts.

Note

Without the tombstone a feed that still lists an old item would reintroduce it as unread on the next refresh, undoing the retention. This is the mechanism a reimplementation is most likely to omit.

MINIFLUX-246Retention batch size

At most CLEANUP_ARCHIVE_BATCH_SIZE entries are removed per status per run, 10,000 by default. A backlog larger than that is worked through over successive runs.

Evidence

internal/storage/entry.go:382; the default and its lower bound of 1 at internal/config/options.go:126-133.

MINIFLUX-247Retention selection order

Within a run the oldest entries are removed first, so a backlog is worked off in age order rather than arbitrarily.

Evidence

internal/storage/entry.go:381, ORDER BY created_at ASC.

MINIFLUX-248Retention lock avoidance

Rows already locked by another transaction are skipped rather than waited for, so a cleanup run never blocks on concurrent activity and simply removes fewer entries that time.

Evidence

internal/storage/entry.go:381, FOR UPDATE SKIP LOCKED.

MINIFLUX-249Retention interval floor

A retention period shorter than one day is treated as one day. Setting the period to zero does not delete every entry immediately.

Evidence

internal/storage/entry.go:396, max(int(interval/(24*time.Hour)), 1).

MINIFLUX-250Retention disabling

A negative retention period, or a batch size of zero or less, removes nothing and reports nothing removed, rather than failing.

Evidence

internal/storage/entry.go:369-371.

MINIFLUX-251Manual history flush

An account can delete all of its read entries at once, regardless of age. The same exemptions apply - starred and shared entries survive - and tombstones are recorded in the same way. Unlike the scheduled task, this is not limited to a batch.

Evidence

internal/storage/entry.go:487-504 (FlushHistory); exposed as PUT and DELETE /v1/flush-history and at internal/ui/history_flush.go.

8.2Other cleanup

MINIFLUX-252Cleanup cycle

Every CLEANUP_FREQUENCY_HOURS, 24 by default, one cleanup run removes old sessions, then old read entries, then old unread entries, then orphaned icons, in that order.

Evidence

internal/cli/scheduler.go:52-56; the sequence at internal/cli/cleanup_tasks.go:16-77.

MINIFLUX-253Cleanup step independence

Each step of a cleanup run is independent: a step that fails is recorded and the remaining steps still run.

Evidence

internal/cli/cleanup_tasks.go: each step handles its own error and none returns early.

MINIFLUX-254Session retention

Browser sessions created more than CLEANUP_REMOVE_SESSIONS_DAYS ago, 30 days by default, are removed. The period is measured from when the session was created, not from when it was last used, so a session in daily use is still ended 30 days after sign-in.

Evidence

internal/storage/web_session.go:229-247; the query compares created_at.

Note

The manual page describes this only as "Number of days after removing old sessions from the database", which does not say which timestamp is measured. A reimplementation using last-used time would change how often people are signed out, without any documentation contradicting it.

Linked Resources
Miniflux Manual Page MINIFLUX-MANUAL-PAGE miniflux.1 in this repository

MINIFLUX-255Session retention floor

A session retention period shorter than one day is treated as one day, so sessions cannot be configured to expire within hours.

Evidence

internal/storage/web_session.go:238; the doc comment at :229 states the minimum.

MINIFLUX-256Orphan icon removal

Icons no longer referenced by any feed are removed on each cleanup run.

Evidence

internal/storage/icon.go:158-176; the comment records the two ways orphans arise - a deleted feed, whose cascade removes only the mapping, and a replaced icon.

MINIFLUX-257Manual session flush

An administrator can remove every browser session at once from the command line, ending all sign-ins immediately.

Evidence

internal/storage/web_session.go:249-255 (FlushAllSessions); internal/cli/flush_sessions.go, the -flush-sessions option.

9The REST API

9.1Shape and conventions

MINIFLUX-258API base path

Every REST endpoint lives under /v1/, beneath the installation's configured base path. The version is part of the path rather than a header.

Evidence

internal/api/api.go:25-75; mounted at internal/http/server/routes.go:37.

MINIFLUX-259API availability switch

Setting DISABLE_API stops the API being mounted at all, so its endpoints answer as unknown addresses rather than refusing access. The API is enabled by default.

Evidence

internal/http/server/routes.go:36-38; the option at internal/config/options.go:743.

MINIFLUX-260Response encoding

Every response body is JSON and carries a JSON content type, including error responses.

Evidence

internal/http/response/json.go: every helper sets the same content-type header.

MINIFLUX-261Error body shape

An error response carries a JSON object holding the reason, so a client can read the message without parsing the status alone.

Evidence

internal/http/response/json.go, generateJSONError, used by every error helper.

MINIFLUX-262Standard error statuses

Four error statuses are used consistently: 400 for a malformed or invalid request, 401 when authentication failed, 403 when the account may not perform the action, and 404 when the resource does not exist. An unexpected failure is 500.

Evidence

internal/http/response/json.go:55-160.

MINIFLUX-263Creation status

A request that creates a resource is answered with 201 Created and the created resource, rather than 200.

Evidence

internal/http/response/json.go:32-45 (JSONCreated).

MINIFLUX-264Asynchronous acceptance

A request that starts work rather than completing it - a feed refresh, for instance - is answered with 202 Accepted and an empty body.

Evidence

internal/http/response/json.go:47-53 (JSONAccepted).

MINIFLUX-265Server error disclosure

An unexpected failure is written to the log with the request's method, address, client address and user agent, and the client is told only that an internal error occurred.

Evidence

internal/http/response/json.go:55-76.

MINIFLUX-266Authentication failure logging

Every refused request - unauthorised, forbidden or not found - is recorded with the client address and user agent, so repeated attempts are visible in the log.

Evidence

internal/http/response/json.go:99-160; the API middleware adds an authentication_failed marker at internal/api/middleware.go:58-64.

9.2Authorisation

MINIFLUX-267Administrator-only operations

Creating, listing, modifying and removing accounts other than one's own requires an administrator. A non-administrator attempting any of them is answered with 403 Forbidden.

Evidence

internal/api/user_handlers.go:34, :83, :117, :159, :188, :215, :236.

MINIFLUX-268Own-account access

An account may read and modify itself without being an administrator. GET /v1/me returns the authenticated account.

Evidence

internal/api/api.go:31; the non-administrator branch at internal/api/user_handlers.go:83-118.

MINIFLUX-269Resource ownership

Every feed, category, entry, icon, enclosure and API key operation is scoped to the authenticated account. A resource belonging to another account is reported as not found rather than as forbidden, so the API does not disclose that it exists.

Evidence

The storage queries carry a user_id condition throughout - for example internal/storage/entry.go:647 and internal/storage/entry_query_builder.go, whose builder is constructed per user.

9.3Endpoints

MINIFLUX-270Account endpoints

Accounts are created, listed, read, modified and removed under /v1/users, an account can be looked up by identifier or by name, all of an account's entries can be marked read, and the authenticated account is read at /v1/me.

Evidence

internal/api/api.go:25-31.

MINIFLUX-271Category endpoints

Categories are created, listed, modified and removed under /v1/categories. A category also exposes its feeds, its entries, a single entry, a refresh of all its feeds, and marking all its entries read.

Evidence

internal/api/api.go:32-40.

MINIFLUX-272Feed endpoints

Feeds are created, listed, read, modified and removed under /v1/feeds. A feed also exposes its icon, its entries, a single entry, a refresh, and marking all its entries read; unread counters for all feeds are read at /v1/feeds/counters and every feed can be refreshed at once.

Evidence

internal/api/api.go:42-56.

MINIFLUX-273Discovery endpoint

POST /v1/discover runs feed discovery against a submitted address and returns the subscriptions found, without creating any.

Evidence

internal/api/api.go:41; internal/api/subscription_handlers.go.

MINIFLUX-274Entry endpoints

Entries are listed and read under /v1/entries, their status and starred flag are changed in bulk or individually, an entry can be saved to the configured integrations, and its original page can be fetched on demand. Entry identifiers alone are listed at /v1/entries/ids.

Evidence

internal/api/api.go:57-66.

MINIFLUX-275Starring endpoint aliases

An entry's starred flag is toggled at either /v1/entries/{entryID}/bookmark or /v1/entries/{entryID}/star. Both addresses invoke the same behaviour.

Evidence

internal/api/api.go:62-63, both bound to toggleStarredHandler.

Note

The pair is a compatibility alias rather than two features. A reimplementation should keep both, since existing clients use one or the other.

MINIFLUX-276History flush methods

Flushing an account's read history is accepted on both PUT and DELETE at /v1/flush-history, with the same effect.

Evidence

internal/api/api.go:66-67.

MINIFLUX-277Subscription transfer endpoints

An account's subscriptions are exported as OPML at GET /v1/export and imported at POST /v1/import.

Evidence

internal/api/api.go:52-53; internal/api/opml_handlers.go.

Linked Resources
OPML 2.0 Specification OPML-2-0-SPECIFICATION 2.0

MINIFLUX-278Entry import endpoint

An entry can be added to a feed directly at POST /v1/feeds/{feedID}/entries/import, without the feed being fetched.

Evidence

internal/api/api.go:55.

MINIFLUX-279Icon endpoints

An icon is read either by the feed that uses it or by its own identifier, so a client can cache one icon shared by several feeds.

Evidence

internal/api/api.go:50 and :68.

MINIFLUX-280Enclosure endpoints

An enclosure is read and modified by its own identifier, which is how a client records a media playback position.

Evidence

internal/api/api.go:69-70.

MINIFLUX-281API key endpoints

An account creates, lists and deletes its own API keys under /v1/api-keys. A key is created with a description only; its token is generated by the server.

Evidence

internal/api/api.go:73-75; internal/model/api_key.go, whose creation request carries only a description.

MINIFLUX-282Integration status endpoint

GET /v1/integrations/status reports only whether the account has any integration configured, not which ones or how they are configured.

Evidence

internal/api/api.go:71; the response shape at internal/api/messages.go:21-23, a single boolean.

Note

Deliberately narrow: integration settings hold third-party credentials, so the API exposes their existence rather than their content.

MINIFLUX-283Version endpoint

GET /v1/version reports the Miniflux version, the commit it was built from, the build date, and the Go version, compiler, architecture and operating system it was built for.

Evidence

internal/api/version_handler.go:13-23.

Note

The endpoint requires authentication like every other, so the build details are not exposed to anonymous callers.

9.4Listing parameters

MINIFLUX-284Entry listing default limit

An entry listing that does not ask for a limit returns 100 entries.

Evidence

internal/api/entry_handlers.go:142.

MINIFLUX-285Identifier listing default limit

An identifier listing that does not ask for a limit returns the maximum, 10,000 identifiers, rather than a smaller default.

Evidence

internal/api/entry_handlers.go:627-630.

MINIFLUX-286Sort parameter validation

The order and direction parameters are validated against a fixed set before the query is built, and an unrecognised value is refused with 400 Bad Request rather than ignored.

Evidence

internal/api/entry_handlers.go:130-140.

MINIFLUX-287Category filter validation

An entry listing filtered by category checks that the category belongs to the authenticated account, and refuses an unknown one with 400 Bad Request and the message invalid category ID.

Evidence

internal/api/entry_handlers.go:150-160.

MINIFLUX-288Entry listing total

An entry listing returns the total number of matching entries alongside the page returned, so a client can paginate without a second request.

Evidence

internal/api/messages.go:16-19 (entriesResponse); internal/storage/entry_query_builder.go:278 (GetEntriesWithCount).

10Compatibility APIs

10.1Fever

MINIFLUX-289Fever endpoint

The Fever-compatible API is served at /fever/. It is always mounted, independently of whether the REST API is enabled.

Evidence

internal/http/server/routes.go:27-28, mounted before and outside the HasAPI condition at :36.

Note

Recorded because it is easy to assume DISABLE_API disables every programmatic interface. It does not: the Fever and Google Reader endpoints stay available.

MINIFLUX-290Fever authentication

Every Fever request carries an api_key parameter identifying the account. A request without one, or with one that matches no account, is answered with a normal response body reporting authentication as unsuccessful rather than with an HTTP error status.

Evidence

internal/fever/middleware.go:21-52, all three failure paths returning newAuthFailureResponse through response.JSON.

Note

Answering an authentication failure with 200 is required by the Fever protocol, which signals success in the body rather than the status. A reimplementation returning 401 would break Fever clients.

Linked Resources
Fever API Specification FEVER-API-SPECIFICATION API version 3

MINIFLUX-291Fever response envelope

Every Fever response carries the API version and a flag saying whether the request was authenticated, alongside whatever the request asked for.

Evidence

internal/fever/response.go:11-12 and :40; the protocol requirement is quoted in the comment at :25-35.

Linked Resources
Fever API Specification FEVER-API-SPECIFICATION API version 3

MINIFLUX-292Fever request dispatch

A Fever request is dispatched on the presence of a query parameter rather than on its path: groups, feeds, favicons, unread_item_ids, saved_item_ids and items each select a read operation, and a mark form value of item, feed or group selects a write. A request matching none of them receives the bare envelope.

Evidence

internal/fever/handler.go:31-53.

Linked Resources
Fever API Specification FEVER-API-SPECIFICATION API version 3

MINIFLUX-293Fever entry marking

Marking an item accepts four values: read and unread set the entry's status, and saved and unsaved both toggle its starred flag. Any other value leaves the entry unchanged and still returns a successful response.

Evidence

internal/fever/handler.go:429-472.

Note

Both saved and unsaved call ToggleStarred rather than setting the flag to a particular value, so the outcome depends on the entry's current state rather than on the value sent. A client that sends saved for an already-starred entry un-stars it.

MINIFLUX-294Fever save dispatch

Marking an item saved also sends it to the account's configured integrations, in the background. Marking it unsaved does not.

Evidence

internal/fever/handler.go:451-459.

MINIFLUX-295Fever unknown entry handling

A mark request naming an entry the account does not have returns the bare envelope rather than an error, so a client working from a stale list is not broken by it.

Evidence

internal/fever/handler.go:419-427.

MINIFLUX-296Fever media proxying

Entry content served through the Fever API has its media addresses rewritten to absolute proxied addresses, because a Fever client is not browsing the site and cannot resolve relative ones.

Evidence

internal/fever/handler.go imports internal/mediaproxy and applies the absolute rewriter to item content.

10.2Google Reader

MINIFLUX-297Google Reader endpoints

The Google Reader-compatible API is served at /reader/api/0/, with its sign-in endpoint at /accounts/ClientLogin. Thirteen operations are implemented: token issue, tag editing, renaming and disabling, tag listing, account information, subscription listing, editing and quick-add, stream item identifiers and contents, and marking everything read.

Evidence

internal/googlereader/handler.go:49-63.

MINIFLUX-298Google Reader fallback

Any other address under the Google Reader path is handled by a fallback rather than reported as unknown, on both GET and POST, so an unimplemented call does not look like a missing service.

Evidence

internal/googlereader/handler.go:62-63.

MINIFLUX-299Google Reader credentials

Google Reader access uses a separate username and password held in the account's integration settings, not the account's own credentials. The integration must be configured before the endpoints can be used.

Evidence

internal/googlereader/middleware.go:138, reading integration.GoogleReaderUsername and GoogleReaderPassword.

MINIFLUX-300Google Reader token form

An authentication token is the account's Google Reader username, a slash, and a hexadecimal digest derived from that username and password. A token without that structure is refused.

Evidence

internal/googlereader/middleware.go:182-186 (getAuthToken) and the structure check at :114-121.

Note

The digest is produced by calling Sum on a fresh HMAC without writing any message, so it is a function of the key - the username and password concatenated - and nothing else. It is deterministic and works as a shared secret, but it is not an HMAC over any content, and a reimplementation copying the shape without the exact call would produce different tokens and invalidate every configured client.

MINIFLUX-301Google Reader token transport

A token is accepted either as the form value T or in an Authorization header of the form GoogleLogin auth=<token>. A header in any other shape is refused with a message naming the expected format.

Evidence

internal/googlereader/middleware.go:38-112.

MINIFLUX-302Google Reader token comparison

A presented token is compared against the expected one in constant time.

Evidence

internal/googlereader/middleware.go:139, using crypto.ConstantTimeCmp.

MINIFLUX-303Google Reader stream types

Nine stream types are recognised, alongside a value meaning no stream: read, starred, reading list, kept unread, broadcast, broadcast friends, label, feed and like. They are mapped onto Miniflux's own two entry statuses, its starred flag, its categories and its feeds; the broadcast, broadcast friends and like streams have no Miniflux equivalent.

Evidence

internal/googlereader/stream.go:12-33 for the constants and :45-69 for their names.

MINIFLUX-304Google Reader stream identifiers

A stream identifier is recognised either as one of the well-known stream prefixes or as a prefix scoped to the requesting account's own identifier, so a client may address a stream in either form.

Evidence

internal/googlereader/stream.go:77.

MINIFLUX-305Google Reader result ceiling

A Google Reader stream request returns at most 10,000 items, the same ceiling the REST API applies to identifier listings.

Evidence

internal/googlereader/handler.go:1029, :1066, :1090 and :1142, all using model.MaxEntryIDsLimit.

MINIFLUX-306Google Reader documentation

The compatibility layer's own behaviour is described in internal/googlereader/README.md, which is the reference for which parts of the original protocol are implemented.

Evidence

internal/googlereader/README.md, 592 lines, not served by the application.

Note

This document was read for vocabulary but not audited line by line against the handler. Any discrepancy between it and the code is therefore unrecorded, and it is the first place to look when reimplementing this section.

11Integrations

11.1The common contract

MINIFLUX-307Two dispatch occasions

Integrations run on two distinct occasions, and each integration belongs to exactly one of them: saving a single entry on the reader's request, and announcing the entries a refresh has just discovered.

Evidence

internal/integration/integration.go:41 (SendEntry) and :511 (PushEntries).

MINIFLUX-308Save targets

Twenty-one services receive a single saved entry: Betula, Pinboard, Instapaper, Wallabag, Notion, Nunux Keeper, Espial, LinkAce, Linkding, LinkTaco, Linkwarden, Readeck, Readwise, Cubox, Shiori, Shaarli, the Internet Archive, a webhook, Omnivore, Karakeep and Raindrop.

Evidence

internal/integration/integration.go:41-509; each has its own client package under internal/integration/.

MINIFLUX-309Announcement targets

Nine services receive the entries a refresh discovered: Matrix, a webhook, ntfy, Apprise, Discord, Slack, Pushover, a Telegram bot, and Readeck's push mode.

Evidence

internal/integration/integration.go:511 onwards.

MINIFLUX-310Webhook on both occasions

The webhook is the only integration invoked on both occasions, sending a different event type for each.

Evidence

internal/integration/integration.go, WebhookEnabled tested in both functions; internal/integration/webhook/webhook.go:32 and :68.

MINIFLUX-311Readeck has two modes

Readeck appears in both lists under two separate settings: one saves an entry on request, the other announces newly discovered entries. Each is enabled independently.

Evidence

ReadeckEnabled in SendEntry and ReadeckPushEnabled in PushEntries, internal/model/integration.go.

MINIFLUX-312Per-integration enablement

Each integration is enabled by its own flag on the account's integration settings, and its configuration - address, token, credentials - is held alongside that flag. An integration that is not enabled is skipped without its settings being read.

Evidence

internal/model/integration.go:7-119; every dispatch in integration.go is guarded by the corresponding ...Enabled field.

MINIFLUX-313Integration failure isolation

An integration that fails records the failure with the account, entry and feed involved, and the remaining integrations still run. One unreachable service does not stop the others.

Evidence

internal/integration/integration.go: every block handles its own error and none returns early - for example :56-63 and :527-534.

MINIFLUX-314Dispatch is asynchronous

Integrations run in the background. A refresh does not wait for them, and neither does the request that saved an entry, so a slow third party cannot delay either.

Evidence

internal/reader/handler/handler.go:348 and internal/fever/handler.go:457-459, both dispatching in a goroutine.

Note

Because the dispatch is fire-and-forget, a failure is visible only in the log; nothing is retried and nothing is reported back to the reader.

MINIFLUX-315Announcement precondition

Entries are announced only when a refresh actually produced new ones. A refresh that found nothing new dispatches nothing, even to an enabled integration.

Evidence

internal/reader/handler/handler.go:348, guarded on len(newEntries) > 0.

MINIFLUX-316Integration network restriction

Integration requests are subject to INTEGRATION_ALLOW_PRIVATE_NETWORKS, which is off by default. A self-hosted target on a private address is therefore unreachable until that setting is turned on.

Evidence

internal/config/options.go, key INTEGRATION_ALLOW_PRIVATE_NETWORKS.

Note

Worth stating plainly because many of these targets - Linkding, Shiori, Wallabag, Readeck, Betula - are typically self-hosted alongside Miniflux, so the default refuses the common deployment.

11.2Webhooks

MINIFLUX-317Webhook event types

A webhook delivery names its occasion in an X-Miniflux-Event-Type header, distinguishing a saved entry from a batch of newly discovered ones, so one endpoint can serve both.

Evidence

internal/integration/webhook/webhook.go:112-126.

MINIFLUX-318Webhook signature

Every webhook delivery carries an X-Miniflux-Signature header holding an HMAC-SHA256 of the request body under the account's webhook secret, so the receiver can verify the delivery came from this installation and was not altered.

Evidence

internal/integration/webhook/webhook.go:125, using crypto.GenerateSHA256Hmac over the serialised body.

MINIFLUX-319Webhook payload scope

A saved-entry delivery carries the entry; a new-entries delivery carries the feed and the entries discovered. The two payloads are built separately rather than sharing one shape.

Evidence

internal/integration/webhook/webhook.go:32-66 and :68-110.

11.3RSS-Bridge

MINIFLUX-320RSS-Bridge as a discovery source

RSS-Bridge is configured as an integration but is not a delivery target: it participates in feed discovery, offering bridges for sites that publish no feed of their own.

Evidence

internal/model/integration.go:96-98; consumed at internal/reader/subscription/finder.go:114-124, and absent from both dispatch functions.

12Running the service

12.1Configuration

MINIFLUX-321Configuration sources

Configuration comes from environment variables, or from a file named by -config-file holding the same keys. Every option has a default, so the service starts with no configuration at all.

Evidence

internal/config/parser.go:31 and :39; the defaults at internal/config/options.go:62-1044.

MINIFLUX-322Secrets from files

A secret can be supplied from a file instead of an environment variable, using the corresponding key with a _FILE suffix. The file's contents become the value of the key it targets.

Evidence

internal/config/parser.go:220; the targetKey field on each _FILE option, for example internal/config/options.go:73-78.

Note

This is what makes container secret mounts usable. The pairs exist for the administrator credentials, the database address, the metrics credentials and the OAuth2 client details.

MINIFLUX-323Secret redaction

An option marked secret is not written out when the configuration is dumped, so -config-dump can be shared without leaking credentials.

Evidence

The secret field on configValue, internal/config/options.go:45, set on ADMIN_PASSWORD, MEDIA_PROXY_PRIVATE_KEY, METRICS_PASSWORD and the OAuth2 secrets.

MINIFLUX-324Configuration validation

An option with a validator is checked while the configuration is parsed, and an invalid value stops the service starting rather than being silently replaced by the default.

Evidence

internal/config/options.go:51 (the validator field); internal/config/validators.go.

MINIFLUX-325Numeric lower bounds

Options whose value must be positive carry an explicit lower bound - the refresh batch size, the cleanup frequency and the cleanup batch size are each at least 1, and the media proxy timeout at least one second.

Evidence

internal/config/options.go:103-133, :144-151 and :362-369, all using validateGreaterOrEqualThan.

MINIFLUX-326Enumerated options

An option with a fixed set of permitted values is checked against that set, so MEDIA_PROXY_MODE accepts only none, http-only or all.

Evidence

internal/config/options.go:370-377, using validateChoices.

MINIFLUX-327Documented defaults

Every configuration key is documented in the manual page with its default value. The 87 keys defined in the code and the keys described in miniflux.1 correspond exactly.

Evidence

Compared mechanically: the keys in internal/config/options.go and the .B entries in miniflux.1 are the same set, with no key defined but undocumented.

Note

The stated defaults were compared against the code's own default values and agreed in every case checked. This is unusually good for a project of this size and is worth preserving: the manual page is trustworthy as a specification of the configuration surface.

Linked Resources
Miniflux Manual Page MINIFLUX-MANUAL-PAGE miniflux.1 in this repository

12.2Command-line operations

MINIFLUX-328Available operations

Beyond running the service, the binary performs sixteen operations from the command line: reporting its version and build information, running database migrations, creating an administrator, resetting a password, flushing sessions, resetting feed errors, resetting feed check times, refreshing every feed once, running the cleanup tasks once, exporting an account's feeds, dumping the configuration, probing an endpoint's health, and enabling debug logging.

Evidence

internal/cli/cli.go:60-78.

MINIFLUX-329Migrations are explicit

Database migrations do not run automatically at start-up. They run when -migrate is given, or when RUN_MIGRATIONS is enabled, which is off by default.

Evidence

internal/cli/cli.go:64; internal/config/options.go, key RUN_MIGRATIONS, defaulting to 0.

Note

The schema is maintained as an ordered list of 135 migrations in internal/database/migrations.go. The individual migrations are out of scope for this document; what is in scope is that applying them is a deliberate act.

MINIFLUX-330Administrator creation from configuration

An administrator can be created at start-up from ADMIN_USERNAME and ADMIN_PASSWORD when CREATE_ADMIN is enabled. It is off by default.

Evidence

internal/cli/create_admin.go; internal/config/options.go, keys CREATE_ADMIN, ADMIN_USERNAME, ADMIN_PASSWORD.

MINIFLUX-331Interactive credential entry

Creating an administrator or resetting a password without supplying credentials prompts for them on the terminal rather than failing.

Evidence

internal/cli/ask_credentials.go, used by create_admin.go and reset_password.go.

MINIFLUX-332One-shot refresh

-refresh-feeds refreshes feeds once and exits, without starting the HTTP service. This is how Miniflux is run from an external scheduler instead of its own.

Evidence

internal/cli/refresh_feeds.go; complements DISABLE_SCHEDULER_SERVICE.

MINIFLUX-333One-shot cleanup

-run-cleanup-tasks runs the retention and cleanup steps once and exits, performing exactly what a scheduled run performs.

Evidence

internal/cli/cleanup_tasks.go:16 (runCleanupTasks), shared by both the scheduled and the command-line paths.

MINIFLUX-334Health check client

-healthcheck probes an endpoint and exits with a status reflecting the result, so the same binary serves as its own container health check.

Evidence

internal/cli/health_check.go.

MINIFLUX-335Short option aliases

Three options have single-letter aliases: -i for -info, -v for -version, and -c for -config-file. Each alias is registered against the same variable as its long form, so the two are interchangeable.

Evidence

internal/cli/cli.go:60-72.

Note

The manual page documents a fourth pair, -h, -help, at miniflux.1:14. That one is not registered in cli.go; it is supplied by Go's flag package. A reimplementation not using that package has to provide it explicitly.

Linked Resources
Miniflux Manual Page MINIFLUX-MANUAL-PAGE miniflux.1 in this repository

12.3Health and observability

MINIFLUX-336Liveness probes

/liveness and /healthz answer 200 OK whenever the process is running, without touching the database.

Evidence

internal/http/server/healthcheck.go:13-16; routed at internal/http/server/routes.go:61-62.

MINIFLUX-337Readiness probes

/readiness, /readyz and /healthcheck answer 200 OK only when the database responds, and otherwise 503 Service Unavailable with the connection error quoted.

Evidence

internal/http/server/healthcheck.go:18-27; routed at internal/http/server/routes.go:24 and :63-64.

Note

The error message includes the database driver's own text. That can name the host and user from the connection string, so the readiness endpoint is not safe to expose publicly.

MINIFLUX-338Probe path placement

The four probes at the root of the server are served outside the configured base path and are always reachable, while /healthcheck is served beneath the base path alongside the application.

Evidence

internal/http/server/routes.go:57-70; the comment states the intent - these routes do not take the base path into consideration.

MINIFLUX-339Metrics endpoint

A Prometheus metrics endpoint is served at /metrics when METRICS_COLLECTOR is enabled. It is disabled by default and the route is not mounted at all when disabled.

Evidence

internal/http/server/routes.go:41-43; internal/http/server/metrics.go:17-19.

MINIFLUX-340Metrics network restriction

The metrics endpoint is served only to clients whose address falls inside METRICS_ALLOWED_NETWORKS, which defaults to loopback. A client outside those networks is answered with 404 Not Found rather than a refusal, so the endpoint's existence is not disclosed.

Evidence

internal/http/server/metrics.go:20-27 and :74.

MINIFLUX-341Metrics credentials

When METRICS_USERNAME and METRICS_PASSWORD are set, the metrics endpoint additionally requires HTTP Basic credentials, and a request without them is refused with the attempt recorded.

Evidence

internal/http/server/metrics.go:37-46.

MINIFLUX-342Collected metrics

The metrics collected include the duration of scraper requests, labelled by success or failure, and the duration of entry archiving, labelled by entry status.

Evidence

internal/metric/; recorded at internal/reader/processor/processor.go:120-126 and internal/cli/cleanup_tasks.go:33-35.

MINIFLUX-343Metric collection cost

Timings are recorded only when the metrics collector is enabled, so an installation without metrics does not pay for the measurement.

Evidence

internal/reader/processor/processor.go:120 and internal/cli/cleanup_tasks.go:33, both guarded by HasMetricsCollector.

MINIFLUX-344Logging configuration

Logging is written to stderr by default, at info level, in a human-readable format. The destination, level and format are each configurable, and -debug raises the level for one run.

Evidence

internal/config/options.go, keys LOG_FILE, LOG_LEVEL, LOG_FORMAT, LOG_DATE_TIME; internal/cli/logger.go.

MINIFLUX-345Service supervision

When run under a supervising init system, the service notifies it once it is ready and sends periodic watchdog notifications. The watchdog is enabled by default.

Evidence

internal/systemd/; internal/config/options.go, key WATCHDOG, defaulting to 1.

12.4Serving

MINIFLUX-346Listen address

The service listens on LISTEN_ADDR, 127.0.0.1:8080 by default, so an unconfigured installation is reachable only from the machine it runs on.

Evidence

internal/config/options.go, key LISTEN_ADDR.

MINIFLUX-347Base path support

When a base path is configured, the whole application is served beneath it and the prefix is stripped before routing. When it is empty the application is served at the root.

Evidence

internal/http/server/routes.go:66-71.

MINIFLUX-348Request timeout

An inbound request is given HTTP_SERVER_TIMEOUT, 300 seconds by default - considerably longer than the outbound fetch timeout, because a request may trigger a refresh of many feeds.

Evidence

internal/config/options.go, key HTTP_SERVER_TIMEOUT; applied in internal/http/server/server.go.

MINIFLUX-349Maintenance mode

While maintenance mode is enabled, every request beneath the base path is answered with the maintenance message and nothing else: the web interface, the REST API, the Fever and Google Reader endpoints, the metrics endpoint and /healthcheck are all replaced. The four probes at the root of the server are unaffected.

Evidence

internal/http/server/routes.go:49-55, which replaces the whole application handler; the root probes are registered separately at :61-64.

Note

The maintenance response carries status 200 and no content type. A reimplementation answering 503 with a Retry-After header would be a behaviour change rather than a like-for-like port.

Note

The two families of health route therefore diverge under maintenance: /healthcheck returns the maintenance message, while /healthz, /readyz, /liveness and /readiness keep reporting the real state. An orchestrator configured against the wrong one will not notice maintenance mode.

MINIFLUX-350Maintenance message

The maintenance message is set by MAINTENANCE_MESSAGE and defaults to Miniflux is currently under maintenance.

Evidence

internal/config/options.go, key MAINTENANCE_MESSAGE.

MINIFLUX-351HTTP service switch

Setting DISABLE_HTTP_SERVICE starts the process without an HTTP listener, so an installation can run only the background scheduler.

Evidence

internal/config/options.go, key DISABLE_HTTP_SERVICE; consulted in internal/cli/daemon.go.

MINIFLUX-352Transport security

The service can terminate TLS itself, either from a supplied certificate and key or from an automatically obtained certificate for CERT_DOMAIN. Strict transport security is applied by default and is turned off by DISABLE_HSTS.

Evidence

internal/http/server/tls_certificate_loader.go; internal/config/options.go, keys HTTPS, CERT_FILE, KEY_FILE, CERT_DOMAIN, DISABLE_HSTS.

MINIFLUX-353Database connection pool

The database connection pool holds between DATABASE_MIN_CONNS and DATABASE_MAX_CONNS connections, 1 and 20 by default, and a connection is retired after DATABASE_CONNECTION_LIFETIME, five minutes by default.

Evidence

internal/config/options.go, the three DATABASE_ keys; applied in internal/database/.

12.5Presentation

MINIFLUX-354Interface languages

The interface is available in 23 languages, each held as a translation catalogue compiled into the binary. An account's language must be one of them; any other value is refused with error.invalid_language.

Evidence

internal/locale/translations/, 23 catalogue files; internal/locale/locale.go (AvailableLanguages); internal/validator/user.go:199-205.

Note

The README says 20 languages and its list omits Arabic, Galician and Korean, all three of which have catalogues. The definition states what the code carries; whether the README's count or its list is the thing to correct is for the reviewer to decide.

MINIFLUX-355Theme selection

An account's theme must be one of the themes the application defines; any other value is refused with error.invalid_theme.

Evidence

internal/validator/user.go:191-197; the set at internal/model/theme.go.

MINIFLUX-356Timezone validation

An account's timezone must be one the system recognises; any other value is refused with error.invalid_timezone. Timestamps shown to a reader are converted into it.

Evidence

internal/validator/user.go:207-212; internal/timezone/.

MINIFLUX-357Custom stylesheet and script

An account may supply its own stylesheet and its own script, which are served with the interface for that account only.

Evidence

internal/model/user.go, the Stylesheet and CustomJS fields.

Note

The README states that the content security policy blocks inline scripts and permits only application JavaScript. How a per-account script is reconciled with that policy was not established, and it is worth confirming before reimplementing either.

MINIFLUX-358External font hosts

An account may name additional hosts from which fonts may be loaded, validated as a domain list and refused with error.settings_invalid_domain_list when malformed.

Evidence

internal/validator/user.go:149; internal/model/user.go, the ExternalFontHosts field.

MINIFLUX-359Reading speed preferences

An account's default and CJK reading speeds are positive numbers; a value of zero or less is refused with error.settings_reading_speed_is_positive.

Evidence

internal/validator/user.go:156-161.

MINIFLUX-360Media playback rate

An account's media playback rate must fall within a permitted range; a value outside it is refused with error.settings_media_playback_rate_range.

Evidence

internal/validator/user.go:259-264.

MINIFLUX-361Enumerated display preferences

The entry sort order, sort direction, category sort order, display mode, gesture navigation and default home page are each checked against a fixed set, and an unrecognised value is refused with its own message rather than silently defaulting.

Evidence

internal/validator/user.go:223-258.

MINIFLUX-362YouTube embedding

YouTube videos are embedded through www.youtube-nocookie.com by default. An alternative front end can be named by INVIDIOUS_INSTANCE, which defaults to yewtu.be, or the embedding address overridden entirely by YOUTUBE_EMBED_URL_OVERRIDE.

Evidence

internal/config/options.go:65 (youTubeEmbedDomain) and the keys INVIDIOUS_INSTANCE and YOUTUBE_EMBED_URL_OVERRIDE.

External Resources

Name Document Version URL Usage
Fever API Specification API version 3 https://web.archive.org/web/20161217042229/https://feedafever.com/api MINIFLUX-290, MINIFLUX-291, MINIFLUX-292
MathML Core W3C Candidate Recommendation https://w3c.github.io/mathml-core/ MINIFLUX-185
Miniflux Manual Page miniflux.1 in this repository https://miniflux.app/docs/configuration.html MINIFLUX-242, MINIFLUX-254, MINIFLUX-327, MINIFLUX-335, MINIFLUX-94
OAuth 2.0 for Native Apps - PKCE RFC 7636 https://www.rfc-editor.org/rfc/rfc7636 MINIFLUX-21, MINIFLUX-22
OpenID Connect Discovery 1.0 https://openid.net/specs/openid-connect-discovery-1_0.html MINIFLUX-20
OPML 2.0 Specification 2.0 https://opml.org/spec2.opml MINIFLUX-277, MINIFLUX-52, MINIFLUX-53
RE2 Syntax Go regexp/syntax https://github.com/google/re2/wiki/Syntax MINIFLUX-161, MINIFLUX-162, MINIFLUX-47
RFC 4287 - The Atom Syndication Format RFC 4287 https://www.rfc-editor.org/rfc/rfc4287 MINIFLUX-126
RFC 9111 - HTTP Caching RFC 9111 https://www.rfc-editor.org/rfc/rfc9111 MINIFLUX-116, MINIFLUX-76, MINIFLUX-77, MINIFLUX-97
RSS 2.0 Specification 2.0 https://www.rssboard.org/rss-specification MINIFLUX-125, MINIFLUX-147, MINIFLUX-148