Ugrás a fő tartalomhoz

Bővítményfájl-tárolás

A bővítményfájlok tárolása lehetővé teszi az engedélyezett bővítmények számára, hogy feltöltsenek egy zárolási bővítmény-munkamenethez tartozó képfájlokat.

Használja, ha a kiterjesztési állapot JSON-ja nem elegendő, például:

  • kirakós képek
  • generált előnézetek
  • kihívás fotók
  • bővítmény-specifikus média, amelyet a zárolással/munkamenettel kell megtisztítani

Ez a tároló elkülönül a state.* tárolótól. Kis JSON adatokhoz használja a state.* tárolót. Bináris adathordozókhoz csak fájltárolót használjon.

Kapcsolat az állami végpontokkal​

A kiterjesztés állapota kis, munkamenet-hatókörű JSON-hoz tartozik. Egy iframe-ből a REST közvetlen hívása helyett használd a bridge read parancsot:

state.get

A hídparancs ide irányít át:

GET   /api/extensions/sessions/:sessionId/state

A közvetlen háttérbeli hívások az állapot írásához az installed-extension API hitelesítési modellt használják:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

Ne küldj fejlesztői API-kulcsokat iframe-be/böngészőkódba.

Tartós referenciákhoz és felhasználói felület adatokhoz használjon háttérben írt állapotot, például:

{
  "puzzleImageFileId": "file_record_id",
  "selectedImageIds": ["file_record_id"],
  "lastOpenedTab": "images"
}

Ne tároljon bináris adatokat, base64 képeket, böngésző blob: URL-eket vagy a signedUrl hosszú élettartamú másolatait az állapotban. Az aláírt URL-ek lejárnak, és a kép megjelenítésekor frissíteni kell őket a files.get értékkel. Az állapotírások méretét a bővítményalkalmazás stateMaxBytes beállítása korlátozza, alapértelmezés szerint 64 KiB-ra állítva.

Tárolási modell​

A Chastify a kiterjesztési fájlokat Chastify által felügyelt R2 tárolóban tárolja.

Minden feltöltött fájlt a következő adatokkal követünk nyomon:

  • scope: "extension"
  • appId
  • sessionId és lockId futásidejű/munkamenet-fájlokhoz
  • templateId a mentett zárolási sablon által igényelt fájlokhoz
  • staged, draftId és expiresAt a még nem igényelt beállítási feltöltésekhez
  • extensionKey
  • purpose

Adminisztrátori kapu és kvóták​

Átállási végpontok beállítása​

Csak akkor használja a beállítási előkészítést, ha a telepítési felhasználói felület a bővítmény-munkamenet létezése előtt fut.

Ez egy ideiglenes feltöltési folyamat. A beállítási/konfigurációs képernyőkön létezik, ahol a felhasználó feltölthet egy fájlt, majd bezárhatja a modális ablakot vagy letilthatja a bővítményt a zárolás/munkamenet létrehozása előtt. Egy előkészített fájl nem tartós, amíg a rá hivatkozó bővítménykonfiguráció mentésével nem igényelik.

A beállító felhasználói felületek a feltöltési vezérlők megjelenítése előtt ellenőrizhetik az elérhetőséget és az aktuális szakaszos használatot:

GET /api/extensions/apps/:appId/files/capabilities

A válasz tartalmazza a stagedQuota kódot az aktuális felhasználó le nem járt előkészített fájljaihoz az adott bővítményalkalmazásban:

{
  "enabled": true,
  "provider": "r2",
  "r2Configured": true,
  "supportsStagedSetupFiles": true,
  "stagedQuota": {
    "bytesUsed": 123456,
    "fileCount": 1,
    "maxBytes": 10485760,
    "remainingBytes": 10362304
  }
}
POST /api/extensions/apps/:appId/files/stage
Content-Type: multipart/form-data

Űrlapmezők:

  • file: szükséges képfájl
  • purpose: opcionális rövid azonosító, például jigsaw-config-image
  • draftId: opcionális beállítási vázlat azonosító; ugyanazt az értéket használhatja újra, amíg egy beállítási modál meg van nyitva

A válasz egy stabil file.id kódot és egy rövid életű aláírt URL-címet tartalmaz az azonnali előnézethez.

Példaválasz:

{
  "file": {
    "id": "file_record_id",
    "signedUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
    "publicUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
    "urlExpiresAt": "2026-05-28T12:10:00.000Z",
    "sizeBytes": 123456,
    "originalName": "puzzle.jpg",
    "mimeType": "image/webp",
    "purpose": "jigsaw-config-image",
    "uploadedAt": "2026-05-28T12:00:00.000Z"
  },
  "stagedQuota": {
    "bytesUsed": 123456,
    "fileCount": 1,
    "maxBytes": 10485760,
    "remainingBytes": 10362304
  }
}

