diff --git a/README.md b/README.md index e1501c3..511f594 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ # Paste -This is a pastebin-like, simple file sharing application targeted to run on Cloudflare Worker. -[pb.nekoid.cc](http://pb.nekoid.cc) is the current deployment of this project. -The maximum upload file size is limited to **10 MB** and the paste will be kept for **28 days** only by default. +This project is a fast, anonymous file and text sharing platform built on a serverless architecture with live instance available at [pb.nekoid.cc](https://pb.nekoid.cc), deployed as a Cloudflare Workers, written in Typescript. Originally designed to quickly share logs, configuration files, and even command output with another computer. + +This service enables users to quickly and anonymously share files, texts, and URLs with QR Codes and shortened URLs. +All the upload files are stored in an object service, which can be any S3-compatible service, like AWS S3. It supports fast file upload +and fetch via RESTful API, web interface and cURL for console, and caching of frequently accessed files with Cloudflare CDN. + +The maximum upload file size is limited to **250 MB** and the paste will be kept for **28 days** only by default. *All data may be deleted or expired without any notification and guarantee.* Please **DO NOT** abuse this service. @@ -30,7 +34,7 @@ It is worth noting that Cloudflare Worker is run *before* the cache. Therefore, ## Environment variable -|Name|Description| +|Variable name|Description| |-|-| |`SERVICE_URL`|Service URL| |`PASTE_INDEX_HTML_URL`|Service frontpage HTML URL| @@ -44,10 +48,11 @@ It is worth noting that Cloudflare Worker is run *before* the cache. Therefore, |`LARGE_ENDPOINT`|S3 endpoint to upload *large paste*| |`LARGE_DOWNLOAD_ENDPOINT`|S3/CDN endpoint/ to retrieve *large paste*| -(Compatible to any S3-compatible object storage) -**`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `ENDPOINT` should be kept secret, -i.e., [encrypted store](https://developers.cloudflare.com/workers/platform/environment-variables/#adding-secrets-via-wrangler) -.** +`AWS_ACCESS_*` and `LARGE_AWS_ACCESS_*` is the access credentials to S3-compatible object storages. +These environment variable can be set in `wrangler.toml` or using the following command: +```sh +$ pnpm wrangler secret put +``` ## Usage @@ -56,13 +61,13 @@ i.e., [encrypted store](https://developers.cloudflare.com/workers/platform/envir Upload a file (Raw body) with password enabled ```sh -$ curl -g -T ${FILE} -H "x-pass: exmaple1234" "https://pb.nekoid.cc" +$ curl -g -X POST -T -H "x-pass: exmaple1234" "https://pb.nekoid.cc" ``` Upload a file (Formdata) with password enabled ```shell -$ curl -F u=@exmaple.txt -F "pass=example1234" "https://pb.nekoid.cc" +$ curl -F u=@ -F "pass=example1234" "https://pb.nekoid.cc" ``` Upload command ouput as paste @@ -80,13 +85,13 @@ $ echo "Hello, world!" | curl -F u=@- 'https://pb.nekoid.cc?qr=1' Get paste ```shell -$ curl https://pb.nekoid.cc/uuid +$ curl https://pb.nekoid.cc/ ``` Delete paste ```shell -$ curl -X DELETE https://pb.nekoid.cc/uuid +$ curl -X DELETE https://pb.nekoid.cc/ ``` ### **Web** @@ -96,20 +101,20 @@ This HTML form currenly only support paste upload. ## API Specification -### GET / +### `GET /` Fetch the Web frontpage HTML for uploading text/file (used for browsers) -### GET /api +### `GET /api` Fetch API specification -### GET /\ +### `GET /` Fetch the paste by uuid. *If the password is set, this request requires additional `x-pass` header or to use [HTTP Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).* -### POST / +### `POST /` Create new paste. Currently, only `multipart/form-data` and raw request are supported. Add `?qr=1` to enable QR code generation for paste link. @@ -149,7 +154,44 @@ The request body contains the upload content. |`large_paste`|Large paste(>25MB)| |`link`|URL link to be redirected| -### GET /\/\ +#### Response + +Upon a successful upload using `POST /` or a call to `GET //settings`, the endpoint will respond in the following format + +In default mode, designed for text console: +``` +uuid: MRFS +link: https://pb.nekoid.cc/MRFS +type: paste +title: satanichia.png +mime-type: image/png +size: 2420328 bytes (2.308 MiB) +password: false +access times: 5 +max_access_n: - +created at 2025-08-01T06:59:44.336Z +expired at 2025-08-29T06:59:44.336Z +``` + +In JSON mode (`?json=1`) +```json +{ + "uuid":"MRFS", + "link":"https://pb.nekoid.cc/MRFS", + "link_qr":"https://qrcode.nekoid.cc/?q=https%3A%2F%2Fpb.nekoid.cc%2FMRFS&type=svg", + "type":"paste", + "title":"satanichia.png", + "mime_type":"image/png", + "human_readable_size":"2.308 MiB", + "size":2420328, + "password":false, + "access_n":5, + "created":"2025-08-01T06:59:44.336Z", + "expired":"2025-08-29T06:59:44.336Z" +} +``` + +### `GET //