Media / API

foldkit-media/server

Functions

admissionRateLimiterAdmission through Effect's RateLimiter, limit misses a client per window, over the limiter's store (RateLimiter.layerStoreMemory for one process, Redis for…
factsOfThe facts of an image a page names only by URL (a rich-text image, a CMS block), so it is drawn with its box and placeholder like any other: its original…
handlersThe handlers of MediaApi's one route. The path is decoded against the space; a variant kept is served as kept, and one the request already holds…
headersForEvery response's headers, decided in one place, so the server, the edge and a static host cannot disagree. A variant's URL names its bytes, so it is kept…
headersRuleThe _headers rule (Cloudflare Pages, Netlify) a host needs for variants written out as files: what the server itself sends a variant, from the same…
layerThe media server as an Effect HTTP application: its route registered with the HttpRouter, needing Originals, Transformer and Variants.
limitTransformsA Transformer that runs at most concurrency transforms at once, the rest waiting their turn: encoding is CPU work, and a burst of misses should queue, not…
materializeEvery hosted variant the built pages name, made through fetch (the media server's own handler, serveFetch) and returned as files at their own paths, for…
originalsKeyValueStoreOriginals in the application's KeyValueStore, each under its content hash after prefix. A store that fails is a defect, not a missing original: the original…
serveFetchThe media server as a Worker's fetch handler, its services from each environment's bindings. It answers its own route and 404s anything else, so route to it…
serveUploadFetchThe upload route as a Worker's fetch handler, its services from each environment's bindings (uploadsR2, inspectorImages, and the application's…
uploadHandlersThe upload route's handler. It asks the UploadPolicy first; takes only an image/* body, which a browser cannot send to another origin without a preflight…
uploadLayerThe upload route as an Effect HTTP application, registered with the HttpRouter beside the variant server's, needing Uploads, an Inspector and the UploadPolicy.
uploadsKeyValueStoreUploads kept in the application's KeyValueStore, each under its content hash after prefix: the same keys originalsKeyValueStore reads, with the same prefix.…
variantsKeyValueStoreVariants kept in the application's KeyValueStore, under prefix: KeyValueStore.layerMemory for tests, layerFileSystem on a disk, layerSql over SQLite or D1.

Values

AnswerEvery answer the media server gives, and nothing else: each has its status and its headers.
MediaApiThe media server's HTTP API: one route, a variant of an original named by its content hash. The route takes its params as text, and the handler decodes them…
statusOfThe status of each answer.
UploadApiThe upload route's API, apart from MediaApi, so the variant server needs none of its services.
variantsNoneKeeps nothing: every request transforms. For a host with a cache of its own in front.

Classes

AdmissionWhether a client may have a variant made now. Asked only on a miss, after the store and before the original is read: a variant already made costs a read,…
FactsUnavailableNo facts could be read for the image at url; reason says why, for the build's report.
OriginalNotFoundNo original is stored under this hash.
OriginalsWhere originals live, by their content hash. Authoritative: the server never writes it.
OriginalTooLargeThe original is larger than the server will read: in bytes, or in pixels once decoded.
QuotaExhaustedThe host's transformation allowance is spent; variants already made still serve.
RateLimitedThe client has made too many variants lately; it may try again after retryAfterSeconds.
TransformerResizes and encodes an original into a variant, never larger than the original (a width above it answers with the original's width). An original too large…
TransformFailedThe transformer could not make the variant: the original is not an image it reads, or it failed. Its reason stays in the server's log, not the response.
UploadForbiddenThe request may not upload. Why stays with the policy: the answer says only no.
UploadPolicyWho may upload, asked of every request before its body is read. The route has no default: an application that serves uploads says who may (a foldkit-guard…
UploadsKeeps an uploaded original under its content hash: the one writer of what Originals reads.
VariantsVariants already made, by the encoded request. A cache: losing it costs time, and on a host that bills transformations, money; never data.

Interfaces

EncodedA variant made: its bytes and their media type.
FactsOptions
KeptA variant found kept, and which layer had it.
MaterializedA variant written out as a file, at its own URL's path.
Options
OriginalAn original's bytes, as the store hands them over, and how many there are.
UploadOptions