A beállítási feltöltéseknek az oldal frissítése utáni visszaállításához listázza ki az aktuális felhasználó és a bővítményalkalmazás előkészített fájljait:

GET /api/extensions/apps/:appId/files/staged?purpose=jigsaw-config-image

Opcionális lekérdezési paraméterek:

  • purpose: csak egy beállítási használati esethez tartozó előkészített fájlokat ad vissza
  • draftId: csak egy ismert beállítási vázlatból származó fájlokat ad vissza

Ha a draftId paraméter nincs megadva, a Chastify visszaadja az aktuális felhasználó lejárt, előkészített fájljait az adott alkalmazáshoz. Ez szándékos a beállítási felhasználói felületeknél: a felhasználó feltölthet fájlokat, újratöltheti az oldalt vagy válthat eszközt, és a beállítási képernyő visszaállíthatja ezeket az ideiglenes feltöltéseket a zárolás/sablon mentése előtt.

A szakaszos listára adott válasz tartalmazza a stagedQuota kódot is, amely az aktuális felhasználó le nem járt szakaszos használatát jelenti az adott alkalmazásban:

{
  "items": [],
  "stagedQuota": {
    "bytesUsed": 123456,
    "fileCount": 1,
    "maxBytes": 10485760,
    "remainingBytes": 10362304
  }
}

A telepítő felhasználói felületek egy előkészített fájlt is frissíthetnek vagy törölhetnek:

GET /api/extensions/apps/:appId/files/:fileId
DELETE /api/extensions/apps/:appId/files/staged/:fileId

Előzetes fájlok igénylése később​

Nincs külön böngészőoldali „igénylési” végpont. Egy előkészített fájl igénylése automatikusan megtörténik, amikor a Chastify ment egy zárolási vagy sablonbővítmény-konfigurációt, amely hivatkozik az előkészített fájlra.

Ezek az útvonalak igénylik az előkészített fájlokat, miután a zárolási/sablon dokumentum rendelkezik egy azonosítóval, majd újra mentik a bővítmény konfigurációját az igényelt fájlhivatkozásokkal. Ha az igénylés sikertelen, az újonnan létrehozott zárolási/sablon visszaállításra kerül, így az előkészített fájlok nem maradnak egy hibás konfigurációhoz csatolva.

Megosztott sablonnal kapcsolatos megjegyzés: az elfogadott megosztott zárak megtartják a forrássablon azonosítóját a klónozott aktív záron. A sablon által igényelt fájlok ezért megmaradnak, amíg a klónozott zár továbbra is hivatkozik az adott sablonra. Ha a forrássablon törlődik, a Chastify késlelteti a bővítményfájlok törlését, amíg a törölt sablonra hivatkozó utolsó klónozott zár törlődik vagy archiválódik.

Egy előkészített fájl igényelhetővé tételéhez tároljon egy ehhez hasonló hivatkozást a telepítő felhasználói felület által beküldött bővítménykonfigurációban:

{
  "storageDraftId": "draft_123",
  "images": [
    {
      "id": "file_record_id",
      "provider": "chastify_storage",
      "fileId": "file_record_id",
      "url": "extension-file:file_record_id",
      "title": "Puzzle image"
    }
  ]
}

Mentéskor a Chastify átvizsgálja a konfigurációt érvényes fileId kóddal rendelkező provider: "chastify_storage" rekordok után, majd:

  • ellenőrzi, hogy a fájl az aktuális felhasználóhoz és bővítményalkalmazáshoz tartozik-e
  • elutasítja a lejárt előkészített fájlokat
  • elutasítja azokat a fájlokat, amelyeket már egy másik zárolási/sablonkontextus igényelt
  • a hivatkozott szakaszos fájlokat igényeltként jelöli meg
  • a mentett zárhoz vagy sablonhoz köti az igényelt fájlokat
  • eltávolítja az ideiglenes signedUrl, publicUrl és urlExpiresAt mezőket a konfiguráció megőrzése előtt
  • törli a nem hivatkozott előkészített fájlokat ugyanarról a storageDraftId-ról

A soha nem mentett elhagyott, előkészített fájlokat a lejárati idejük után a tisztítás törli.

A jelenlegi felhasználó és a bővítményalkalmazás tulajdonában lévő fájlazonosító beállítási előnézetének frissítése:

GET /api/extensions/apps/:appId/files/:fileId

