मुख्य कंटेंट तक स्किप करें

एक्सटेंशन फ़ाइल संग्रहण

एक्सटेंशन फ़ाइल स्टोरेज एक सक्षम एक्सटेंशन को लॉक एक्सटेंशन सेशन से संबंधित इमेज फ़ाइलों को अपलोड करने की अनुमति देता है।

इसका उपयोग तब करें जब एक्सटेंशन स्टेट JSON पर्याप्त न हो, उदाहरण के लिए:

  • पहेली चित्र
  • उत्पन्न पूर्वावलोकन
  • चुनौती तस्वीरें
  • एक्सटेंशन-विशिष्ट मीडिया जिसे लॉक/सेशन के साथ साफ़ किया जाना चाहिए

यह स्टोरेज state.* से अलग है। छोटे JSON डेटा के लिए state.* का उपयोग करें। फ़ाइल स्टोरेज का उपयोग केवल बाइनरी मीडिया के लिए करें।

राज्य के अंतिम बिंदुओं से संबंध

एक्सटेंशन स्टेट छोटे सेशन-स्कोप वाले JSON के लिए है। iframe से, सीधे REST को कॉल करने के बजाय ब्रिज रीड कमांड का उपयोग करें:

state.get

वह ब्रिज कमांड रूट इस ओर जाता है:

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

स्टेट लिखने के लिए डायरेक्ट बैकएंड कॉल इंस्टॉल्ड-एक्सटेंशन एपीआई प्रमाणीकरण मॉडल का उपयोग करते हैं:

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

डेवलपर एपीआई कुंजी को आईफ्रेम/ब्राउज़र कोड में न भेजें।

उदाहरण के लिए, टिकाऊ संदर्भों और UI डेटा के लिए बैकएंड-लिखित स्थिति का उपयोग करें:

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

बाइनरी डेटा, बेस64 इमेज, ब्राउज़र blob: URL या signedUrl की दीर्घकालिक प्रतियां स्टेट में संग्रहीत न करें। हस्ताक्षरित URL की समय सीमा समाप्त हो जाती है और इमेज रेंडर होने पर उन्हें files.get से रीफ़्रेश किया जाना चाहिए। स्टेट राइट्स का आकार एक्सटेंशन ऐप की stateMaxBytes सेटिंग द्वारा सीमित है, जो डिफ़ॉल्ट रूप से 64 KiB है।

भंडारण मॉडल

Chastify एक्सटेंशन फ़ाइलों को Chastify-प्रबंधित R2 स्टोरेज में संग्रहीत करता है।

अपलोड की गई प्रत्येक फ़ाइल को निम्नलिखित के साथ ट्रैक किया जाता है:

  • scope: "extension"
  • appId
  • रनटाइम/सेशन फ़ाइलों के लिए sessionId और lockId
  • सहेजे गए लॉक टेम्पलेट द्वारा दावा की गई फ़ाइलों के लिए templateId
  • staged, draftId और expiresAt उन सेटअप अपलोड के लिए हैं जिन्हें अभी तक किसी ने क्लेम नहीं किया है।
  • extensionKey
  • purpose

प्रशासनिक गेट और कोटा

स्टेजिंग एंडपॉइंट्स सेटअप करें

सेटअप स्टेजिंग का उपयोग केवल तभी करें जब एक्सटेंशन सेशन मौजूद होने से पहले सेटअप यूआई चलता हो।

यह एक अस्थायी अपलोड प्रक्रिया है। यह सेटअप/कॉन्फ़िगरेशन स्क्रीन के लिए मौजूद है, जहाँ उपयोगकर्ता फ़ाइल अपलोड कर सकता है, फिर लॉक/सेशन बनाने से पहले मोडल को बंद कर सकता है या एक्सटेंशन को निष्क्रिय कर सकता है। स्टेज की गई फ़ाइल तब तक स्थायी नहीं रहती जब तक कि उसे संदर्भित करने वाले एक्सटेंशन कॉन्फ़िगरेशन को सहेजकर उस पर दावा नहीं किया जाता।

अपलोड नियंत्रण प्रदर्शित करने से पहले सेटअप यूआई उपलब्धता और वर्तमान चरणबद्ध उपयोग की जांच कर सकते हैं:

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

प्रतिक्रिया में उस एक्सटेंशन ऐप पर वर्तमान उपयोगकर्ता की समाप्ति से पहले स्टेज की गई फ़ाइलों के लिए stagedQuota शामिल है:

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

फॉर्म फ़ील्ड:

  • file: आवश्यक छवि फ़ाइल
  • purpose: वैकल्पिक संक्षिप्त पहचानकर्ता जैसे jigsaw-config-image
  • draftId: वैकल्पिक सेटअप ड्राफ्ट आईडी; एक सेटअप मॉडल खुला होने पर समान मान का पुनः उपयोग करें

