Feature Specification: HLS Streaming for Selected Videos¶
Metadata¶
Status: Implemented (2026-10-24) Author: nguyenhuuca Date: 2026-10-24 Related PRD: PRD-hls-streaming Related ADR: ADR-0031 Sequence diagrams: sequence-hls-streaming
Overview¶
- Opt-in per video: the SUPER_ADMIN turns HLS on or off for one Drive video at a time.
- Transcoding: an in-process worker stream-copies the video's
.fullfile intovideo-cache/hls/{fileId}/, one job at a time. - Playback:
- Video DTOs carry
hlsUrlonly when the Harness flaghls_streaming_enabledis on and the rendition is READY. - The player uses
hlsUrlwhen it is set and falls back to the existing Range URL (embedLink) on any failure. - Range playback, the Guava cache and the download paths keep working as today.
- Video DTOs carry
Business Rules¶
BR-1: Drive videos only¶
- HLS can be turned on only for
VideoSourcerows withsource_type = 'google_drive'. - Every other row keeps
hls_status = NONEand its admin DTO showshlsStatus = null.
BR-2: SUPER_ADMIN only¶
- Only the SUPER_ADMIN can turn HLS on or off.
- ADMIN can see the status but cannot change it.
BR-3: Status machine¶
hls_status moves only along these edges. Any other change is a bug.
| From | To | Trigger |
|---|---|---|
| NONE, ERROR | PENDING | PUT (turn on / retry) |
| PENDING | PROCESSING | Worker claims the job (atomic UPDATE … WHERE hls_status = 'PENDING') |
| PROCESSING | READY | FFmpeg exit 0, playlist exists, temp directory renamed |
| PROCESSING | ERROR | Any failure listed in BR-9 |
| PROCESSING | PENDING | Startup recovery (BR-11) |
| READY, ERROR | PENDING | .full replaced by a new download (BR-10) |
| READY | ERROR | Startup check finds the output directory missing (BR-11) |
| any | NONE | DELETE (turn off) |
BR-4: One job at a time¶
- At most one FFmpeg or ffprobe process runs at any moment (
Semaphore(1)). - Jobs are taken oldest first, ordered by
updated_at.
BR-5: Codec allowlist¶
ffprobemust report video codech264.- Audio must be
aacormp3, or there must be no audio stream. - Anything else ends the job with
UNSUPPORTED_CODEC. No re-encoding is done.
BR-6: Disk guard¶
- Before FFmpeg starts, the usable space on the
video-cachefile store must be at leastsize(.full) + app.hls.min-free-disk-bytes. The default reserve is 1 GB. - If it is lower, the job ends with
DISK_FULL.
BR-7: Output and timeout¶
- FFmpeg runs with
-c copy -f hls -hls_time 6 -hls_playlist_type vod -hls_segment_filename seg_%d.tsand writes intovideo-cache/hls/{fileId}.tmp/. - The job is READY only after all of these:
- FFmpeg exits 0;
playlist.m3u8exists;- the directory has been renamed to
video-cache/hls/{fileId}/.
- A run longer than
app.hls.timeout(default 10 min) is killed and ends withTIMEOUT.
BR-8: hlsUrl offer rule¶
hlsUrlis set when both hold:FeatureFlagService.isEnabled("hls_streaming_enabled", false)is true;hls_status = READY.
- Otherwise it is
null. - The flag is read once per request.
- The rule applies to every place that builds a feed-shaped DTO (
Converter.toVideoDto): the feed list, video detail and public collection videos.
BR-9: Error codes¶
hls_error holds one of these codes. It is null unless the status is ERROR.
| Code | Condition |
|---|---|
SOURCE_MISSING |
video-cache/{fileId}.full does not exist when the job starts |
FFMPEG_NOT_FOUND |
ffprobe or ffmpeg cannot be started |
UNSUPPORTED_CODEC |
BR-5 fails |
DISK_FULL |
BR-6 fails |
TIMEOUT |
BR-7 timeout |
FFMPEG_FAILED |
Non-zero exit code, or no playlist after exit 0 |
OUTPUT_MISSING |
Startup check: READY but the directory is gone |
BR-10: Source replaced¶
When DriveVideoDownloaderImpl writes a new .full, still holding the file lock, it:
- always deletes
video-cache/hls/{fileId}/if it exists; - if the status was READY or ERROR, sets it to PENDING and wakes the worker.
BR-11: Startup recovery¶
On ApplicationReadyEvent, the worker:
- sets every PROCESSING row to PENDING;
- deletes every
video-cache/hls/*.tmp/directory; - sets every READY row whose directory is missing to ERROR
OUTPUT_MISSING; - deletes every
video-cache/hls/{fileId}/directory whose row is missing or not READY (orphans left by a DELETE that ran while a download held the lock); - then wakes up.
BR-12: Cleanup¶
video-cache/hls/{fileId}/ is deleted in each of these cases:
- DELETE on the HLS endpoint;
- admin video delete (
AdminVideoServiceImpl.deleteVideo, always, whatever thedeleteLocalFileflag); - BR-10.
The deletion runs under DriveFileLocks. The .full file is touched only by the existing delete-local-file option.
BR-13: Public serving¶
- Playlist: served only when all of these hold:
- status READY;
- video
PUBLISHED; - video not hidden;
- the file exists.
- Segment: served when the name is valid and the file exists in the READY directory. There is no DB lookup per segment.
Functional Requirements¶
FR-1: Schema¶
video_sources must get the columns hls_status and hls_error (see Database Changes). The VideoSource entity must map them with a new HlsStatus enum.
FR-2: Admin toggle endpoints¶
The system must expose PUT and DELETE /v1/funny-app/admin/videos/{id}/hls, as described in API Changes.
- Both are idempotent.
- Both are annotated with
@AuditLog("enableVideoHls")and@AuditLog("disableVideoHls"). - A PUT that sets PENDING must call
HlsTranscodeWorker.wakeUp().
FR-3: Worker¶
HlsTranscodeWorker must follow VideoImportWorker:
wakeUp()on a virtual thread;- a
@Scheduled(cron = "0 */5 * * * *")poll; - startup recovery (BR-11);
Semaphore(1).
For each job it must take these steps in this order:
- claim the file lock in
DriveFileLocks; if the file is busy, leave the job PENDING; - claim the DB row;
- check that the source exists;
- run ffprobe;
- run the disk guard;
- run FFmpeg;
- re-read the status;
- publish, or clean up;
- release the lock.
Every command must be built with ProcessBuilder(List<String>), never a shell string. fileId must pass the existing safe-id check before any path is built.
FR-4: Publish guard¶
After FFmpeg exits, the worker must re-read the row.
- If the status is no longer PROCESSING (the owner turned it off, or the video was deleted), it must delete the temp directory and not publish.
- It must never overwrite NONE with READY.
FR-5: Public HLS endpoints¶
VideoStreamController must serve the playlist and the segments (see API Changes). It must:
- validate path variables before touching the file system;
- check that the resolved path stays inside
video-cache/hls/{fileId}/(CWE-22).
FR-6: DTO field¶
VideoDtomust gethlsUrl(String, nullable).- The value is
https://canh-labs.com/api/v1/funny-app/video-stream/hls/{fileId}/playlist.m3u8, the same host and prefix asembedLink, built inConverter. Converter.toVideoDtomust take the request's flag value as a parameter. It must not read the flag itself, per video.
FR-7: Admin DTO¶
AdminVideoDto must get hlsStatus (HlsStatus, null for non-Drive videos) and hlsError (String).
FR-8: Source replaced hook¶
DriveVideoDownloaderImpl must apply BR-10 after it moves a new .full into place. This covers both the scheduler and the force sync, because both go through it.
FR-9: Player¶
VideoPlayer must keep its single <video> element.
- When
video.hlsUrlis set:- If
canPlayType('application/vnd.apple.mpegurl')is non-empty (Safari/iOS), it setssrc = hlsUrl. - Otherwise, it loads
hls.jswithimport('hls.js'), checksHls.isSupported(), and attaches it. - If HLS is not supported, it uses the Range URL.
- If
- On a fatal HLS error, or a native
errorevent while on HLS: it destroys the instance, setssrcto the Range URL, and onloadedmetadatarestores the lastcurrentTimeand the play state. - It destroys the instance on unmount and whenever the video changes.
- Resume (
startAt), view counting and watch-history progress keep using the same element, with no other change.
FR-10: Swiper preload¶
VideoSwiper must not render the hidden Range preload <video> for upcoming videos that have hlsUrl.
Assumption: preloading the
.fullbytes for an HLS video wastes bandwidth. hls.js starts quickly enough from the playlist.
FR-11: Admin table¶
AdminVideoTable must add an HLS column for Drive videos:
- a status badge (
NONE,PENDING,PROCESSING,READY,ERROR); - the localized error reason as a tooltip on ERROR;
- for the SUPER_ADMIN only (
isSuperAdmin(role)), a toggle (on = PUT, off = DELETE).
While any row on the page is PENDING or PROCESSING, the admin videos query refetches every 5 s.
FR-12: Config¶
AppProperties must get an Hls section:
app.hls.min-free-disk-bytes, default1073741824;app.hls.timeout, default10m.
Both are bound in application.yaml with env overrides HLS_MIN_FREE_DISK_BYTES and HLS_TIMEOUT.
FR-13: Tech strategy¶
Add hls.js (exact version pinned in webapp/package.json) to the JavaScript table in .claude/rules/tech-strategy.md, citing ADR-0031.
API Changes¶
New Endpoints¶
PUT /v1/funny-app/admin/videos/{id}/hls¶
| Auth | JWT; @PreAuthorize("hasRole('SUPER_ADMIN') and @permissionServiceImpl.hasPermission(authentication.details.permissions, ADMIN)") (same as AdminDriveSyncController.java:55) |
| Body | none |
| Effect | NONE or ERROR → PENDING (clears hls_error) and wakes the worker. PENDING, PROCESSING or READY → no change |
Response 200:
| Status | Code | Condition |
|---|---|---|
| 400 | error.hls.notDriveVideo |
The row's source_type is not google_drive |
| 401 | — | No or invalid JWT |
| 403 | — | Caller is not SUPER_ADMIN, or lacks the ADMIN bit while enforcement is on |
| 404 | error.video.notFound |
No video_sources row with this id (CustomException with NOT_FOUND) |
DELETE /v1/funny-app/admin/videos/{id}/hls¶
| Auth | Same as PUT |
| Effect | Any status → NONE, hls_error = null. If DriveFileLocks.tryClaim(fileId) succeeds, deletes video-cache/hls/{fileId}/ and releases the lock. If the lock is held, the holder cleans up: a running job discards its output (FR-4), and a running download deletes the directory (BR-10). A running job is not killed |
Response 200: { "status": "SUCCESS", "data": { "id": 42, "hlsStatus": "NONE", "hlsError": null } }
| Status | Code | Condition |
|---|---|---|
| 400 | error.hls.notDriveVideo |
Not a Drive video |
| 401 / 403 | — | As for PUT |
| 404 | error.video.notFound |
Unknown id |
GET /v1/funny-app/video-stream/hls/{fileId}/playlist.m3u8¶
| Auth | Public (/v1/funny-app/video-stream/** in ALLOW_ALL_METHOD) |
fileId |
Must match ^[A-Za-z0-9_-]{1,128}$ |
| Status | Headers / body | Condition |
|---|---|---|
| 200 | Content-Type: application/vnd.apple.mpegurl, Cache-Control: no-cache, the playlist file |
BR-13 holds |
| 400 | empty | fileId fails the regex |
| 404 | empty | Unknown fileId, status not READY, video hidden or not PUBLISHED, or file missing |
GET /v1/funny-app/video-stream/hls/{fileId}/{segment}¶
| Auth | Public |
segment |
Must match ^seg_\d{1,5}\.ts$ |
| Status | Headers / body | Condition |
|---|---|---|
| 200 | Content-Type: video/mp2t, Cache-Control: public, max-age=31536000, immutable, Content-Length, file body via FileSystemResource |
File exists in video-cache/hls/{fileId}/ |
| 400 | empty | fileId or segment fails its regex |
| 404 | empty | File missing |
Modified Endpoints¶
GET /v1/funny-app/video-stream/list, GET /v1/funny-app/video-stream/{id}, GET /v1/funny-app/collections/{id}/videos¶
Each VideoDto gets one more field:
{ "id": 42, "fileId": "1AbC…", "embedLink": "https://canh-labs.com/api/v1/funny-app/video-stream/stream/1AbC…",
"hlsUrl": "https://canh-labs.com/api/v1/funny-app/video-stream/hls/1AbC…/playlist.m3u8" }
hlsUrl is null unless BR-8 holds. No other field changes.
GET /v1/funny-app/admin/videos¶
Each AdminVideoDto gets "hlsStatus": "READY" | … | null and "hlsError": "UNSUPPORTED_CODEC" | null.
Database Changes¶
New Tables¶
None.
Modified Tables¶
api/src/main/resources/db/changelog/sql/202610240001-video-source-hls.sql (picked up by includeAll):
-- HLS rendition state per video (ADR-0031). NONE until the SUPER_ADMIN turns HLS on.
ALTER TABLE video_sources
ADD COLUMN hls_status VARCHAR(20) NOT NULL DEFAULT 'NONE',
ADD COLUMN hls_error VARCHAR(40);
ALTER TABLE video_sources
ADD CONSTRAINT chk_video_sources_hls_status
CHECK (hls_status IN ('NONE', 'PENDING', 'PROCESSING', 'READY', 'ERROR'));
-- Worker queue lookups touch only the few in-flight rows.
CREATE INDEX idx_video_sources_hls_queue
ON video_sources (updated_at)
WHERE hls_status IN ('PENDING', 'PROCESSING');
The ALTER TABLE with a constant default is a metadata-only change in PostgreSQL 11+ (no table rewrite).
No Changes¶
video_access_stats, video_collection*, watch_history and every other table.
Security Requirements¶
Authentication¶
- The toggle endpoints need a valid JWT.
- The public HLS endpoints need none, like the Range endpoint. No token is ever put in an HLS URL (CWE-598).
Authorization¶
- PUT and DELETE are for the SUPER_ADMIN only, using the expression in API Changes.
GET /admin/videoskeeps its ADMIN+ access.- The playlist endpoint enforces BR-13, so a hidden or unpublished video is not served even if its
fileIdis known.
Data Validation¶
fileIdmust match^[A-Za-z0-9_-]{1,128}$andsegmentmust match^seg_\d{1,5}\.ts$.- After resolving, the path must still start with the normalized
video-cache/hls/{fileId}/(CWE-22). - FFmpeg and ffprobe arguments are a fixed list; only the validated path is inserted (CWE-78).
- Toggles are written to the audit log (
@AuditLog).
Sensitive Data¶
None. HLS files are the same public video bytes the Range endpoint already serves.
Caching Impact¶
| Cache | Impact |
|---|---|
VideoCacheImpl / ChunkIndexCacheImpl |
None. HLS files are served straight from disk via FileSystemResource, and the OS page cache keeps hot segments |
StatsCacheImpl |
None. HLS requests do not record cache hits or misses |
| HTTP / browser | Segments are immutable for a year. The playlist uses no-cache, so a re-transcode (BR-10) is picked up |
| Harness SDK | The flag is evaluated through the SDK's local cache, with no network call per request |
Frontend Changes¶
New Routes¶
None.
Modified Components¶
| File | Change |
|---|---|
webapp/src/utils/videoModel.js |
mapApiVideo adds hlsUrl: raw.hlsUrl || null |
webapp/src/components/video/VideoPlayer.jsx |
FR-9; HLS attach and fallback live in a new hook webapp/src/hooks/useHlsSource.js |
webapp/src/components/video/VideoSwiper.jsx |
FR-10 |
webapp/src/components/admin/AdminVideoTable.jsx |
FR-11: HLS column, badge, SUPER_ADMIN toggle |
webapp/src/api/admin.js |
enableVideoHls(id) → PUT /admin/videos/{id}/hls; disableVideoHls(id) → DELETE |
webapp/src/hooks/useAdmin.js |
useEnableVideoHls, useDisableVideoHls invalidate ['admin', 'videos']; the admin videos query gets refetchInterval: 5000 while any row is PENDING or PROCESSING |
webapp/src/i18n/locales/{en,vi}/admin.json |
colHls, hlsStatus.{NONE,PENDING,PROCESSING,READY,ERROR}, hlsError.{…BR-9 codes}, hlsToggleOn, hlsToggleOff |
webapp/package.json |
Add hls.js (exact version) |
State Management¶
| Query key | Change |
|---|---|
['videos', …] (useVideos, staleTime 5 min) |
Unchanged. Carries hlsUrl. A flag flip reaches a client at its next refetch |
['admin', 'videos', page, status] |
Unchanged key; conditional 5 s refetchInterval |
Event / Job Changes¶
Domain Events¶
None. The worker is woken by a direct wakeUp() call from the admin service and the downloader.
Scheduled Jobs¶
| Job | Schedule | Behaviour |
|---|---|---|
HlsTranscodeWorker.poll() |
0 */5 * * * * |
Drains PENDING jobs one by one (BR-4). It is a fallback for a missed wakeUp() or a job left PENDING because its file was locked |
HlsTranscodeWorker.onApplicationReady() |
Once at startup | BR-11 recovery, then wakeUp() |
Non-Functional Requirements¶
Performance¶
| Operation | Target |
|---|---|
| Transcode, 500 MB H.264 on the prod VM | < 30 s end to end (probe + guard + copy + rename) |
| Playlist request | p95 < 50 ms (one indexed row read + static file) |
| Segment request, time to first byte | p95 < 50 ms (static file, no DB) |
| Feed list with the flag | +< 5 ms vs today (one SDK evaluation per request) |
| PUT / DELETE toggle | p95 < 200 ms (excludes the transcode itself) |
Availability¶
- Range playback never depends on HLS. The flag off, ERROR, a missing file or an unsupported browser all lead to Range.
- A Harness outage means the flag reads
false, so everyone plays through Range.
Scalability¶
- One job at a time on one instance; this is a single-replica app (HPA 1–1).
- Disk is the limit, and the owner controls it per video. There is no automatic growth.
Edge Cases¶
EC-1: .full missing¶
PUT on a video whose .full has not been downloaded, or was deleted, results in PENDING, then ERROR SOURCE_MISSING. Playback stays Range.
EC-2: READY but the directory is gone¶
- The playlist returns 404, so the player falls back to Range.
- At the next startup the row becomes ERROR
OUTPUT_MISSING. - There is no self-healing: the owner retries with PUT.
EC-3: Hidden or unpublished video¶
- PUT is allowed.
- The feed already leaves the video out, and the playlist returns 404 while it is hidden or not PUBLISHED.
- Unhiding it makes the existing READY rendition available again with no re-transcode.
EC-4: Force sync or scheduler replaces .full¶
- Any old directory is deleted.
- For a READY or ERROR row, the status becomes PENDING and the worker is woken (BR-10).
- For NONE, PENDING or PROCESSING, the status does not change.
EC-5: PUT while PENDING, PROCESSING or READY¶
200 with the current status; there is no second job.
EC-6: DELETE while PROCESSING¶
- The status becomes NONE at once.
- FFmpeg runs to the end or to the timeout. FR-4 then deletes
.tmpand does not publish. - The final status stays NONE.
EC-7: File locked when the worker picks a job¶
The download or delete holds DriveFileLocks, so the job stays PENDING and is retried at the next wake-up or poll.
EC-8: Two concurrent PUTs¶
Both return 200 PENDING. The atomic claim UPDATE … WHERE hls_status = 'PENDING' lets exactly one worker run move it to PROCESSING.
EC-9: Restart during PROCESSING¶
BR-11: the row goes back to PENDING, the leftover .tmp is deleted, and the job runs again.
EC-10: Flag turned off while someone is watching¶
- The current playback continues, because files are still served.
- The next list fetch returns
hlsUrl = null, so that client uses Range from then on.
EC-11: Harness unreachable¶
isEnabled returns the default false, so hlsUrl is null everywhere.
EC-12: Fatal HLS error during playback¶
The player switches to the Range URL and resumes at the last currentTime. If it was playing, it keeps playing.
EC-13: Path traversal and bad names¶
fileId with .., /, %2F or other characters outside the regex, or a segment like ../x.ts or seg_1.m3u8, returns 400 with no file system access.
EC-14: Video without an audio stream¶
Allowed by BR-5. FFmpeg copies the video stream only.
EC-15: FFmpeg or ffprobe missing (e.g. K8s image)¶
ERROR FFMPEG_NOT_FOUND; Range keeps working.
EC-16: Delete a video with an HLS rendition¶
deleteVideo always removes video-cache/hls/{fileId}/ (BR-12), even when deleteLocalFile = false, so no orphan directory is left.
Acceptance Criteria¶
- [ ] Changeset
202610240001-video-source-hls.sqlapplies on an existing DB. Every existing row readshls_status = 'NONE',hls_error = NULL. - [ ] PUT as SUPER_ADMIN on a Drive video with status NONE → 200 PENDING. The worker runs, and the status reaches READY with
video-cache/hls/{fileId}/playlist.m3u8+seg_*.ts. - [ ] PUT as ADMIN → 403. PUT on a non-Drive row → 400
error.hls.notDriveVideo. PUT on an unknown id → 404. - [ ] PUT on ERROR → PENDING with
hls_errorcleared. PUT on PENDING, PROCESSING or READY → 200, unchanged. - [ ] DELETE → NONE and the directory is gone. DELETE during PROCESSING → the final status is NONE and no directory is published. DELETE never returns 409.
- [ ] HEVC source → ERROR
UNSUPPORTED_CODEC. Low disk (reserve set above free space in a test) → ERRORDISK_FULL, and FFmpeg is not started. - [ ] A timeout (set to 1 s in a test with a stub process) kills the process → ERROR
TIMEOUT, and.tmpis removed. - [ ] Only one FFmpeg process at a time, with 3 videos queued.
- [ ] Restart with a PROCESSING row → it becomes PENDING, then READY. A READY row with a deleted directory → ERROR
OUTPUT_MISSING. - [ ] Re-download of a READY video's
.full→ the status becomes PENDING and the old segments are deleted. - [ ] Flag on + READY →
hlsUrlis set in the list, the detail and the collection videos. Flag off, or not READY →hlsUrlis null. - [ ] Playlist for a hidden or unpublished READY video → 404. Segment with
..→ 400. Segment response hasvideo/mp2tand the immutableCache-Control. - [ ] Chrome desktop: an HLS video plays through hls.js (network shows
.m3u8+.ts, no/stream/). Safari/iOS: native HLS plays. - [ ] Forcing a fatal HLS error (e.g. deleting a segment mid-play) → playback continues through Range at about the same time.
- [ ] Resume (
startAt) and watch-history progress work for an HLS video like for a Range video. - [ ]
hls.jsis in a separate chunk. The main bundle size is unchanged (±1 KB). - [ ] Admin table: SUPER_ADMIN sees the toggle and ADMIN sees only the badge. The status refreshes on its own until READY or ERROR. Error reasons appear in EN and VI.
- [ ]
mvn verifygreen with coverage ≥ the threshold.npm run testandnpm run lintgreen.
Open Questions¶
None. All PRD and ADR questions are closed. Decisions from the spec Q&A (2026-10-24):
- the toggles are idempotent, and PUT on ERROR retries;
- the
app.hls.*config is separate from video-import; - the four edge cases EC-1..EC-4 are confirmed;
@AuditLogon the toggles;- the playlist is served only for PUBLISHED, non-hidden videos.
Assumption: there is no
app.hls.enabledkill switch for the worker. The Harness flag controls playback, and the owner controls transcoding per video.
Version History¶
| Date | Author | Change |
|---|---|---|
| 2026-10-24 | nguyenhuuca | Initial spec from PRD-hls-streaming + ADR-0031 |