Munkamenet végpontjai​

Ezekhez a végpontokhoz a szokásos bővítmény-munkamenet-engedélyezés és hatókörök szükségesek.

Alapútvonal:

/api/extensions/sessions/:sessionId/files

Képességek​

Ezt ellenőrizd a feltöltési vezérlők renderelése előtt.

GET /api/extensions/sessions/:sessionId/files/capabilities

locks:read szükséges.

Példaválasz:

{
  "enabled": true,
  "provider": "r2",
  "r2Configured": true,
  "settings": {
    "enabled": true,
    "maxFileBytes": 10485760,
    "maxBytesPerApp": 524288000,
    "maxBytesPerSession": 52428800,
    "maxStagedBytesPerUserPerApp": 10485760,
    "allowedMimePrefixes": ["image/"]
  }
}

Fájlok listázása​

GET /api/extensions/sessions/:sessionId/files

locks:read szükséges.

Példaválasz:

{
  "items": [
    {
      "id": "file_record_id",
      "signedUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
      "publicUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
      "urlExpiresAt": "2026-05-28T12:10:00.000Z",
      "sizeBytes": 123456,
      "originalName": "puzzle.jpg",
      "mimeType": "image/webp",
      "purpose": "puzzle-image",
      "uploadedAt": "2026-05-28T12:00:00.000Z"
    }
  ]
}

Egy fájl beszerzése​

Használja ezt, ha a bővítményének már van egy tárolt fájlazonosítója, és csak egy friss, aláírt R2 hivatkozásra van szüksége.

GET /api/extensions/sessions/:sessionId/files/:fileId

locks:read szükséges.

A fájlnak ugyanahhoz a bővítményalkalmazáshoz, munkamenethez és zároláshoz kell tartoznia.

Példaválasz:

{
  "file": {
    "id": "file_record_id",
    "signedUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
    "publicUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
    "urlExpiresAt": "2026-05-28T12:10:00.000Z",
    "sizeBytes": 123456,
    "originalName": "puzzle.jpg",
    "mimeType": "image/webp",
    "purpose": "puzzle-image",
    "uploadedAt": "2026-05-28T12:00:00.000Z"
  }
}

Fájl feltöltése​

POST /api/extensions/sessions/:sessionId/files
Content-Type: multipart/form-data

locks:write szükséges.

Űrlapmezők:

  • file: szükséges képfájl
  • purpose: opcionális rövid azonosító, például puzzle-image vagy preview

Példa:

curl "https://chastify.net/api/extensions/sessions/SESSION_ID/files" \
  -X POST \
  -F "purpose=puzzle-image" \
  -F "[email protected]"

Példaválasz:

{
  "file": {
    "id": "file_record_id",
    "signedUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
    "publicUrl": "https://chastify.<account-id>.r2.cloudflarestorage.com/extensions/abc.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
    "urlExpiresAt": "2026-05-28T12:10:00.000Z",
    "sizeBytes": 123456,
    "originalName": "puzzle.jpg",
    "mimeType": "image/webp",
    "purpose": "puzzle-image",
    "uploadedAt": "2026-05-28T12:00:00.000Z"
  }
}

Gyakori feltöltési hibák:

  • extension_file_storage_disabled
  • extension_file_storage_requires_r2
  • file_too_large
  • invalid_file_type
  • extension_app_storage_quota_exceeded
  • extension_session_storage_quota_exceeded
  • extension_staged_user_app_storage_quota_exceeded

Fájl törlése​

DELETE /api/extensions/sessions/:sessionId/files/:fileId

locks:write szükséges.

A fájlnak ugyanahhoz a bővítményalkalmazáshoz, munkamenethez és zároláshoz kell tartoznia.

Iframe Bridge műveletek​

Az Iframe kiterjesztések a szülő webhidat használhatják futásidejű fájlok olvasásához. A futásidejű fájlok feltöltése és törlése munkamenet-mutációk, és a háttérrendszernek kell végrehajtania egy alkalmazás-hatókörű fejlesztői API-kulccsal és a x-chastify-main-token kóddal.

const capabilities = await bridge.request("files.capabilities", {});

const refreshed = await bridge.request("files.get", {
  fileId: "file_record_id"
});

image.src = refreshed.file.signedUrl;

Támogatott hídműveletek:

  • files.capabilities -> ellenőrizze, hogy engedélyezve van-e a fájltárolás, és milyen kvóták érvényesek
  • files.list -> listázza az aktuális kiterjesztés munkamenetéhez tartozó fájlokat
  • files.get -> egy aláírt R2 URL frissítése egy tárolt fájlazonosítóból