प्रतिक्रिया में एक स्थिर file.id और तत्काल पूर्वावलोकन के लिए एक अल्पकालिक हस्ताक्षरित URL शामिल है।

उदाहरण प्रतिक्रिया:

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

पेज रिफ्रेश होने के बाद सेटअप अपलोड को पुनर्स्थापित करने के लिए, वर्तमान उपयोगकर्ता और एक्सटेंशन ऐप के लिए स्टेज्ड फ़ाइलों की सूची बनाएं:

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

वैकल्पिक क्वेरी पैरामीटर:

  • purpose: केवल एक सेटअप उपयोग मामले के लिए तैयार की गई फ़ाइलें लौटाएँ
  • draftId: केवल ज्ञात सेटअप ड्राफ्ट से फ़ाइलें लौटाएँ

यदि draftId को छोड़ दिया जाता है, तो Chastify उस ऐप के लिए वर्तमान उपयोगकर्ता की बिना समय सीमा समाप्त हुई स्टेज्ड फ़ाइलों को लौटाता है। सेटअप यूआई के लिए यह जानबूझकर किया गया है: उपयोगकर्ता फ़ाइलें अपलोड कर सकता है, पेज को रीलोड कर सकता है या डिवाइस बदल सकता है, और लॉक/टेम्प्लेट सहेजे जाने से पहले सेटअप स्क्रीन उन अस्थायी अपलोड को पुनर्स्थापित कर सकती है।

स्टेज्ड लिस्ट रिस्पॉन्स में stagedQuota भी शामिल है, जो उस ऐप के लिए वर्तमान उपयोगकर्ता के अनएक्सपायर्ड स्टेज्ड उपयोग की रिपोर्ट करता है:

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

सेटअप यूआई किसी एक स्टेज्ड फ़ाइल को रीफ़्रेश या डिलीट भी कर सकता है:

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

बाद में फर्जी फाइलों पर दावा करना

ब्राउज़र की ओर से कोई अलग "क्लेम" एंडपॉइंट नहीं है। स्टेज की गई फ़ाइल को स्वचालित रूप से क्लेम कर लिया जाता है जब Chastify एक लॉक या टेम्प्लेट एक्सटेंशन कॉन्फ़िगरेशन को सहेजता है जो स्टेज की गई फ़ाइल को संदर्भित करता है।

ये रूट लॉक/टेम्प्लेट दस्तावेज़ को आईडी मिलने के बाद स्टेज्ड फ़ाइलों पर दावा करते हैं, फिर दावा किए गए फ़ाइल संदर्भों के साथ एक्सटेंशन कॉन्फ़िगरेशन को पुनः सहेजते हैं। यदि दावा विफल हो जाता है, तो नवनिर्मित लॉक/टेम्प्लेट को रोलबैक कर दिया जाता है ताकि स्टेज्ड फ़ाइलें किसी टूटे हुए कॉन्फ़िगरेशन से जुड़ी न रह जाएं।

साझा टेम्पलेट नोट: स्वीकृत साझा लॉक क्लोन किए गए सक्रिय लॉक पर स्रोत टेम्पलेट आईडी को बनाए रखते हैं। इसलिए, टेम्पलेट-दावा की गई फ़ाइलें तब तक सुरक्षित रहती हैं जब तक कोई क्लोन किया गया लॉक उस टेम्पलेट को संदर्भित करता रहता है। यदि स्रोत टेम्पलेट हटा दिया जाता है, तो Chastify इसकी एक्सटेंशन फ़ाइलों को तब तक हटाने में देरी करता है जब तक कि हटाए गए टेम्पलेट को संदर्भित करने वाला अंतिम क्लोन किया गया लॉक हटा या संग्रहीत नहीं कर दिया जाता।

किसी स्टेज्ड फ़ाइल को क्लेम करने योग्य बनाने के लिए, सेटअप UI द्वारा सबमिट किए गए एक्सटेंशन कॉन्फ़िगरेशन में इस तरह का एक संदर्भ स्टोर करें:

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

सेव करने पर, Chastify कॉन्फ़िगरेशन में वैध fileId वाले provider: "chastify_storage" रिकॉर्ड की स्कैनिंग करता है, फिर:

  • यह सत्यापित करता है कि फ़ाइल वर्तमान उपयोगकर्ता और एक्सटेंशन ऐप से संबंधित है।
  • एक्सपायर हो चुकी स्टेज्ड फाइलों को अस्वीकार करता है
  • किसी अन्य लॉक/टेम्प्लेट संदर्भ द्वारा पहले से ही दावा की गई फ़ाइलों को अस्वीकार करता है
  • दावा किए गए अनुसार संदर्भित चरणबद्ध फाइलों पर निशान लगाए गए।
  • दावा की गई फ़ाइलों को सहेजे गए लॉक या टेम्पलेट से जोड़ता है
  • कॉन्फ़िगरेशन को सहेजने से पहले अस्थायी signedUrl, publicUrl और urlExpiresAt फ़ील्ड हटा दिए जाते हैं।
  • storageDraftId से अप्रमाणित स्टेज्ड फ़ाइलों को हटाता है

