{"id":13624981,"url":"https://github.com/judge2020/cloudflare-file-hosting","last_synced_at":"2025-04-16T01:33:09.503Z","repository":{"id":34923550,"uuid":"190421828","full_name":"judge2020/cloudflare-file-hosting","owner":"judge2020","description":"Use Cloudflare (Workers) as a file host!","archived":true,"fork":false,"pushed_at":"2023-01-07T06:07:42.000Z","size":715,"stargazers_count":73,"open_issues_count":15,"forks_count":17,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T19:53:40.734Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/judge2020.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-05T15:35:39.000Z","updated_at":"2024-11-18T07:33:39.000Z","dependencies_parsed_at":"2023-01-15T10:29:55.169Z","dependency_job_id":null,"html_url":"https://github.com/judge2020/cloudflare-file-hosting","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/judge2020%2Fcloudflare-file-hosting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/judge2020%2Fcloudflare-file-hosting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/judge2020%2Fcloudflare-file-hosting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/judge2020%2Fcloudflare-file-hosting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/judge2020","download_url":"https://codeload.github.com/judge2020/cloudflare-file-hosting/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249182489,"owners_count":21226074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:01:49.120Z","updated_at":"2025-04-16T01:33:09.496Z","avatar_url":"https://github.com/judge2020.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Cloudflare file hosting\n\nUses Workers KV to enable Cloudflare as a file host. MIT Licensed.\n\n### This vs. [Workers Sites](https://developers.cloudflare.com/workers/sites/)\n\nThis tool is intended for when you need to host files that are above Cloudflare Workers' size limitations (currently 10mb); however,  this comes at a cost penalty. See the below pricing notice.\n\n### Pricing notice\n\nYou should know that **Cloudflare Workers always runs in front the CF Cache**. This means none of the files will be cached, and every request made to these files will count against your Workers quota and pricing ($0.50/million after 10 million).\n\nIf you use files \u003e10mb then this script will split the file into multiple 10mb parts. Due to this, the script will incur multiple `KV.get` calls (one for file split detection, others per each 10mb part), meaning you will go through your included KV read quota quicker.\n\nThe $5/mo workers charge gets you **10 million free KV reads**. You will exhaust your quota depending on the size of files you have. See [this spreadsheet for the pricing quota usage](https://docs.google.com/spreadsheets/d/1seiWWouWcN1vc3RCoCDy0I5-WbZmAwIZRd7K3Ju8WCY/edit?usp=sharing).\n\n### Usage\n\n#### Standalone\n\nSee [the wiki](https://github.com/judge2020/cloudflare-file-hosting/wiki/Standalone-usage).\n\n#### Existing worker\n\nthe \"get file response\" method is provided as a library in order to make integrating this into existing workers projects simple.\n\nThe API is similar to that of the `caches.default` API where you call the function, then check if the return value is `null`, in which case you continue with other code, or a `Response`, in which case you would immediately return that response.\n\nUse it:\n\n `npm install cloudflare-file-hosting`\n\n```js\n// ES2015 Modules / typescript\nimport CF_FILES from \"cloudflare-file-hosting\";\n\n// require / javascript\nlet CF_FILES = require(\"cloudflare-file-hosting\");\n\nasync function handleRequest(request) {\n  // FILES_KV is a KV namespace dedicated to the static files\n  let url = new URL(request.url)\n  let _filesResponse = await CF_FILES.getFile(url.pathname, FILES_KV);\n  if (_filesResponse) {\n    return _filesResponse;\n  }\n  /* other code here for when the file wasn't found */\n}\n```\n\nThe standalone worker is a direct example of using this API, see [workerCode.ts](worker/workerCode.ts).\n\n##### Uploading files\n\nTo upload files, the following environment variables must be set:\n\n* CLOUDFLARE_API_TOKEN - the API token to use for uploading. Require permission `Workers KV Storage:edit` on the account that owns the namespace.\n* CLOUDFLARE_ACCOUNT_ID\n* CLOUDFLARE_ZONE_ID\n* CLOUDFLARE_KV_NAMESPACE_ID - the KV namespace ID for where to upload files\n\nWith these set, run `cfupload --path path/to/root`. You might need to use `node_modules/.bin/cfupload --path path/to/root` instead depending on your PATH setup.\n\n### Limitations\n\n#### Download speeds\n\nNot all Cloudflare regions are optimal for large file downloads. A download from the ATL datacenter with a fiber connection within the same state (Georgia) obtained ~6 MB/s download speeds.\n\nArgo smart routing likely won't have any effect due to the nature of Workers (Argo only routes CF \u003c--\u003e origin better).\n\n#### Upload size and frequency limits\n\nYour uploading may get rate limited by Cloudflare if you have a lot of data to upload and/or are frequently uploading files.\n\nThe Cloudflare API request limit is 5000/hour. Each file upload is 1 request and big files that are being split will incur a request per every ~10mb, so you can upload at most 12.5gb before exhausting the limit.\n\nWe cannot use bulk upload since it requires uploaded values be UTF-8 encoded strings, which isn't possible for binary data (base64 is not used due to it taking up memory in the worker, where there is a 128mb limit).\n\n#### Cache\n\n\nAt the moment, responses under 10mb in size will be pulled from the Cloudflare cache if possible, but this will still incur a workers request charge (but not a KV get charge). The cache is on a per-datacenter basis.\nAs far as I know, due to the fact that this uses streamed responses for \u003e10mb files, we can't use the Cache API to prevent incurring charges for KV reads. This is a tradeoff to support files larger than 128mb.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjudge2020%2Fcloudflare-file-hosting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjudge2020%2Fcloudflare-file-hosting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjudge2020%2Fcloudflare-file-hosting/lists"}