A beállítási iframe-ek további hídneveket használhatnak, mielőtt futásidejű munkamenet létesülne. Beállítás módban a files.upload előkészített fájlokat hoz létre, a files.list/files.staged.list listázza az aktuális felhasználó és alkalmazás lejárt előkészített fájljait, a files.delete pedig törli az előkészített fájlokat. A beállítás init kontextusa tartalmazza a storageDraftId értéket; adja hozzá ezt az értéket a mentett konfigurációhoz storageDraftId néven, ha azt szeretné, hogy a Chastify a mentéskor azonnal törölje a nem hivatkozott fájlokat ugyanabból a vázlatból.

A files.upload beállítás egyszerű iframe kliensek esetén a dataUrl kódot is elfogadja:

await bridge.request("files.upload", {
  dataUrl: canvas.toDataURL("image/webp", 0.9),
  filename: "preview.webp",
  purpose: "preview"
}, 60000);

Amikor csak lehetséges, a File vagy Blob feltöltéseket részesítsd előnyben. A dataUrl kódot csak kis méretű, generált képekhez használd, mivel a base64 hasznos adatmennyiségek nagyobb memóriát foglalnak el.

A stabil fájlazonosító id.

A fájl megjelenítéséhez vagy letöltéséhez használja a signedUrl paramétert. Az aláírt hivatkozások a Chastify által generált rövid életű R2 GetObject URL-ek. A publicUrl kompatibilitási aliasként van megtartva, és jelenleg ugyanazt az aláírt URL-t tartalmazza.

Amikor egy aláírt hivatkozás lejár, hívja a GET /api/extensions/sessions/:sessionId/files/:fileId parancsot egy tárolt fájl friss hivatkozásának fogadásához, vagy a GET /api/extensions/sessions/:sessionId/files parancsot az összes munkamenetfájl-hivatkozás frissítéséhez.

Takarítási életciklus​

A bővítményfájlokat egy BullMQ által támogatott tisztítási sor tisztítja.

A takarítást akkor tervezik, amikor:

  • egy bővítményalkalmazás törölve van
  • A zárolási/munkamenet-kiterjesztési dokumentumok törlődnek a zárolás eltávolítása/archívum törlése során
  • egy fájl explicit módon törlődik a munkamenetfájl-végponton keresztül

A várólista kiküszöböli a költséges R2 törlést és adatbázis-tisztítást a kérési útvonalból. Ha a várólista sorba helyezése sikertelen, a szerver a válasz utáni folyamaton belüli takarításra tér vissza, ahol létezik kérési kontextus, vagy közvetlen, legjobb erőfeszítést igénylő takarításra az alacsonyabb szintű életciklus-tisztítás során.

Teljesítményjegyzetek​

  • A képességellenőrzéseknek a feltöltési felhasználói felület megjelenése előtt kell megtörténniük.
  • A feltöltéseket fájlonkénti, munkamenetenkénti és alkalmazásonkénti korlátok korlátozzák.
  • A kvóta-ellenőrzések indexelt UserFile metaadatokat használnak a scope + appId, scope + sessionId és scope + lockId értékekhez.
  • A fájlrekordoknak megfelelő adatfolyamok tisztítása ahelyett, hogy az összes URL-t a memóriába töltené.
  • A feltöltött raszteres képeket optimalizált webképekként dolgozza fel és tárolja.

Biztonsági megjegyzések​

  • Ne kezelje a bővítmény által biztosított kép URL-eket megbízható befejezési bizonyítékként.
  • Csak a Chastify által kiadott fájlrekordokat tárolja megbízható kiterjesztésfájlként.
  • Fájlrekordok kötése a appId, sessionId és lockId kódokhoz.
  • locks:write kód érvényesítése feltöltéseknél és törléseknél.
  • MIME típus validálása és SVG elutasítása.
  • A széleskörű nyilvános használat engedélyezése előtt tartsa engedélyezve az adminisztrátor által ellenőrzött kvótákat.
  • Használjon szerveroldali ellenőrzést minden olyan munkafolyamathoz, amely feltöltött fájloktól függ.

Közvetlen útvonalak vs. híd​

Használd az iframe hidat, ha a bővítményed a Chastify-n belül fut. Ez a Chastify hitelesítést a szülőoldalon tartja, és elkerüli az útvonal részleteinek iframe-nek való kitettségét.

Csak a saját Chastify felhasználói felületről vagy megbízható háttérfolyamatokból származó közvetlen munkamenet-útvonalakat használjon, amelyek már rendelkeznek érvényes kiterjesztési munkamenet-engedéllyel.