video2ctx/reference/transcript-request-onion.html at main · devhims/video2ctx · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Transcript request sequence</title>
  <style>
    :root {
      color-scheme: light dark;
      --paper: #f7f6f2;
      --ink: #1d1d1b;
      --muted: #686761;
      --soft: #9a9890;
      --rule: #d8d5cd;
      --rule-strong: #827f77;
      --accent: #ee6a5b;
      --accent-tint: #fbe5e1;
      --link: #2e5aa8;
      --link-tint: #e7edf8;
    }
    @media (prefers-color-scheme: dark) {
      :root {
        --paper: #191917;
        --ink: #f2f0e9;
        --muted: #b9b6ad;
        --soft: #88857d;
        --rule: #393833;
        --rule-strong: #a7a39a;
        --accent: #ff8172;
        --accent-tint: #472824;
        --link: #9bbcff;
        --link-tint: #202d49;
      }
    }
    * { box-sizing: border-box; }
    body { margin: 0; background: var(--paper); color: var(--ink); font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
    main { max-width: 1240px; margin: 0 auto; padding: 32px 28px 24px; }
    h1 { margin: 0; font-size: 30px; line-height: 1.1; letter-spacing: -.025em; }
    p { margin: 8px 0 22px; color: var(--muted); font-size: 15px; }
    svg { display: block; width: 100%; height: auto; }
    .eyebrow { font: 600 11px ui-monospace, SFMono-Regular, Menlo, monospace; letter-spacing: .12em; fill: var(--accent); }
    .title { font: 650 24px Inter, ui-sans-serif, system-ui, sans-serif; letter-spacing: -.02em; fill: var(--ink); }
    .subtitle { font: 400 13px Inter, ui-sans-serif, system-ui, sans-serif; fill: var(--muted); }
    .actor { fill: var(--paper); stroke: var(--rule-strong); stroke-width: 1.1; }
    .actor-focal { fill: var(--accent-tint); stroke: var(--accent); stroke-width: 1.3; }
    .actor-link { fill: var(--link-tint); stroke: var(--link); stroke-width: 1.1; }
    .actor-name { font: 650 13px Inter, ui-sans-serif, system-ui, sans-serif; fill: var(--ink); text-anchor: middle; }
    .actor-sub { font: 500 9px ui-monospace, SFMono-Regular, Menlo, monospace; fill: var(--muted); text-anchor: middle; }
    .lifeline { stroke: var(--rule); stroke-width: 1; stroke-dasharray: 5 5; }
    .message { fill: none; stroke: var(--rule-strong); stroke-width: 1.1; marker-end: url(#arrow); }
    .message-accent { fill: none; stroke: var(--accent); stroke-width: 1.3; marker-end: url(#arrow-accent); }
    .message-link { fill: none; stroke: var(--link); stroke-width: 1.1; marker-end: url(#arrow-link); }
    .return { stroke-dasharray: 5 4; }
    .message-label { font: 500 10px Inter, ui-sans-serif, system-ui, sans-serif; fill: var(--muted); text-anchor: middle; paint-order: stroke; stroke: var(--paper); stroke-width: 4px; stroke-linejoin: round; }
    .number { fill: var(--paper); stroke: var(--rule-strong); }
    .number-accent { fill: var(--accent); stroke: var(--accent); }
    .step { font: 600 8px ui-monospace, SFMono-Regular, Menlo, monospace; fill: var(--ink); text-anchor: middle; }
    .step-inverse { fill: var(--paper); }
    .note { fill: var(--link-tint); stroke: var(--link); stroke-width: 1; }
    .note-title { font: 650 11px Inter, ui-sans-serif, system-ui, sans-serif; fill: var(--ink); }
    .note-copy { font: 400 10px Inter, ui-sans-serif, system-ui, sans-serif; fill: var(--muted); }
    .legend { font: 500 10px Inter, ui-sans-serif, system-ui, sans-serif; fill: var(--muted); }
    footer { margin-top: 16px; padding-top: 14px; border-top: 1px solid var(--rule); color: var(--muted); font-size: 13px; line-height: 1.5; }
  </style>
</head>
<body>
<main>
  <h1>Transcript request path</h1>
  <p>This is an ordered call sequence, not a set of nested layers. The main line below shows a successful cache miss.</p>

  <svg viewBox="0 0 1200 900" role="img" aria-labelledby="transcript-title transcript-desc">
    <title id="transcript-title">Transcript request sequence</title>
    <desc id="transcript-desc">A client requests a YouTube transcript. The Hono application establishes request context, authenticates and authorizes the caller, validates the route input, reserves one credit in D1, asks the provider cache for the complete transcript, and on a miss uses the request coordinator and processor to retrieve it. The application settles the credit, projects the requested response format, and returns the transcript with credit headers.</desc>
    <defs>
      <marker id="arrow" viewBox="0 0 8 6" refX="7" refY="3" markerWidth="8" markerHeight="6" orient="auto"><polygon points="0 0,8 3,0 6" fill="var(--rule-strong)"></polygon></marker>
      <marker id="arrow-accent" viewBox="0 0 8 6" refX="7" refY="3" markerWidth="8" markerHeight="6" orient="auto"><polygon points="0 0,8 3,0 6" fill="var(--accent)"></polygon></marker>
      <marker id="arrow-link" viewBox="0 0 8 6" refX="7" refY="3" markerWidth="8" markerHeight="6" orient="auto"><polygon points="0 0,8 3,0 6" fill="var(--link)"></polygon></marker>
    </defs>

    <text class="eyebrow" x="40" y="30">GET /V1/PROVIDERS/:PROVIDER/VIDEOS/:ID/TRANSCRIPT</text>
    <text class="title" x="40" y="64">Authentication, metering, cache, and complete transcript retrieval</text>
    <text class="subtitle" x="40" y="88">The response can be projected as words, segments, or text. The default is words.</text>

    <g aria-label="Sequence participants">
      <rect class="actor" x="40" y="116" width="176" height="58" rx="8"></rect>
      <text class="actor-name" x="128" y="140">Client</text>
      <text class="actor-sub" x="128" y="158">browser or API caller</text>

      <rect class="actor-focal" x="280" y="116" width="176" height="58" rx="8"></rect>
      <text class="actor-name" x="368" y="140">Worker + Hono</text>
      <text class="actor-sub" x="368" y="158">middleware and route</text>

      <rect class="actor" x="520" y="116" width="176" height="58" rx="8"></rect>
      <text class="actor-name" x="608" y="140">Credit ledger</text>
      <text class="actor-sub" x="608" y="158">D1 entitlements</text>

      <rect class="actor" x="760" y="116" width="176" height="58" rx="8"></rect>
      <text class="actor-name" x="848" y="140">Provider cache</text>
      <text class="actor-sub" x="848" y="158">KV + coordinator DO</text>

      <rect class="actor-link" x="1000" y="116" width="176" height="58" rx="8"></rect>
      <text class="actor-name" x="1088" y="140">YouTube processor</text>
      <text class="actor-sub" x="1088" y="158">container + public YouTube</text>
    </g>

    <line class="lifeline" x1="128" y1="174" x2="128" y2="820"></line>
    <line class="lifeline" x1="368" y1="174" x2="368" y2="820"></line>
    <line class="lifeline" x1="608" y1="174" x2="608" y2="820"></line>
    <line class="lifeline" x1="848" y1="174" x2="848" y2="820"></line>
    <line class="lifeline" x1="1088" y1="174" x2="1088" y2="820"></line>

    <g aria-label="Autonumbered transcript request messages">
      <circle class="number" cx="24" cy="214" r="9"></circle><text class="step" x="24" y="217">01</text>
      <path class="message-accent" d="M128 214 H368"></path><text class="message-label" x="248" y="202">GET transcript?lang=&amp;format=</text>

      <circle class="number" cx="24" cy="264" r="9"></circle><text class="step" x="24" y="267">02</text>
      <path class="message" d="M368 264 H420 Q428 264 428 272 V292 Q428 300 420 300 H376"></path><text class="message-label" x="520" y="278">context, CORS, principal, data permission, input</text>

      <circle class="number" cx="24" cy="344" r="9"></circle><text class="step" x="24" y="347">03</text>
      <path class="message" d="M368 344 H608"></path><text class="message-label" x="488" y="332">reserve 1 transcript credit</text>

      <circle class="number" cx="24" cy="388" r="9"></circle><text class="step" x="24" y="391">04</text>
      <path class="message return" d="M608 388 H368"></path><text class="message-label" x="488" y="376">reservation accepted</text>

      <circle class="number" cx="24" cy="438" r="9"></circle><text class="step" x="24" y="441">05</text>
      <path class="message" d="M368 438 H848"></path><text class="message-label" x="608" y="426">get complete transcript, language optional</text>

      <circle class="number" cx="24" cy="488" r="9"></circle><text class="step" x="24" y="491">06</text>
      <path class="message" d="M848 488 H900 Q908 488 908 496 V516 Q908 524 900 524 H856"></path><text class="message-label" x="746" y="502">read cached entry and freshness</text>

      <circle class="number" cx="24" cy="568" r="9"></circle><text class="step" x="24" y="571">07</text>
      <path class="message-link" d="M848 568 H1088"></path><text class="message-label" x="968" y="556">cache miss: fetch word-granularity transcript</text>

      <circle class="number" cx="24" cy="612" r="9"></circle><text class="step" x="24" y="615">08</text>
      <path class="message-link return" d="M1088 612 H848"></path><text class="message-label" x="968" y="600">complete normalized transcript</text>

      <circle class="number" cx="24" cy="656" r="9"></circle><text class="step" x="24" y="659">09</text>
      <path class="message return" d="M848 656 H368"></path><text class="message-label" x="608" y="644">transcript + hit | miss | coalesced | stale</text>

      <circle class="number" cx="24" cy="704" r="9"></circle><text class="step" x="24" y="707">10</text>
      <path class="message" d="M368 704 H608"></path><text class="message-label" x="488" y="692">settle actual cost: 1 credit</text>

      <circle class="number" cx="24" cy="752" r="9"></circle><text class="step" x="24" y="755">11</text>
      <path class="message" d="M368 752 H420 Q428 752 428 760 V780 Q428 788 420 788 H376"></path><text class="message-label" x="524" y="766">project words, segments, or text</text>

      <circle class="number-accent" cx="24" cy="820" r="9"></circle><text class="step step-inverse" x="24" y="823">12</text>
      <path class="message-accent return" d="M368 820 H128"></path><text class="message-label" x="248" y="808">200 transcript + credit headers</text>
    </g>

    <g aria-label="Cache branch behavior">
      <rect class="note" x="752" y="716" width="424" height="86" rx="8"></rect>
      <text class="note-title" x="772" y="740">Cache outcomes</text>
      <text class="note-copy" x="772" y="760">A fresh KV hit skips steps 07–08. Concurrent misses can coalesce.</text>
      <text class="note-copy" x="772" y="780">A stale entry is returned only when refresh fails and prior data exists.</text>
    </g>

    <line x1="40" y1="868" x2="72" y2="868" class="message-accent"></line><text class="legend" x="88" y="872">request and final response</text>
    <line x1="324" y1="868" x2="356" y2="868" class="message"></line><text class="legend" x="372" y="872">application call</text>
    <line x1="536" y1="868" x2="568" y2="868" class="message-link"></line><text class="legend" x="584" y="872">provider or external read</text>
  </svg>

  <footer>Authentication or validation failures stop before provider work. An insufficient balance stops at reservation. If provider work fails after reservation, <code>meterOperation</code> releases the reserved credit. A stale transcript is a successful fallback, not an error response.</footer>
</main>
</body>
</html>