Laajennustiedostojen tallennustila

TLDR: store the file id, render with a signed URL.

When an extension uploads a file, Chastify returns a stable id and a short-lived signedUrl. Store the id in your extension config, state, or own database.

When your extension page loads later, call bridge.request("files.get", { fileId }) or GET /api/extensions/sessions/:sessionId/files/:fileId with the stored id. Chastify verifies that the file belongs to the same extension app, session, and lock, then returns a fresh signed R2 URL.

Render the image with <img src={file.signedUrl} />. Do not store signed URLs long-term because they expire.

Laajennustiedostojen tallennustila antaa käyttöönotetun laajennuksen ladata kuvatiedostoja, jotka kuuluvat lukituslaajennusistuntoon.

Käytä sitä, kun pelkkä JSON-muotoinen laajennustila ei riitä, esimerkiksi:

palapelikuvat
luodut esikatselut
haastekuvat
laajennuskohtainen media, joka tulisi tyhjentää lukituksen/istunnon avulla

Tämä tallennustila on erillään state.*:sta. Käytä state.*:ta pienille JSON-tiedoille. Käytä tiedostotallennustilaa vain binäärimedialle.

Suhde valtion päätepisteisiin

Laajennustila on tarkoitettu pienille istuntokohtaisen laajuisille JSON-tiedostoille. Käytä iframe-kehyksestä bridge read -komentoa REST-komennon suoran kutsumisen sijaan:

state.get

Tuo sillan komento reitittää:

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

Suorat taustajärjestelmän kutsut tilan kirjoittamiseen käyttävät installed-extension API-todennusmallia:

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

Älä lähetä kehittäjän API-avaimia iframe-/selainkoodiin.

Käytä taustajärjestelmällä kirjoitettua tilaa kestäville viitteille ja käyttöliittymädatalle, esimerkiksi:

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

Älä tallenna binääridataa, base64-kuvia, selaimen blob:-URL-osoitteita tai signedUrl:n pitkäikäisiä kopioita tilaan. Allekirjoitetut URL-osoitteet vanhenevat ja ne tulee päivittää files.get:lla, kun kuva renderöidään. Tilaan kirjoitettujen tiedostojen kokoa rajoittaa laajennussovelluksen stateMaxBytes-asetus, jonka oletusarvo on 64 KiB.

Tallennusmalli

Chastify tallentaa laajennustiedostot Chastify:n hallinnoimaan R2-tallennustilaan.

Jokaista ladattua tiedostoa seurataan seuraavilla tiedoilla:

scope: "extension"
appId
sessionId ja lockId suorituksenaikaisille/istuntotiedostoille
templateId tiedostoille, jotka on varattu tallennetulla lukitusmallilla
staged, draftId ja expiresAt vielä lunastamattomille asennuslatauksille
extensionKey
purpose

Ylläpitäjän portti ja kiintiöt

Admin controlled

Extension file storage is disabled by default.

Admins can enable it and configure:

maximum bytes per file
maximum total bytes per extension app
maximum total bytes per active extension session
maximum staged bytes per user and extension app
allowed MIME prefixes

