syncworker

package
v0.6.9 Latest Latest
Warning

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

Go to latest
Published: Oct 4, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package syncworker isolates subtitle-sync computation in a supervised one-shot child process (P13). Sync is the engine's most memory-intensive work (PCM decode + alignment inside a 1 GiB no-swap container); running it in a same-binary `subflux sync-worker` child means a memory blowup is killed by the kernel OOM killer as the LARGEST-badness process — the fat child — while the server keeps serving. One job per process, versioned JSON over stdin/stdout, kill-on-cancel, concurrency-one admission.

The protocol carries the raw inputs of the two heavy strategies (reference-based and audio-based sync) and returns a wire copy of subsync.SyncResult. Both sides convert to/from the real subsync types, so the parent applies the SAME Applied()/ShouldApply() logic it always did — no duplicated decision rules on the wire.

Index

Constants

View Source
const (
	// OpReference aligns subtitle data against an embedded reference track
	// (syncing.SyncAgainstReference).
	OpReference = "reference"
	// OpAudio aligns subtitle data against the audio track
	// (syncing.SyncFromAudio).
	OpAudio = "audio"
)

Op names for Request.Op.

View Source
const ProtocolVersion = 1

ProtocolVersion guards the parent/child JSON contract. Parent and child are the same binary, so a mismatch can only mean the executable was replaced while a request was in flight (upgrade race); the child answers with an error response rather than guessing.

Variables

View Source
var ErrAdmissionRefused = errors.New("sync job admission refused")

ErrAdmissionRefused reports that the admission hook refused the run (a cancel won the race before the worker spawned).

Functions

func RunWorker

func RunWorker(ctx context.Context, stdin io.Reader, stdout io.Writer) int

RunWorker executes exactly one sync job read from stdin and writes the response to stdout. Called by the hidden `subflux sync-worker` subcommand. The exit code reflects PROTOCOL health only (0 even when the sync found nothing); the parent judges the job by the JSON response. ctx cancellation (parent kill, signal) aborts the underlying ffmpeg/alignment work.

Types

type AdmissionHook added in v0.5.0

type AdmissionHook func() bool

AdmissionHook is invoked exactly once, at acquisition of the single execution slot and before the worker spawns. Returning false REFUSES the admission: the slot is released, no work runs, and the job reports OutcomeCancelled. A nil hook admits unconditionally.

type Client

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

Client runs sync jobs in supervised one-shot `subflux sync-worker` child processes. It implements syncing.SyncExec, so the Syncer, the engine's audio fallback, and the manual sync handlers all route their heavy computation through it transparently.

Admission is concurrency-one (the P13 queue, subsuming the sync-semaphore side finding): a season sync of N episodes runs at most one alignment at a time, and manual jobs queue behind automatic ones. Failure is degradation, never escalation: a worker death (OOM kill, crash, timeout) is WARN-logged and reported as a no-change result — the subtitle stays unsynced, the download proceeds, the server keeps serving.

func NewClient

func NewClient() (*Client, error)

NewClient builds the process-isolation client. It resolves the current executable once; construction fails only when the running binary's path cannot be determined (in which case the caller should fall back to in-process sync).

func NewInProcess added in v0.5.0

func NewInProcess() *Client

NewInProcess builds a Client whose jobs run inside THIS process instead of a child: the fallback for when the running executable's path cannot be resolved. Same admission slot, budget, and typed outcomes; no process isolation (the pre-P13 posture — an OOM takes the server with it).

func (*Client) Audio

func (c *Client) Audio(ctx context.Context, data []byte, videoPath, subtitlePath string) subsync.SyncResult

Audio implements syncing.SyncExec: audio-based sync in a worker. A thin projection of the typed core, like Reference.

func (*Client) Reference

func (c *Client) Reference(ctx context.Context, data []byte, videoPath, lang string, minConf float64) subsync.SyncResult

Reference implements syncing.SyncExec: reference-track sync in a worker. A thin projection of the typed core — every non-result outcome degrades to the documented no-change result.

func (*Client) RunAudio added in v0.5.0

func (c *Client) RunAudio(ctx context.Context, data []byte, videoPath, subtitlePath string, hook AdmissionHook) RunOutcome

RunAudio runs one audio-sync job through the typed core: admission on the single slot (hook at acquisition), unconditional budget, typed outcome.

type Outcome added in v0.5.0

type Outcome string

Outcome discriminates how one worker job ended, each by its own NAMED signal: the budget timer's cause sentinel, the job context, or the process exit state. Nothing is inferred from error text.

const (
	// OutcomeResult: the worker delivered a versioned JSON response with
	// exit 0 and no job error.
	OutcomeResult Outcome = "result"
	// OutcomeTimeout: the analysis budget (maxWorkerRuntime) fired —
	// identified by its own cause sentinel, never inferred from ctx.Err.
	OutcomeTimeout Outcome = "timeout"
	// OutcomeCancelled: the job context was cancelled (stop request,
	// shutdown), or the admission hook refused the run.
	OutcomeCancelled Outcome = "cancelled"
	// OutcomeCrash: everything else — non-zero exit, protocol error, spawn
	// failure, or a worker-reported job error.
	OutcomeCrash Outcome = "crash"
)

Job outcomes.

type Request

type Request struct {
	Op            string  `json:"op"`
	VideoPath     string  `json:"video_path"`
	SubtitlePath  string  `json:"subtitle_path,omitempty"`
	Lang          string  `json:"lang,omitempty"`
	Data          []byte  `json:"data"`
	Version       int     `json:"version"`
	MinConfidence float64 `json:"min_confidence,omitempty"`
}

Request is the parent->child job description, one per process invocation.

type Response

type Response struct {
	Error   string         `json:"error,omitempty"`
	Result  WireSyncResult `json:"result"`
	Version int            `json:"version"`
}

Response is the child->parent result envelope. Error is set for protocol or infrastructure failures; strategy-level "no sync found" is NOT an error (it travels as a MethodNone result, exactly like the in-process calls).

type RunOutcome added in v0.5.0

type RunOutcome struct {
	Err     error
	Outcome Outcome
	Result  subsync.SyncResult
}

RunOutcome is the typed core's answer. Result is meaningful only for OutcomeResult; Err carries the timeout/cancel/crash detail.

type WireCue

type WireCue struct {
	Text    string `json:"t"`
	StartNs int64  `json:"s"`
	EndNs   int64  `json:"e"`
}

WireCue is one subtitle cue on the wire (durations in nanoseconds).

type WireSyncResult

type WireSyncResult struct {
	Method     string    `json:"method"`
	Cues       []WireCue `json:"cues,omitempty"`
	OffsetMs   int64     `json:"offset_ms"`
	Confidence float64   `json:"confidence"`
	Rate       float64   `json:"rate"`
}

WireSyncResult is the JSON projection of subsync.SyncResult.

Jump to

Keyboard shortcuts

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