परित्यक्त स्टेज्ड फाइलें जिन्हें कभी सहेजा नहीं जाता है, उनकी समय सीमा समाप्त होने के बाद सफाई प्रक्रिया द्वारा हटा दी जाती हैं।

वर्तमान उपयोगकर्ता और एक्सटेंशन ऐप के स्वामित्व वाली फ़ाइल आईडी के लिए सेटअप पूर्वावलोकन को रीफ़्रेश करने के लिए:

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

सत्र समाप्ति बिंदु

इन एंडपॉइंट्स के लिए सामान्य एक्सटेंशन सेशन ऑथराइजेशन और स्कोप की आवश्यकता होती है।

आधार पथ:

/api/extensions/sessions/:sessionId/files

क्षमताओं

अपलोड नियंत्रणों को प्रदर्शित करने से पहले इसकी जांच कर लें।

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

इसके लिए locks:read की आवश्यकता है।

उदाहरण प्रतिक्रिया:

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

फ़ाइलों की सूची

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

इसके लिए locks:read की आवश्यकता है।

उदाहरण प्रतिक्रिया:

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

एक फ़ाइल प्राप्त करें

इसका उपयोग तब करें जब आपके एक्सटेंशन में पहले से ही एक संग्रहीत फ़ाइल आईडी हो और उसे केवल एक नए हस्ताक्षरित R2 लिंक की आवश्यकता हो।

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

इसके लिए locks:read की आवश्यकता है।

फ़ाइल का एक्सटेंशन ऐप, सेशन और लॉक एक ही होना चाहिए।

उदाहरण प्रतिक्रिया:

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

फ़ाइल अपलोड करें

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

इसके लिए locks:write की आवश्यकता है।

फॉर्म फ़ील्ड:

  • file: आवश्यक छवि फ़ाइल
  • purpose: वैकल्पिक संक्षिप्त पहचानकर्ता जैसे puzzle-image या preview

उदाहरण:

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

उदाहरण प्रतिक्रिया:

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

सामान्य अपलोड त्रुटियाँ:

  • 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

फ़ाइल नष्ट करें

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

इसके लिए locks:write की आवश्यकता है।

फ़ाइल का एक्सटेंशन ऐप, सेशन और लॉक एक ही होना चाहिए।

आईफ्रेम ब्रिज क्रियाएँ

आईफ़्रेम एक्सटेंशन रनटाइम फ़ाइल रीड के लिए पैरेंट वेब ब्रिज का उपयोग कर सकते हैं। रनटाइम फ़ाइल अपलोड और डिलीट सेशन म्यूटेशन हैं और इन्हें आपके बैकएंड द्वारा ऐप-स्कोप डेवलपर API कुंजी और x-chastify-main-token के साथ निष्पादित किया जाना चाहिए।

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

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

image.src = refreshed.file.signedUrl;

समर्थित ब्रिज क्रियाएँ:

  • files.capabilities -> जांचें कि फ़ाइल संग्रहण सक्षम है या नहीं और कौन से कोटा लागू होते हैं।
  • files.list -> वर्तमान एक्सटेंशन सत्र के स्वामित्व वाली फ़ाइलों की सूची
  • files.get -> संग्रहीत फ़ाइल आईडी से एक हस्ताक्षरित R2 URL को रीफ़्रेश करें

रनटाइम सेशन शुरू होने से पहले सेटअप आईफ्रेम अतिरिक्त ब्रिज नामों का उपयोग कर सकते हैं। सेटअप मोड में, files.upload स्टेज्ड फ़ाइलें बनाता है, files.list/files.staged.list वर्तमान उपयोगकर्ता और ऐप के लिए एक्सपायर न हुई स्टेज्ड फ़ाइलों की सूची दिखाता है, और files.delete एक स्टेज्ड फ़ाइल को हटाता है। सेटअप इनिट कॉन्टेक्स्ट में storageDraftId शामिल है; यदि आप चाहते हैं कि Chastify सेव करने पर उसी ड्राफ़्ट से अनरेफरेंस्ड फ़ाइलों को तुरंत साफ़ कर दे, तो इस मान को अपनी सेव की गई कॉन्फ़िगरेशन में storageDraftId के रूप में शामिल करें।

Setup files.upload सरल iframe क्लाइंट के लिए dataUrl को भी स्वीकार करता है:

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

