ДОКУМЕНТАЦИЯ
Операции автора
Загрузка файлов, изменение описания и проверка статуса.
Условия доступа#
| Условие | Проверка |
|---|---|
| Приложение | Явное согласие и нужные области доступа: mods:create + files:upload для загрузки, mods:update для описания мода. |
| Пользователь | Делегированный токен rh_user_, текущее разрешение mods.upload или другое необходимое разрешение; соответствие требованиям к авторам. |
| Ресурс | Проверка владельца, видимости и разрешённых полей; повторная проверка перед завершением загрузки. |
| Ключ и тариф | Ключи rh_live_ — только для чтения. Оплата не даёт права загрузки и редактирования, доступа к платному контенту или привилегий модератора. |
Что исключено#
Методы записи#
| Метод | Назначение |
|---|---|
| POST /mods; POST /uploads/external | Ссылка на Google Drive: name, category, googleDriveFileId и разрешённые поля описания. Регистрирует мод для модерации, не передаёт файл. |
| PATCH /mods/{id} | Изменение только своего мода: name/category/description/type/version/project, по схеме и текущим правилам. |
| GET /mods/{id}/upload-status | Статус загрузки своего мода по делегированному токену; без внутренних файлов и токенов. |
| POST /upload-sessions | Создание сессии загрузки ZIP; протокол и лимиты ниже. |
| GET/PATCH /upload-sessions/{id}; POST /upload-sessions/{id}/commit | Проверка статуса, последовательная передача частей файла и завершение загрузки. Мод создаётся бесплатным и ожидает модерации. |
Загрузка ZIP · 15 минут#
- POST /upload-sessions: JSON с name, category, filename, bytes и sha256 (64 шестнадцатеричных символа в нижнем регистре). Необязательные поля: description/type/version/project. filename — имя ZIP без пути, например local.zip. Часть имени до .zip содержит от 1 до 91 символа: латинские буквы, цифры, дефисы и подчёркивания; первый символ — буква или цифра.
- В data ответа: id (UUID), offset=0, sessionToken (показывается один раз), expiresIn=900 и maxChunkBytes=1048576. Храните sessionToken только в памяти на время сессии.
- GET требует тот же Bearer и X-Upload-Session. PATCH также требует Upload-Offset, Content-Type: application/octet-stream и точный Content-Length (1..1048576). Тело — байты файла, без сжатия и потоковой передачи chunked. Заголовки TUS не поддерживаются.
- Последний PATCH переводит допустимый ZIP в staged, но не публикует его. Для POST /upload-sessions/{id}/commit передайте JSON {}. Повторно проверяются хеш, длина, архив, лимит хранения, согласие и текущие права. Результат — committed с status=pending.
Лимиты и безопасность файлов#
- От 22 байт до 256 MiB на ZIP; часть файла — до 1 MiB; сессия действует 15 минут. У пользователя может быть одна активная публичная сессия на все выданные разрешения и проекты.
- Общий резерв загрузок — до 2 GiB, на пользователя — до 1 GiB; также действует лимит хранения автора. После завершения или при неопределённом результате резерв сохраняется. Это отдельное ограничение, не квота запросов за тарифный период.
- Принимается только ZIP: до 10000 записей и до 512 MiB заявленного распакованного размера. Зашифрованные файлы, символические ссылки, вложенные архивы и пути за пределы архива запрещены. Эти проверки не заменяют антивирусную проверку и не подтверждают полную распаковку или CRC всех файлов.
- Мод создаётся бесплатным, с нулевой ценой и статусом ожидания модерации. Используйте только поля схемы: нельзя менять владельца, издателя, цену или условия доступа.
Если ответ на запись потерян#
Примеры загрузки в локальной тестовой среде#
Запускайте примеры только в изолированной локальной тестовой среде с тестовым ZIP и делегированным тестовым токеном. Скрипты отклоняют внешние адреса и ключи разработчика для чтения; запросы разрешаются только явными флагами запуска. Секреты не выводятся и не сохраняются.
Local upload invocation
# Set REDUXHUB_TEST_TOKEN to your short-lived delegated local test token.
node local-examples/upload.mjs --allow-local-write --commit-local --target http://127.0.0.1:1335/public/v1 --file local.zip --name "Local sample" --category redux
python local-examples/upload.py --allow-local-write --commit-local --target http://127.0.0.1:1335/public/v1 --file local.zip --name "Local sample" --category redux
# curl script: additionally set REDUXHUB_LOCAL_API to that exact local base.
sh local-examples/upload.sh --allow-local-write local.zip redux "Local sample" --commit-local
# --check on Node/Python validates target without file, token or network.cURL · ZIP до 1 MiB
cURL · ZIP до 1 MiB
#!/bin/sh
# LOCAL disposable test ZIP only, one chunk <=1 MiB. Node/Python support larger files.
# Requires curl + Python 3 standard library; no jq/install. Never run with shell tracing.
set +x
set -eu
[ "${1-}" = '--allow-local-write' ] || { echo 'Explicit --allow-local-write required; no requests sent.' >&2; exit 1; }
[ "$#" -ge 4 ] || { echo 'Usage: upload.sh --allow-local-write local.zip TEST_CATEGORY "Local sample" [--commit-local]' >&2; exit 1; }
FILE=$2
CATEGORY=$3
NAME=$4
COMMIT=${5-}
: "${REDUXHUB_LOCAL_API:?Explicit local target required: http://127.0.0.1:PORT/public/v1}"
: "${REDUXHUB_TEST_TOKEN:?Ephemeral delegated LOCAL test token required, not a developer key}"
# All validation runs before curl. Refuse production, DNS hosts, proxies and placeholders.
META=$(python3 -c '
import hashlib,json,os,re,sys
from urllib.parse import urlsplit
base=os.environ["REDUXHUB_LOCAL_API"]
if not re.fullmatch(r"http://127\.0\.0\.1:[0-9]{1,5}/public/v1",base): raise SystemExit("Numeric loopback target required")
if not 1 <= urlsplit(base).port <= 65535: raise SystemExit("Invalid local port")
if not re.fullmatch(r"rh_user_[A-Za-z0-9_-]{43}",os.environ["REDUXHUB_TEST_TOKEN"]): raise SystemExit("Delegated LOCAL token required")
file,category,name=sys.argv[1:]
filename=os.path.basename(file)
if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,90}\.zip",filename): raise SystemExit("Plain local.zip basename required")
size=os.path.getsize(file)
if not 22 <= size <= 1048576: raise SystemExit("This curl example requires 22 bytes through 1 MiB; use Node/Python for chunks")
with open(file,"rb") as source: sha=hashlib.sha256(source.read(1048577)).hexdigest()
print(json.dumps(dict(name=name,category=category,filename=filename,bytes=size,sha256=sha)))
' "$FILE" "$CATEGORY" "$NAME")
# Pass credentials to curl via stdin config, not shell history or files. No -L or retries.
CREATED=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions"
request = "POST"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "Content-Type: application/json"
data = "$(printf '%s' "$META" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read())[1:-1])')"
EOF
)
# stdout is captured in shell memory only; never echo the server response/session token.
ID=$(printf '%s' "$CREATED" | python3 -c 'import json,re,sys;d=json.load(sys.stdin)["data"];assert re.fullmatch(r"[a-f0-9-]{36}",d["id"]);assert d["offset"]==0;print(d["id"])')
SESSION=$(printf '%s' "$CREATED" | python3 -c 'import json,re,sys;t=json.load(sys.stdin)["data"]["sessionToken"];assert re.fullmatch(r"rh_upload_[A-Za-z0-9_-]{43}",t);print(t)')
BYTES=$(printf '%s' "$META" | python3 -c 'import json,sys;print(json.load(sys.stdin)["bytes"])')
STATUS=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions/$ID"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "X-Upload-Session: $SESSION"
EOF
)
printf '%s' "$STATUS" | python3 -c 'import json,sys;d=json.load(sys.stdin)["data"];assert d["state"]=="uploading" and d["offset"]==0'
# --data-binary reads only the selected local file. No compression/TUS/chunked transfer.
APPENDED=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --data-binary "@$FILE" --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions/$ID"
request = "PATCH"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "X-Upload-Session: $SESSION"
header = "Upload-Offset: 0"
header = "Content-Type: application/octet-stream"
header = "Content-Length: $BYTES"
EOF
)
printf '%s' "$APPENDED" | python3 -c 'import json,sys;d=json.load(sys.stdin)["data"];assert d["state"]=="staged" and d["offset"]==int(sys.argv[1])' "$BYTES"
if [ "$COMMIT" = '--commit-local' ]; then
RESULT=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions/$ID/commit"
request = "POST"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "X-Upload-Session: $SESSION"
header = "Content-Type: application/json"
data = "{}"
EOF
)
printf '%s' "$RESULT" | python3 -c 'import json,sys;d=json.load(sys.stdin)["data"];assert d["state"]=="committed" and d["status"]=="pending";print("Local test upload pending moderation; not published")'
else
echo 'Staged only. Reservation remains until known cleanup or an explicit local commit.'
fi
# On any uncertain PATCH/commit, STOP. Query authoritative status with SAME credentials.
# Never replay blindly; unknown/committing states require operator investigation.
unset CREATED SESSION STATUS APPENDED RESULT REDUXHUB_TEST_TOKEN
Node.js · части до 1 MiB
Node.js · части до 1 MiB
/** Explicitly opted-in LOCAL test writes only. No browser code or private signing key. */
import { request as httpRequest } from 'node:http';
import { open } from 'node:fs/promises';
import { basename, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { createHash } from 'node:crypto';
export const MAX_FILE = 256 * 1024 * 1024;
export const CHUNK = 1024 * 1024;
export function localTarget(raw) {
if (!/^http:\/\/127\.0\.0\.1:[0-9]{1,5}\/public\/v1$/.test(raw || '')) throw new Error('Explicit numeric loopback --target http://127.0.0.1:PORT/public/v1 required');
const url = new URL(raw);
if (!url.port || Number(url.port) > 65535 || Number(url.port) < 1) throw new Error('An explicit non-default local port is required');
return url;
}
export function delegatedToken(value) {
if (!/^rh_user_[A-Za-z0-9_-]{43}$/.test(value || '')) throw new Error('Set REDUXHUB_TEST_TOKEN to an ephemeral delegated LOCAL test token, never a developer key');
return value;
}
export function parseOptions(argv) {
const options = {};
for (let i = 0; i < argv.length; i++) {
const key = argv[i];
if (['--allow-local-write', '--commit-local', '--check'].includes(key)) options[key.slice(2)] = true;
else if (['--target', '--file', '--name', '--category'].includes(key) && argv[i + 1] && !argv[i + 1].startsWith('--')) options[key.slice(2)] = argv[++i];
else throw new Error('Unknown/missing argument. Use --check --target URL or explicit --allow-local-write --target URL --file local.zip --name NAME --category CATEGORY [--commit-local]');
}
localTarget(options.target);
return options;
}
function transport(target, token) {
return (method, path, body, session, offset) => new Promise((accept, reject) => {
const headers = { Authorization: 'Bearer ' + token, Accept: 'application/json' };
if (session) headers['X-Upload-Session'] = session;
if (body) { headers['Content-Type'] = Buffer.isBuffer(body) ? 'application/octet-stream' : 'application/json'; headers['Content-Length'] = String(Buffer.byteLength(Buffer.isBuffer(body) ? body : JSON.stringify(body))); }
if (offset !== undefined) headers['Upload-Offset'] = String(offset);
// Numeric loopback, no DNS/proxy environment, redirect following or retry.
const req = httpRequest({ hostname: '127.0.0.1', port: Number(target.port), path: '/public/v1' + path, method, headers, agent: false }, res => {
const chunks = []; let total = 0;
res.on('data', chunk => { total += chunk.length; if (total > 65536) req.destroy(new Error('Bounded response exceeded')); else chunks.push(chunk); });
res.on('end', () => {
if (res.statusCode < 200 || res.statusCode >= 300) { reject(new Error('Local API HTTP ' + res.statusCode + '; stop and inspect session status. No automatic retry.')); return; }
try { const value = JSON.parse(Buffer.concat(chunks).toString('utf8')); if (value.success !== true || !value.data || typeof value.data !== 'object') throw new Error(); accept(value.data); }
catch { reject(new Error('Invalid local API envelope; stop, do not replay a write')); }
});
res.on('error', reject);
});
req.setTimeout(15000, () => req.destroy(new Error('Local request deadline; outcome may be ambiguous. Query status before any manual recovery.')));
req.on('error', () => reject(new Error('Local request failed; outcome may be ambiguous. Do not replay PATCH/commit. Query status with the same credentials.')));
if (body) req.write(Buffer.isBuffer(body) ? body : JSON.stringify(body));
req.end();
});
}
export async function upload(options, env = process.env, requestOverride) {
const target = localTarget(options.target);
if (options.check) return { checked: true, network: false };
if (!options['allow-local-write']) throw new Error('--allow-local-write is mandatory; no request was sent');
const token = delegatedToken(env.REDUXHUB_TEST_TOKEN);
if (!options.file || !options.name || !options.category) throw new Error('--file, --name and --category must identify disposable LOCAL test data');
const filename = basename(options.file);
if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,90}\.zip$/.test(filename)) throw new Error('Use a plain ASCII local.zip basename');
const file = await open(resolve(options.file), 'r');
try {
const info = await file.stat();
if (!info.isFile() || info.size < 22 || info.size > MAX_FILE) throw new Error('ZIP must be 22 bytes through 256 MiB');
const buffer = Buffer.alloc(CHUNK), hash = createHash('sha256');
for (let offset = 0; offset < info.size;) { const { bytesRead } = await file.read(buffer, 0, Math.min(CHUNK, info.size - offset), offset); if (!bytesRead) throw new Error('Local file changed'); hash.update(buffer.subarray(0, bytesRead)); offset += bytesRead; }
const call = requestOverride || transport(target, token);
const created = await call('POST', '/upload-sessions', { name: options.name, category: options.category, filename, bytes: info.size, sha256: hash.digest('hex') });
if (!/^[a-f0-9-]{36}$/.test(created.id || '') || !/^rh_upload_[A-Za-z0-9_-]{43}$/.test(created.sessionToken || '') || created.offset !== 0 || created.maxChunkBytes !== CHUNK) throw new Error('Invalid session response; stop without retry');
const path = '/upload-sessions/' + created.id, secret = created.sessionToken;
let offset = 0, state = created.state;
while (offset < info.size) {
const status = await call('GET', path, undefined, secret);
if (status.offset !== offset || status.state !== 'uploading') throw new Error('Unexpected authoritative offset/state; no automatic resume');
const { bytesRead } = await file.read(buffer, 0, Math.min(CHUNK, info.size - offset), offset);
if (!bytesRead) throw new Error('Local file changed');
const appended = await call('PATCH', path, Buffer.from(buffer.subarray(0, bytesRead)), secret, offset);
if (appended.offset !== offset + bytesRead) throw new Error('Ambiguous append offset; stop without retry');
offset = appended.offset; state = appended.state;
}
if (state !== 'staged') throw new Error('Final chunk was not staged; do not commit');
if (!options['commit-local']) return { state: 'staged', note: 'Reserved until known cleanup or explicit local commit; not published' };
const result = await call('POST', path + '/commit', {}, secret);
if (result.state !== 'committed' || result.status !== 'pending') throw new Error('Ambiguous commit; stop without replay');
return { state: 'committed', status: 'pending' };
} finally { await file.close(); }
}
if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
try { const result = await upload(parseOptions(process.argv.slice(2))); console.log(JSON.stringify(result)); }
catch (error) { console.error(error.message); process.exitCode = 1; }
}
Python · стандартная библиотека
Python · стандартная библиотека
"""Opted-in LOCAL ZIP test writes only. Python standard library; no signing keys."""
import argparse
import hashlib
import http.client
import json
import os
from pathlib import Path
import re
from urllib.parse import urlsplit
CHUNK = 1024 * 1024
MAX_FILE = 256 * 1024 * 1024
def local_target(raw):
if not re.fullmatch(r"http://127\.0\.0\.1:[0-9]{1,5}/public/v1", raw or ""):
raise ValueError("Explicit numeric loopback --target http://127.0.0.1:PORT/public/v1 required")
target = urlsplit(raw)
if not target.port or not 1 <= target.port <= 65535:
raise ValueError("Explicit local port required")
return target
def run(args):
target = local_target(args.target)
if args.check:
return {"checked": True, "network": False}
if not args.allow_local_write:
raise ValueError("--allow-local-write required; no request sent")
token = os.environ.get("REDUXHUB_TEST_TOKEN", "")
if not re.fullmatch(r"rh_user_[A-Za-z0-9_-]{43}", token):
raise ValueError("Ephemeral delegated LOCAL REDUXHUB_TEST_TOKEN required, not a developer key")
if not args.file or not args.name or not args.category:
raise ValueError("--file, --name and --category must describe disposable LOCAL data")
file = Path(args.file)
if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_-]{0,90}\.zip", file.name):
raise ValueError("Plain ASCII local.zip basename required")
def call(method, route, body=None, session=None, offset=None):
headers = {"Authorization": "Bearer " + token, "Accept": "application/json"}
if session:
headers["X-Upload-Session"] = session
if body is not None:
if isinstance(body, bytes):
headers["Content-Type"] = "application/octet-stream"
else:
body = json.dumps(body).encode("utf-8")
headers["Content-Type"] = "application/json"
headers["Content-Length"] = str(len(body))
if offset is not None:
headers["Upload-Offset"] = str(offset)
# http.client uses this numeric loopback only; no redirects, DNS or proxies.
connection = http.client.HTTPConnection("127.0.0.1", target.port, timeout=15)
try:
connection.request(method, "/public/v1" + route, body, headers)
response = connection.getresponse()
raw = response.read(65537)
if not 200 <= response.status < 300 or len(raw) > 65536:
raise ValueError("Local response rejected; inspect status, never blindly replay writes")
payload = json.loads(raw)
if payload.get("success") is not True or not isinstance(payload.get("data"), dict):
raise ValueError("Invalid local API envelope")
return payload["data"]
except (OSError, http.client.HTTPException):
raise ValueError("Ambiguous local request; stop. Query status with the same credentials before manual recovery") from None
finally:
connection.close()
with file.open("rb") as source:
size = os.fstat(source.fileno()).st_size
if not 22 <= size <= MAX_FILE:
raise ValueError("ZIP must be 22 bytes through 256 MiB")
digest = hashlib.sha256()
for chunk in iter(lambda: source.read(CHUNK), b""):
digest.update(chunk)
source.seek(0)
created = call("POST", "/upload-sessions", {"name": args.name, "category": args.category,
"filename": file.name, "bytes": size, "sha256": digest.hexdigest()})
if (not re.fullmatch(r"[a-f0-9-]{36}", created.get("id", ""))
or not re.fullmatch(r"rh_upload_[A-Za-z0-9_-]{43}", created.get("sessionToken", ""))
or created.get("offset") != 0 or created.get("maxChunkBytes") != CHUNK):
raise ValueError("Invalid session response; stop")
route = "/upload-sessions/" + created["id"]
session = created["sessionToken"] # Memory only: never print/save it.
offset, state = 0, created.get("state")
while offset < size:
status = call("GET", route, session=session)
if status.get("offset") != offset or status.get("state") != "uploading":
raise ValueError("Unexpected authoritative offset/state; no automatic resume")
chunk = source.read(min(CHUNK, size - offset))
if not chunk:
raise ValueError("Local file changed")
appended = call("PATCH", route, chunk, session, offset)
if appended.get("offset") != offset + len(chunk):
raise ValueError("Ambiguous append; stop without replay")
offset, state = appended["offset"], appended.get("state")
if state != "staged":
raise ValueError("Final chunk was not staged; do not commit")
if not args.commit_local:
return {"state": "staged", "note": "Reservation remains; not published"}
result = call("POST", route + "/commit", {}, session)
if result.get("state") != "committed" or result.get("status") != "pending":
raise ValueError("Ambiguous commit; do not replay")
return {"state": "committed", "status": "pending"}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--target", required=True)
parser.add_argument("--allow-local-write", action="store_true")
parser.add_argument("--commit-local", action="store_true")
parser.add_argument("--check", action="store_true")
for key in ("file", "name", "category"):
parser.add_argument("--" + key)
try:
print(json.dumps(run(parser.parse_args())))
except (ValueError, OSError):
# Do not include response bodies, token values or HTTP exception objects.
parser.exit(1, "Local upload stopped. Validate input/permissions and inspect session status before any manual retry.\n")
if __name__ == "__main__":
main()