ADR-0035: Video Visibility Enum (FEED, COLLECTION_ONLY, HIDDEN) Replaces is_hide¶
Metadata¶
Status: Accepted (2026-10-30) · Date: 2026-10-30 · Deciders: nguyenhuuca · Tags: api, database, frontend Related PRD: PRD-collection-only-videos · Supersedes: N/A · Superseded By: N/A
Tech Strategy: ✅ Follows Golden Path (JPA/Hibernate, Liquibase, Guava FeedCache, explicit admin controller). No new dependency.
Context¶
- The owner wants research videos out of the feed but playable from collections (PRD Problem Statement). Today a video has one visibility switch,
video_sources.is_hide:false: in the feed, search and collections;true: invisible everywhere, collections included (VideoCollectionItemRepository.VISIBLE).
is_hideis read in many places. About 20 references in 10 non-test files, backend and frontend:- the feed query
findAllByIsHideAndStatusOrderByPriorityDescCreatedAtDesc(StreamVideoServiceImpl.java:87-93); getVideoById, the collection and reaction checksexistsByIdAndIsHideAndStatus;incrementViewCount,WatchHistoryRepository, the HLS playlist check;PATCH /admin/videos/{id}/visibilitywith body{hidden},AdminVideoDto.hiddenand the Admin videos table.
- the feed query
- The feed is served from
FeedCache(Guava, 30 s TTL). Admin changes that affect the feed callfeedCache.invalidate()(priority, HLS). - The feed has a partial index
idx_video_sources_feedwithWHERE is_hide = false AND status = 'PUBLISHED'(202610240002-video-sources-feed-index.sql). - Imported videos get their row later, in two places. The import worker only uploads the file to Drive and stores
drive_file_idon the job. Thevideo_sourcesrow is created afterwards:- by the Drive scheduler, through
VideoStorageServiceImpl.saveInfo(builder +save, defaultis_hide = false); - or by a force sync, through
upsertInfo→VideoSourceRepository.upsertDriveSource, which INSERTs withis_hide = falseand, onON CONFLICT, keeps the moderation columns (is_hide, status, priority).
- by the Drive scheduler, through
- The PRD requires (FR-13..FR-16) the setting to come from the Import form and be written at INSERT time, so a collection-only video never appears in the feed.
- Deployment. The backend is deployed by copying the JAR to the VPS and restarting it (
funnyapp-ci.ymldeploy job). Old and new backend never run side by side, and the owner accepts a short downtime (2026-10-30). Liquibase runs on startup of the new JAR. - The frontend deploys separately (
deploy-web.yml, triggered bywebapp/**). For a few minutes the old frontend can talk to the new backend, or the reverse.
The decision: how to model "collection-only" next to "hidden".
Decision Drivers¶
- Invalid states should not be representable: a video is in exactly one visibility state.
- Hidden must keep meaning "gone everywhere", with no regression in the places that read visibility today.
- Downtime is acceptable (single VPS, owner-approved). There is no need for a rolling-safe expand/contract.
- Room to grow: a future state (for example private videos) should be one more value, not one more column.
- The feed query stays index-backed on the 1 vCPU VM.
- The setting can be chosen at import time and stored on the import job.
- The admin UI stays clear: one control, three states.
Considered Options¶
Option 1: New boolean column collection_only, is_hide unchanged¶
- Add
video_sources.collection_only BOOLEAN NOT NULL DEFAULT false. Only the feed query addsAND collection_only = false. - Precedence:
is_hide = truewins. - New endpoint
PATCH /admin/videos/{id}/collection-only.
| Pros | Cons |
|---|---|
| Smallest change: only the feed query and admin code | Two booleans give four combinations; "hidden + collection-only" is meaningless and needs a precedence rule |
| Additive column, safe even for a rolling deploy | Every future visibility query must remember both columns |
| A future state means a third column | |
| Two admin toggles for one concept |
Option 2: Replace is_hide with a visibility enum (FEED, COLLECTION_ONLY, HIDDEN)¶
- A
visibility VARCHAR NOT NULL DEFAULT 'FEED'column (JavaVideoVisibilityenum,@Enumerated(STRING)), backfilled fromis_hide:truebecomesHIDDEN,falsebecomesFEED.is_hideis then dropped in the same changeset. - Readers switch to:
- feed:
visibility = 'FEED'; - everywhere a video may play:
visibility <> 'HIDDEN'.
- feed:
PATCH /admin/videos/{id}/visibilitytakes{visibility}.
| Pros | Cons |
|---|---|
| One value per video: invalid states cannot exist | Touches about 20 references in 10 files, plus their tests |
| The feed rule and the playable rule each read one column | Not rolling-deploy safe; acceptable here because of the owner-approved downtime |
| A future state is one more enum value | Changes the /visibility request body and the admin DTO, so it needs a compatibility window with the separately deployed frontend |
| One admin control with three states | The partial index and the ON CONFLICT upsert must be rewritten |
Option 3: Option 2 in two releases (expand/contract)¶
- Add
visibility, dual-write both columns, switch reads, then dropis_hidein a second release.
| Pros | Cons |
|---|---|
| Zero downtime | Two releases and temporary dual-write code for a single-VPS app that accepts downtime |
Decision Outcome¶
Chosen Option: Option 2, a visibility enum (FEED, COLLECTION_ONLY, HIDDEN) that replaces is_hide in one release with a short downtime.
Rationale:
- It is the correct model. Visibility is a single property with three mutually exclusive values (invalid-state driver). There is no precedence rule to remember, and a fourth state later is one more value (room-to-grow driver).
- The main cost of Option 2 is the rolling deploy, and it does not apply. The backend is a single JAR on a VPS, and the owner accepts downtime (downtime driver). One Liquibase changeset adds the column, backfills it from
is_hide, recreates the index and dropsis_hide. - The remaining cost is touching ~20 references. That is mechanical and fully covered by existing tests that already assert hidden videos are excluded. Each of those tests is updated to the enum.
- Option 1 was the cheaper change, but it was rejected. It encodes one concept in two columns forever.
- Option 3 was rejected. It buys zero downtime nobody needs.
Compatibility window with the frontend. Backend and frontend deploy separately. For one release the backend therefore:
- also accepts the legacy body
{hidden: true|false}onPATCH /admin/videos/{id}/visibility, mapping it toHIDDEN|FEEDand rejecting a body that has both fields; - keeps a derived
hiddenfield (visibility == HIDDEN) inAdminVideoDtonext to the newvisibility.
A follow-up removes both once the new frontend is live. The exact mechanics belong in the plan.
Import jobs store a visibility limited to FEED or COLLECTION_ONLY (default FEED). When saveInfo or upsertInfo creates the video_sources row, it copies the visibility of the job found by drive_file_id, or uses FEED when there is no job (plain Drive sync). On ON CONFLICT the existing visibility is kept, like the other moderation columns today. Approved suggestions create FEED jobs.
Quantified Impact¶
| Metric | Before | After | Notes |
|---|---|---|---|
| Columns describing visibility | 1 (is_hide) |
1 (visibility) |
Option 1 would make it 2 |
| References changed | — | ~20 in 10 files + tests | Mechanical rename of the predicate |
| Releases needed | — | 1 backend + 1 frontend, then a small cleanup | Option 3 would need 2 backend releases with dual-write |
| Downtime | — | Backend restart + migration, expected under a minute | Owner-approved; video_sources is small |
| Feed query | Partial index scan | Partial index scan | Index predicate becomes visibility = 'FEED' AND status = 'PUBLISHED'; verified with EXPLAIN in the plan |
| Time for a change to reach the feed | — | Next request (cache invalidated), ≤ 30 s worst case | Same as priority and HLS changes |
Consequences¶
Positive:
- One column, one meaning.
- The feed reads
visibility = 'FEED'. - Collections, watch history, direct links, views, reactions and HLS read
visibility <> 'HIDDEN', so collection-only videos keep working there.
- The feed reads
- Feed search, the Explore hero and the Library "Add videos" picker exclude collection-only videos automatically, because they all read the feed list.
- Import jobs carry the visibility, so a collection-only import is never in the feed, not even between INSERT and an admin change.
- The Admin videos table gets one three-state control instead of a hidden checkbox plus a second toggle.
Negative:
- About 20 references and their tests change in one go. Review must check that every former
is_hide = falsebecomesvisibility <> 'HIDDEN', except the feed, which becomesvisibility = 'FEED'. is_hideis dropped. Rollback to the previous JAR needs a reverse migration (Liquibase rollback block) or a DB restore, not just redeploying the old JAR.- There is a temporary compatibility code path (legacy
{hidden}body, derivedhiddenDTO field) until the cleanup follow-up. - The client must handle a video that exists but is not in the feed list (PRD FR-9 deep-link fallback).
Risks:
- A former
is_hide = falsepredicate is mapped tovisibility = 'FEED'by mistake, and collection-only videos disappear from collections or history. Mitigation:- tests per surface (collections, history,
GET /video-stream/{id}, reactions, views, HLS) using aCOLLECTION_ONLYfixture; - a grep check that no
is_hide/isHideremains.
- tests per surface (collections, history,
- The old frontend sends
{hidden}after the backend deploys. Mitigation: the legacy body is accepted for one release, as described above. - A bad migration on prod. Mitigation:
- take a DB backup before deploy;
- the changeset has a
rollbackblock that recreatesis_hidefromvisibility; - test the migration on a prod-like dump first.
- The owner reads collection-only as private. Mitigation: the PRD Out of Scope states it, and the admin control has a tooltip that says so.
Validation¶
- [ ] Migration test:
is_hide = truebecomesHIDDENandfalsebecomesFEED;is_hideis gone; the rollback block restores it - [ ] Feed excludes
COLLECTION_ONLYandHIDDEN - [ ] Collections, watch history,
GET /video-stream/{id}, reactions, views and HLS acceptCOLLECTION_ONLYand rejectHIDDEN - [ ] Import with
COLLECTION_ONLYcreates the row with that value on first INSERT; re-import keeps the existing value - [ ]
PATCH /admin/videos/{id}/visibilityaccepts{visibility}and the legacy{hidden}, and rejects both together - [ ] No
is_hide/isHidereference remains inapi/src/mainorwebapp/src(except the migration and the legacyhiddencompatibility code) - [ ]
EXPLAINof the feed query uses the recreated partial index - [ ] Security review:
/visibilitykeeps its role guard and@AuditLog - [ ] Related plan document created:
docs/plans/plan-collection-only-videos.md
Links¶
- Related PRD
- Implementation Plan (to be written)
- ADR-0019: video import worker
- ADR-0031: opt-in HLS streaming (
FeedCacheinvalidation pattern)
Changelog¶
| Date | Author | Change |
|---|---|---|
| 2026-10-30 | nguyenhuuca | Initial draft (boolean collection_only) |
| 2026-10-30 | nguyenhuuca | Switched to the visibility enum: single-VPS deploy, owner accepts downtime |