जहां तक ​​संभव हो, File या Blob अपलोड को प्राथमिकता दें। dataUrl का उपयोग केवल छोटी जनरेटेड इमेज के लिए करें क्योंकि बेस64 पेलोड मेमोरी में अधिक जगह लेते हैं।

स्थिर फ़ाइल पहचानकर्ता id है।

फ़ाइल को देखने या डाउनलोड करने के लिए signedUrl का उपयोग करें। हस्ताक्षरित लिंक अल्पकालिक R2 GetObject URL हैं जो Chastify द्वारा जनरेट किए जाते हैं। publicUrl को संगतता उपनाम के रूप में रखा गया है और वर्तमान में इसमें वही हस्ताक्षरित URL शामिल है।

जब कोई हस्ताक्षरित लिंक समाप्त हो जाता है, तो एक संग्रहीत फ़ाइल के लिए एक नया लिंक प्राप्त करने के लिए GET /api/extensions/sessions/:sessionId/files/:fileId को कॉल करें, या सभी सत्र फ़ाइल लिंक को रीफ़्रेश करने के लिए GET /api/extensions/sessions/:sessionId/files को कॉल करें।

सफाई जीवनचक्र

एक्सटेंशन फाइलों को BullMQ समर्थित क्लीनअप क्यू के माध्यम से साफ किया जाता है।

सफाई का कार्य निम्नलिखित समय पर निर्धारित किया जाता है:

  • एक एक्सटेंशन ऐप हटा दिया गया है
  • लॉक हटाने/आर्काइव क्लीनअप के दौरान लॉक/सेशन एक्सटेंशन दस्तावेज़ हटा दिए जाते हैं।
  • सेशन फ़ाइल एंडपॉइंट के माध्यम से एक फ़ाइल को स्पष्ट रूप से हटाया जाता है।

क्यू, महंगे R2 विलोपन और डेटाबेस सफाई को अनुरोध पथ से बाहर रखता है। यदि क्यू में डेटा डालना विफल हो जाता है, तो सर्वर प्रतिक्रिया के बाद प्रक्रिया के भीतर सफाई करता है, जहां अनुरोध संदर्भ मौजूद होता है, या निचले स्तर के जीवनचक्र सफाई में सीधे सर्वोत्तम प्रयास सफाई करता है।

प्रदर्शन संबंधी नोट्स

  • अपलोड यूजर इंटरफेस दिखाए जाने से पहले क्षमता की जांच होनी चाहिए।
  • अपलोड प्रति फ़ाइल, प्रति सत्र और प्रति ऐप सीमाओं द्वारा सीमित हैं।
  • कोटा जांच में scope + appId, scope + sessionId और scope + lockId के लिए अनुक्रमित UserFile मेटाडेटा का उपयोग किया जाता है।
  • सभी यूआरएल को मेमोरी में लोड करने के बजाय, फ़ाइल रिकॉर्ड से मेल खाने वाली स्ट्रीम को साफ करें।
  • अपलोड की गई रास्टर छवियों को संसाधित किया जाता है और अनुकूलित वेब छवियों के रूप में संग्रहीत किया जाता है।

सुरक्षा संबंधी नोट्स

  • एक्सटेंशन द्वारा प्रदान किए गए इमेज यूआरएल को विश्वसनीय पूर्णता प्रमाण के रूप में न मानें।
  • केवल Chastify द्वारा जारी किए गए फ़ाइल रिकॉर्ड को ही विश्वसनीय एक्सटेंशन फ़ाइलों के रूप में संग्रहीत करें।
  • फ़ाइल रिकॉर्ड को appId, sessionId और lockId से बाइंड करें।
  • अपलोड और डिलीट के लिए locks:write लागू करें।
  • MIME प्रकार को सत्यापित करें और SVG को अस्वीकार करें।
  • सार्वजनिक उपयोग की अनुमति देने से पहले प्रशासक-नियंत्रित कोटा को सक्षम रखें।
  • अपलोड की गई फ़ाइलों पर निर्भर किसी भी वर्कफ़्लो के लिए सर्वर-साइड सत्यापन का उपयोग करें।

सीधे रास्ते बनाम पुल

जब आपका एक्सटेंशन Chastify के अंदर चल रहा हो, तो iframe ब्रिज का उपयोग करें। यह Chastify प्रमाणीकरण को पैरेंट पेज में ही रखता है और iframe को रूट विवरण उजागर होने से बचाता है।

प्रत्यक्ष सत्र मार्गों का उपयोग केवल प्रथम-पक्ष Chastify UI या विश्वसनीय बैकएंड फ़्लो से करें जिनके पास पहले से ही वैध एक्सटेंशन सत्र प्राधिकरण है।