The first implementation is image-focused and should use image/* uploads. SVG is not accepted by the storage service.

If storage is disabled or R2 is not configured, upload requests fail before the server reads the multipart file body.

Staged setup uploads count toward the current user's per-app staged quota until they are claimed. Claimed files count toward the per-extension app quota. Runtime files with a session id also count toward the per-session quota.

Määritä vaiheittaiset päätepisteet

Käytä asennuksen valmisteluvaihetta vain, kun asennuskäyttöliittymä suoritetaan ennen laajennusistunnon olemassaoloa.

Tämä on väliaikainen latausprosessi. Se on tarkoitettu asennus-/määritysnäyttöihin, joissa käyttäjä voi ladata tiedoston ja sulkea modaali-ikkunan tai poistaa laajennuksen käytöstä ennen lukituksen/istunnon luomista. Valmisteltu tiedosto ei ole pysyvä, ennen kuin se varataan tallentamalla siihen viittaava laajennuksen määritys.

Asennuskäyttöliittymät voivat tarkistaa saatavuuden ja nykyisen vaiheittaisen käytön ennen latausohjainten renderöintiä:

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

Vastaus sisältää stagedQuota:n nykyisen käyttäjän käyttämättömille, kyseisessä laajennussovelluksessa oleville vaiheistetuille tiedostoille:

{
  "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

Lomakekentät:

file: vaadittu kuvatiedosto
purpose: valinnainen lyhyt tunniste, kuten jigsaw-config-image
draftId: valinnainen asennusluonnoksen tunnus; käytä samaa arvoa uudelleen, kun yksi asennusmodaali on auki

Vastaus sisältää vakaan file.id-koodin ja lyhytikäisen allekirjoitetun URL-osoitteen välitöntä esikatselua varten.

Esimerkkivastaus:

{
  "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
  }
}

Jos haluat palauttaa asennustiedostojen lataukset sivun päivityksen jälkeen, listaa nykyisen käyttäjän ja laajennussovelluksen vaiheittaiset tiedostot:

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

Valinnaiset kyselyparametrit:

purpose: palauttaa vain yhden asennuskäyttötapauksen vaiheittaiset tiedostot
draftId: palauttaa vain tunnetun asennusluonnoksen tiedostot

Jos draftId jätetään pois, Chastify palauttaa nykyisen käyttäjän voimassaolevat, kyseiselle sovellukselle tallennetut tiedostot. Tämä on tarkoituksellista asennuskäyttöliittymille: käyttäjä voi ladata tiedostoja, ladata sivun uudelleen tai vaihtaa laitetta, ja asennusnäyttö voi palauttaa nämä väliaikaiset lataukset ennen lukituksen/mallin tallentamista.

Vaiheistetun listan vastaus sisältää myös stagedQuota:n, joka raportoi nykyisen käyttäjän voimassa olevan vaiheittaisen käytön kyseisessä sovelluksessa:

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

Asennuskäyttöliittymät voivat myös päivittää tai poistaa yhden vaiheittaisen tiedoston:

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

Vaiheittaisten tiedostojen lunastus myöhemmin

Erillistä selainpuolen "vaatimus"-päätepistettä ei ole. Valmisteltu tiedosto vaatimus tehdään automaattisesti, kun Chastify tallentaa lukitus- tai mallipohjan laajennusmäärityksen, joka viittaa valmisteltuun tiedostoon.

Nämä reitit varaavat valmiiksi asetetut tiedostot sen jälkeen, kun lukitus-/mallidokumentilla on tunniste, ja tallentavat sitten laajennuksen määrityksen uudelleen vaadituilla tiedostoviittauksilla. Jos määritys epäonnistuu, juuri luotu lukitus-/mallipohja peruutetaan, jotta valmiiksi asetetut tiedostot eivät jää kiinni rikkinäiseen määritykseen.

Jaettua mallipohjaa koskeva huomautus: Hyväksytyt jaetut lukot säilyttävät lähdemallipohjan tunnuksen kloonatussa aktiivisessa lukossa. Mallipohjalla vahvistetut tiedostot säilytetään siksi, kunhan kaikki kloonatut lukot viittaavat edelleen kyseiseen mallipohjaan. Jos lähdemallipohja poistetaan, Chastify viivyttää laajennustiedostojensa poistamista, kunnes viimeinen poistettuun mallipohjaan viittaava kloonattu lukko on poistettu tai arkistoitu.

Jotta lavastettu tiedosto voidaan lunastaa, tallenna tällainen viittaus asennuskäyttöliittymän lähettämään laajennuksen kokoonpanoon:

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

Tallennuksen yhteydessä Chastify etsii konfiguraatiosta provider: "chastify_storage"-tietueita, joilla on kelvollinen fileId, ja sitten:

varmistaa, että tiedosto kuuluu nykyiselle käyttäjälle ja laajennussovellukselle
hylkää vanhentuneet vaiheittaiset tiedostot
hylkää tiedostot, jotka on jo lunastanut toinen lukitus-/mallipohjakonteksti
merkitsee viitatut lavastetut tiedostot vaatimuksen kohteena oleviksi
sitoo vaaditut tiedostot tallennettuun lukkoon tai mallipohjaan
poistaa väliaikaiset signedUrl-, publicUrl- ja urlExpiresAt-kentät ennen kuin kokoonpano säilytetään
poistaa viittaamattomat vaiheittaiset tiedostot samasta storageDraftId-koodista

Hylätyt, tallennetut tiedostot poistetaan siivouksen jälkeen.

Nykyisen käyttäjän ja laajennussovelluksen omistaman tiedostotunnuksen asennusohjelman esikatselun päivittäminen:

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

Istunnon päätepisteet

Nämä päätepisteet vaativat normaalin laajennusistunnon valtuutuksen ja vaikutusalueet.

Perusreitti:

/api/extensions/sessions/:sessionId/files

Ominaisuudet

Tarkista tämä ennen latausohjainten renderöintiä.

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

Vaatii koodin locks:read.

Esimerkkivastaus:

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

Listaa tiedostot

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

Vaatii koodin locks:read.

Esimerkkivastaus:

{
  "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"
    }
  ]
}

Hanki yksi tiedosto

Käytä tätä, kun laajennuksellasi on jo tallennettu tiedostotunnus ja se tarvitsee vain uuden allekirjoitetun R2-linkin.

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

Vaatii koodin locks:read.

Tiedoston on kuuluttava samaan laajennussovellukseen, istuntoon ja lukkoon.

Esimerkkivastaus:

{
  "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"
  }
}

Lähetä tiedosto

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

Vaatii koodin locks:write.

Lomakekentät:

file: vaadittu kuvatiedosto
purpose: valinnainen lyhyt tunniste, kuten puzzle-image tai preview

Esimerkki:

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

Esimerkkivastaus:

{
  "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"
  }
}

Yleisiä latausvirheitä:

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

Poista tiedosto

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

Vaatii koodin locks:write.

Tiedoston on kuuluttava samaan laajennussovellukseen, istuntoon ja lukkoon.

Iframe Bridge -toiminnot

Iframe-laajennukset voivat käyttää pääverkkosiltaa ajonaikaisten tiedostojen lukemiseen. Ajonaikaisten tiedostojen lataus ja poisto ovat istuntomutaatioita, ja taustajärjestelmän tulisi suorittaa ne sovelluskohtaisella Developer API -avaimella ja x-chastify-main-token:lla.

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

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

image.src = refreshed.file.signedUrl;

Tuetut siltatoiminnot:

files.capabilities -> tarkista, onko tiedostojen tallennus käytössä ja mitä kiintiöitä sovelletaan
files.list -> listaa nykyisen laajennusistunnon omistamat tiedostot
files.get -> päivitä yksi allekirjoitettu R2-URL-osoite tallennetusta tiedostotunnuksesta

Asennuskehykset voivat käyttää muita sillannimiä ennen kuin ajonaikainen istunto on olemassa. Asennustilassa files.upload luo vaiheittaisia tiedostoja, files.list/files.staged.list listaa nykyisen käyttäjän ja sovelluksen vanhentumattomat vaiheittaiset tiedostot ja files.delete poistaa vaiheittaisen tiedoston. Asetuksen init-konteksti sisältää storageDraftId:n; lisää tämä arvo tallennettuun kokoonpanoosi muodossa storageDraftId, jos haluat Chastify:n puhdistavan viittaamattomat tiedostot samasta luonnoksesta heti tallennuksen yhteydessä.

Asennusohjelma files.upload hyväksyy myös koodin dataUrl yksinkertaisille iframe-asiakasohjelmille:

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

Suosi File- tai Blob-latauksia aina kun mahdollista. Käytä dataUrl:ta vain pienille luoduille kuville, koska base64-hyötykuormat ovat suurempia muistissa.

Allekirjoitetut linkit

Vakaan tiedoston tunniste on id.

Käytä signedUrl-komentoa tiedoston näyttämiseen tai lataamiseen. Allekirjoitetut linkit ovat lyhytikäisiä R2 GetObject URL-osoitteita, jotka on luotu Chastify:lla. publicUrl säilytetään yhteensopivuusaliaksena ja sisältää tällä hetkellä saman allekirjoitetun URL-osoitteen.

Kun allekirjoitettu linkki vanhenee, kutsu GET /api/extensions/sessions/:sessionId/files/:fileId-funktiota saadaksesi uuden linkin yhteen tallennettuun tiedostoon tai kutsu GET /api/extensions/sessions/:sessionId/files-funktiota päivittääksesi kaikki istuntotiedostolinkit.

Siivouksen elinkaari

Laajennustiedostot siivotaan BullMQ:n tukeman siivousjonon avulla.

Siivousaika on sovittu, kun:

laajennussovellus poistetaan
lukitus-/istuntolaajennusasiakirjat poistetaan lukituksen poiston/arkiston siivouksen aikana
tiedosto poistetaan eksplisiittisesti istunnon tiedostopäätepisteen kautta

Jono pitää kalliit R2-poistot ja tietokannan siivoukset poissa pyyntöpolulta. Jos jonon lisääminen jonoon epäonnistuu, palvelin palaa prosessin sisäiseen siivoukseen vastauksen jälkeen, jos pyyntökonteksti on olemassa, tai suoraan parhaansa mukaan tehtävään siivoukseen alemman tason elinkaarisiivouksessa.

Suorituskykyhuomautuksia

Valmiustarkistukset tulisi tehdä ennen latauskäyttöliittymän näyttämistä.
Lähetyksille on tiedosto-, istunto- ja sovelluskohtaisia rajoituksia.
Kiintiötarkistukset käyttävät indeksoitua UserFile-metatietoa scope + appId-, scope + sessionId- ja scope + lockId-muuttujalle.
Siivoaa vastaavat tiedostotietueet sen sijaan, että lataa kaikki URL-osoitteet muistiin.
Ladatut rasterikuvat käsitellään ja tallennetaan optimoituina verkkokuvina.

Turvallisuushuomautukset

Älä käsittele laajennuksen toimittamia kuvien URL-osoitteita luotettavana todisteena koodin täydentämisestä.
Tallenna vain Chastify-tiedostotunnisteella varustettuja tiedostotietueita luotettavina laajennustiedostoina.
Sido tiedostotietueet appId-, sessionId- ja lockId-alueille.
Pakota locks:write-koodi latauksiin ja poistoihin.
Vahvista MIME-tyyppi ja hylkää SVG.
Pidä ylläpitäjän hallitsemat kiintiöt käytössä ennen kuin sallit laajan julkisen käytön.
Käytä palvelinpuolen validointia kaikille työnkuluille, jotka ovat riippuvaisia ladatuista tiedostoista.

Suorat reitit vs. silta

Käytä iframe-siltaa, kun laajennuksesi toimii Chastify:n sisällä. Se pitää Chastify-todennuksen pääsivulla ja estää reittitietojen paljastamisen iframelle.

Käytä suoria istuntoreittejä vain ensimmäisen osapuolen Chastify-käyttöliittymästä tai luotettavista taustajärjestelmän työnkuluista, joilla on jo voimassa oleva laajennusistunnon valtuutus.

Suhde valtion päätepisteisiin​

Tallennusmalli​

Ylläpitäjän portti ja kiintiöt​

Määritä vaiheittaiset päätepisteet​

Vaiheittaisten tiedostojen lunastus myöhemmin​

Istunnon päätepisteet​

Ominaisuudet​

Listaa tiedostot​

Hanki yksi tiedosto​

Lähetä tiedosto​

Poista tiedosto​

Iframe Bridge -toiminnot​

Allekirjoitetut linkit​

Siivouksen elinkaari​

Suorituskykyhuomautuksia​

Turvallisuushuomautukset​

Suorat reitit vs. silta​

Suhde valtion päätepisteisiin

Tallennusmalli

Ylläpitäjän portti ja kiintiöt

Määritä vaiheittaiset päätepisteet

Vaiheittaisten tiedostojen lunastus myöhemmin

Istunnon päätepisteet

Ominaisuudet

Listaa tiedostot

Hanki yksi tiedosto

Lähetä tiedosto

Poista tiedosto

Iframe Bridge -toiminnot

Allekirjoitetut linkit

Siivouksen elinkaari

Suorituskykyhuomautuksia

Turvallisuushuomautukset

Suorat reitit vs. silta