واژه‌نامهٔ محصول و امنیت#

الامر چند واژهٔ دامنه‌ای با مرزهای آگاهانه دارد. در متن محصول، مستندات، API و بازبینی کد از تعریف‌های زیر استفاده کنید. واژه‌ای آشنا مانند «محیط»، «نسخه» یا «مجوز» ممکن است در الامر معنایی دقیق‌تر از کاربرد معمول در توسعهٔ وب داشته باشد.

شناسه‌های قراردادی مانند environment_revision و trusted_library عیناً و همان‌گونه که در قرارداد عمومی آمده‌اند نمایش داده می‌شوند.

محصول و مالکیت#

محیط (Environment)#

مقصدی که کاربر وارد آن می‌شود و تجربه‌اش می‌کند. هر محیط در رجیستری شناسه‌ای پایدار، مالک، entry/version نوع bundle، سیاست ورود، revisionهای تغییرناپذیر، هویت حضور، رکورد سلامت و مجموعهٔ دقیق Pluginهای نصب‌شدهٔ خود را دارد. سازندهٔ Environment مالک صحنه، چارچوب، تجربه و backend اختیاری است؛ پلتفرم بایت‌های frontend بررسی‌شده را نگه می‌دارد و سرو می‌کند.

محیط یک صفحه در پرتال توسعه‌دهندگان نیست و پلاگین هم نیست.

پلاگین (Plugin)#

قابلیتی نصب‌شدنی و نسخه‌دار که یک محیط از آن استفاده می‌کند. پلاگین واحد عمومی کشف، نصب، سازگاری، بازبینی و انتشار است. می‌تواند آداپتر فرانت‌اند، مولفهٔ بک‌اند یا هر دو را ارائه کند.

سرویس بک‌اند محصولی جدا در فروشگاه نیست؛ یک BackendComponent اختیاری داخل پلاگین است.

اپ (App)#

bundle تغییرناپذیری که مستقل تألیف شده و شخص آن را داخل یک Environment باز می‌کند. AppHost دسکتاپ آن را از origin متعلق به پلتفرم و داخل قاب sandbox‌شدهٔ Widget سرو می‌کند؛ App هرگز کد Environment را import نمی‌کند، صحنه را نمی‌خواند و credential زمان اجرا نمی‌گیرد. هر دو نیمهٔ App متعلق به ناشر App است: backend آن apps/<app>/packages/backend است که ADR-0080 آن را از جای services/ که ADR-0068 اول انتخاب کرده بود به آنجا برد.

اپ پلاگین نیست. پلاگین محیط را از داخل bundle خود محیط گسترش می‌دهد؛ اپ سندی جداست که فقط از راه Host Services به دنیا می‌رسد.

ویجت (Widget)#

سطح خودِ پلتفرم داخل هر Environment: قاب App، صندوق اعلان و پنل همراهی. Widget bundle نگه‌داری‌شدهٔ App را در iframe با origin بررسی‌شده باز می‌کند و مالک Grant قابلیت، اختیار میزبان و deadline درخواست‌هاست؛ Environment فقط وضعیت تعامل type-safe را می‌گیرد. تغییر حالت نمایش، سند و session App را حفظ می‌کند و از راه protocol تغییر presentation می‌رسد.

اپ و محیط هرگز نباید صندوق اعلان دوم پلتفرم را نصب کنند یا به DOM ویجت دست بزنند.

پروژه (Project)#

ظرف مدیریتی قابل ویرایشی که مالک در کنسول، API مدیریت و CLI با نام alamr استفاده می‌کند. نوع پروژه environment، app یا plugin است. ویرایش پروژه، نسخهٔ نامزد و تغییرناپذیر تازه‌ای می‌سازد و مقصد منتشرشده را بازنویسی نمی‌کند.

projectId با environmentId یا pluginId یکی نیست.

ناشر (Publisher)#

هویت عمومی‌ای که مالک نام‌های عمومی و پروژه‌هاست. تأیید ناشر یکی از وضعیت‌های رجیستری است. این تأیید فقط وضعیت ثبت‌شدهٔ ناشر را نشان می‌دهد و به معنی ایزوله یا بی‌خطر بودن هر کد فرانت‌اندی نیست.

رجیستری (Registry)#

منبع حقیقت هویت عمومی، رکوردهای کاتالوگ، بازبینی‌ها و نسخه‌های تغییرناپذیر، اعتبارسنجی بسته، وضعیت انتشار، اعتماد، سازگاری، تنظیمات، مجوز زمان اجرا، Plugin Grant، سلامت و حضور.

رابط کاربری، صحنهٔ سه‌بعدی، فرادادهٔ npm یا نسخه‌ای کپی‌شده از مستندات نباید به‌جای وضعیت رجیستری مرجع قرار گیرد.

پرتال توسعه‌دهندگان و کنسول#

پرتال توسعه‌دهندگان بخش عمومیِ رندرشده در سرور برای آموزش و کشف است: مستندات، کاتالوگ و صفحه‌های پلاگین، محیط، ناشر، مرجع و وضعیت. کنسول بخش مدیریتی احرازهویت‌شدهٔ آن است.

کنسول یکی از مصرف‌کنندگان همان API عمومی مدیریتی است که CLI و CI استفاده می‌کنند؛ مرجع خصوصی و انحصاری برای اعمال اختیار محصول نیست.

هاب (Hub)#

محیط معمولی با نام environment-zero. هاب مانند هر محیط مستقل دیگر از SDK، مسیر ورود، APIهای رجیستری و مدل نصب پلاگین عمومی استفاده می‌کند. مسیر ممتاز پلاگین ندارد.

ناحیه (Zone)#

صحنه‌ای محلی در برنامهٔ هاب با نشانی /z/:slug. همهٔ ناحیه‌ها مبدأ، زمان اجرا، هویت حضور، تنظیمات، نصب دقیق پلاگین‌ها، بازبینی محیط و بوم پایدار R3F هاب را به اشتراک می‌گذارند. ناحیه موجودیت رجیستری، پروژه، محیط یا مقصد انتشار نیست.

مکان (Place)#

اینکه شخص کجاست، با واژگان خود محیط: یک ناحیهٔ اختیاری و یک موقعیت اختیاری که هرکدام می‌توانند نباشند (ADR-0075). نبودن ناحیه دادهٔ گم‌شده نیست — یعنی آن دنیا چنین تقسیمی ندارد، و اپی که فقط همان چیزی را چاپ می‌کند که گرفته است هر دو نوع دنیا را درست نشان می‌دهد بی‌آنکه بداند در کدام است. موقعیت فقط وقتی شناسه دارد که محیط آن مکان را اعلام کرده باشد، و همین است که نشانیِ قابل‌ارجاع را از توصیف یک نیمکت جدا می‌کند.

هویت‌ها و رکوردهای تغییرناپذیر#

هویت پایدار#

شناسهٔ رجیستری که با تغییر نامک، نام بسته، میزبان یا نسخه همچنان همان محیط یا پلاگین را مشخص می‌کند. نام بستهٔ عمومی و نامک کاتالوگ، هویت پلتفرم نیستند.

بازبینی manifest محیط (EnvironmentManifestRevision)#

تصویری تغییرناپذیر از ورود محیط، نمایش در پرتال، قابلیت‌ها و نصب دقیق پلاگین‌ها. انتشار یکی از بازبینی‌های بررسی‌شده را فعال می‌کند و ویرایش بعدی بازبینی دیگری می‌سازد.

نسخهٔ انتشار پلاگین (PluginRelease)#

تصویری تغییرناپذیر با شماره نسخهٔ معنایی از فرادادهٔ پلاگین، آداپترهای فرانت‌اند، قرارداد مولفه‌های بک‌اند، طرح‌وارهٔ تنظیمات، مجوزها، توضیحات اعتماد، سازگاری، مستندات و هویت بستهٔ انتشار.

تغییر manifest یا بایت‌های بسته زیر یک نسخهٔ موجود تعارض است؛ نسخهٔ تازه‌ای منتشر کنید.

مولفهٔ بک‌اند (BackendComponent)#

قابلیت اختیاری در لایهٔ داده که داخل نسخهٔ پلاگین اعلام می‌شود. قرارداد آن هویت مولفه، پروتکل، دامنه‌های Grant و زمینهٔ عمومی را مشخص می‌کند. مولفهٔ بک‌اند فقط از Plugin Grant کوتاه‌عمر و اعتبارسنجی‌شده اختیار می‌گیرد.

بازبینی استقرار بک‌اند (BackendDeploymentRevision)#

تصویری تغییرناپذیر از نشانی زندهٔ یک مولفهٔ بک‌اند، نشانی اختیاری سلامت و پیکربندی عمومی و غیرمحرمانه. این بازبینی جدا از نسخهٔ پلاگین بررسی و منتشر می‌شود. اطلاعات محرمانه در زیرساخت استقرار می‌ماند.

بستهٔ انتشار (PackageArtifact)#

بایت‌های دقیق بستهٔ متصل به نسخهٔ پلاگین همراه روش تأمین، مشخصات بسته، اندازه، صحت و وضعیت اعتبارسنجی. بستهٔ مدیریت‌شده در الامر بارگذاری می‌شود؛ بستهٔ npm را رجیستری پیدا می‌کند و پس از اعتبارسنجی آینه می‌کند.

فقط مرز artifact-validator اجازه دارد بایت‌های بستهٔ مدیریت‌شده را بخواند و اعتبارسنجی کند. متادیتای رجیستری به‌تنهایی مدرک ایمنی بایت‌ها نیست.

al-amr.lock.json#

فایل قفل محیط که alamr add می‌سازد. هر نصب را به شناسهٔ پلاگین و نسخهٔ آن در رجیستری، آداپتر، بسته، مشخصات نصب و صحت SHA-512 مقید می‌کند. این فایل را دستی ویرایش نکنید.

انتشار#

مقصد انتشار#

شیء تغییرناپذیری که بررسی می‌شود: environment_revision، plugin_release یا backend_deployment_revision.

درخواست انتشار (PublicationSubmission)#

رکورد گردش‌کاری که یک مقصد را به چکیدهٔ تصویر ثابت، چکیدهٔ مجموعه بسته‌ها در صورت وجود، سطح نمایش، کانال، بررسی‌ها، عامل و وضعیت انتشار مقید می‌کند.

این درخواست، دادهٔ قابل ویرایش پروژه را به مرجع تبدیل نمی‌کند. بازبینی و انتشار همچنان به مقصد و چکیده‌های ثابت متصل می‌مانند.

چکیدهٔ تصویر ثابت و چکیدهٔ بسته‌ها#

چکیدهٔ تصویر ثابت همان مقصد تغییرناپذیر دقیق را مشخص می‌کند. برای نسخهٔ پلاگین، artifactDigest مجموعهٔ مرتب و دقیق بسته‌هایی را مشخص می‌کند که هنگام ساخت درخواست ثابت شده‌اند. اگر این مقدارها دیگر تطبیق نکنند، بازبینی و انتشار نهایی شکست می‌خورند.

سطح نمایش (Visibility)#

یکی از unlisted یا public. سطح نمایش هنگام ساخت درخواست انتشار انتخاب می‌شود و از وضعیت گردش‌کار و کانال جداست.

کانال (Channel)#

یکی از preview، beta یا stable. کانال میزان بلوغ نسخه را بیان می‌کند و بررسی‌ها، بازبینی، اعتبارسنجی بسته یا نسخه‌گذاری تغییرناپذیر را دور نمی‌زند.

پس‌گرفتن و تعلیق (yanked و suspended)#

دو وضعیت نهایی و مدیریتی که از published قابل دستیابی‌اند. قرارداد گذار برای هر دو دلیل می‌خواهد و مقصد را از حالت فعال خارج می‌کند. بسته به نوع مقصد، نشست‌های زمان اجرا یا Plugin Grantهای مرتبط نیز باطل می‌شوند.

نسخهٔ yanked پلاگین برای تکرارپذیری همچنان قابل شناسایی است، اما CLI نصب تازهٔ آن را در یک محیط نمی‌پذیرد.

بازگردانی (Rollback)#

جابه‌جاکردن اشاره‌گر فعال پروژه به یک بازبینی محیط یا نسخهٔ پلاگین قدیمی‌تر که هنوز منتشرشده و مجاز است. بازگردانی هیچ تصویر ثابتی را ویرایش نمی‌کند و دلیل ثبت‌شده می‌خواهد. مقصد مسدود یا منتشرنشده واجد شرایط نیست.

زمان اجرا و مجوز#

ورود یکپارچهٔ مرورگر (Browser SSO)#

نشست ورود تحت مالکیت رجیستری که میان ورود محیط‌ها و پرتال توسعه‌دهندگان مشترک است. هر محیط همچنان توکن و نشست زمان اجرای جدا و محدود به مبدأ خود می‌گیرد. Browser SSO از ورود CLI، توکن پروژهٔ CI و نشست مرورگر یا دستگاه دیگر جداست.

Authorization Code همراه PKCE#

پروتکل ورود برای برنامه‌های عمومیِ بدون راز، مانند محیط و CLI. روش PKCE S256 کد یک‌بارمصرف را به برنامه‌ای متصل می‌کند که مقدار راستی‌آزما را ساخته است. نشانی بازگشت دقیق ثبت می‌شود و تعویض امن کد، مقدار راستی‌آزما، state یا redirect_uri ممکن نیست.

نشست زمان اجرا (Runtime session)#

رکورد رجیستری برای یک صفحه یا دستگاه مجاز محیط. نشست می‌تواند standby، active، superseded، آزادشده، منقضی یا باطل باشد. داشتن مجوز ورود با مالکیت فعال زمان اجرا یکی نیست.

نشست اپ (App session)#

اختیار کوتاه‌عمر برای یک نسخهٔ دقیق از اپ، محصور به اجارهٔ زمان اجرای محیط والد، نسل میزبان، حالت نمایش و چکیدهٔ مجموعهٔ مجوزها. appActorSub آن نسبت به حساب و اپ زوجی است، پس اپ کاربر خودش را در محیط‌های مختلف می‌شناسد بی‌آنکه هرگز شناسهٔ خام حساب را بگیرد؛ با actorSub پلاگین یکی نیست. اپی که manifestش بلوک backend دارد کلاینت محرمانه است و بک‌اند خودش تبادل را امضا می‌کند، چون قاب مرورگر نمی‌تواند کلیدی را که این را ثابت می‌کند نگه دارد (ADR-0074).

هویت خصوصی (Principal)#

حسابی که رجیستری مالکیت زمان اجرای فعال را برای آن هماهنگ می‌کند. هر هویت خصوصی در یک لحظه فقط یک زمان اجرای فعال الامر دارد.

اجاره و حصار زمان اجرا#

مدرک کوتاه‌عمر و دارای نسخهٔ افزایشی که نشان می‌دهد یک نشست اکنون مالک اجرای فعال است. درخواست محافظت‌شده شناسهٔ نشست، شناسهٔ دقیق اجاره و نسخهٔ اجاره را حمل می‌کند. حصار قدیمی با 409 رد می‌شود و نبود هماهنگی در محیط عملیاتی با 503 و رویکرد بسته در هنگام خطا پاسخ می‌گیرد.

زمان اجرای جایگزین‌شده (Superseded Runtime)#

زمان اجرایی که فعال بوده و فعال‌شدن صفحهٔ جدیدتر جای آن را گرفته است. Plugin Grantهای آن باطل، حضور حذف و منابع پلاگین‌های همکار متوقف می‌شوند. قرارگرفتن صفحه در کانون به‌تنهایی مالکیت را برنمی‌گرداند؛ کاربر باید صفحه را صریحاً فعال کند.

کانال کنترل#

کانال فقط‌خواندنی و محدود به نشست و مبدأ که صفحهٔ غیرفعال برای دریافت تغییر فعالیت و خروج سراسری مرورگر نگه می‌دارد. اعتبارنامهٔ آن اجارهٔ Runtime ندارد و نمی‌تواند حضور بفرستد، Plugin Grant بگیرد، تنظیمات را تغییر دهد یا رابط پلاگین را اجرا کند.

حضور (Presence)#

مدرک رجیستری از اتصال زمان اجرای محیط. SDK فقط پس از مجوز، فعال‌شدن Runtime و تپش موفق، حضور را متصل گزارش می‌کند. پرچم ثابت «برخط» حضور واقعی نیست.

مجوز پلاگین (Plugin Grant)#

توکن امضاشده و کوتاه‌عمر برای یک نسخهٔ دقیق نصب‌شدهٔ پلاگین و استقرار منتشرشدهٔ بک‌اند. audience، دامنه‌ها، مبدأ، انقضا، زمینهٔ تغییرناپذیر، وضعیت مهمان و حصار اجارهٔ Runtime را حمل می‌کند. بک‌اند آن را محلی اعتبارسنجی می‌کند و وضعیت متغیر اجاره و ابطال را از رجیستری می‌پرسد.

شناسهٔ اختصاصی عامل#

نام مستعار پایدار کاربر که فقط در محدودهٔ یک پلاگین معنی دارد. مولفهٔ بک‌اند به جای شناسهٔ سراسری کاربر در اکوسیستم، همین شناسه را دریافت می‌کند.

اعتماد و مجوزهای پلاگین#

trusted_library#

کلاس زمان اجرای فرانت‌اند در v0.x. کد بستهٔ پلاگین در همان قلمرو JavaScript و با همان اختیار مرورگر محیط میزبان اجرا می‌شود. کتابخانهٔ مورد اعتماد میزبان است، نه کد راه‌دور در محیط ایزوله.

مجوز پلتفرم#

قابلیتی اعلامی که APIهای الامر می‌توانند اعمال کنند؛ مانند دسترسی به تنظیمات یا Plugin Grant. این مجوز اجرای دلخواه JavaScript، API مرورگر یا رفتار شبکه خارج از پلتفرم را محدود نمی‌کند.

نیاز مرورگر#

قابلیت مرورگری موردنیاز پلاگین، مانند دسترسی به رسانه یا دستگاه، همراه با مشخص‌بودن اجباری یا اختیاری بودن و دلیل آن. این مورد توضیح اعتماد است، نه اختیاری که رجیستری بدهد.

توضیح شبکه و داده#

مبدأهای بیرونی اعلام‌شدهٔ پلاگین، دلیل دسترسی، دادهٔ جمع‌آوری یا اشتراک‌گذاری‌شده، مدت نگهداری و سیاست اختیاری حریم خصوصی. بازبینی این موارد را می‌بیند، اما خود این توضیحات محیط ایزولهٔ شبکه در مرورگر ایجاد نمی‌کنند.

دامنهٔ Grant#

عملیاتی که یک مولفهٔ بک‌اند از راه Plugin Grant اعتبارسنجی‌شده می‌پذیرد. دامنه‌های Grant با مجوزهای فرانت‌اند پلتفرم و نیازهای مرورگر فرق دارند.

همراهی و اعلان#

همراه (Companion)#

کسی که حساب در سطح پلتفرم با او پیوند دارد، نه داخل یک دنیا. فهرست همراهان تنها از راه مراسم رضایتِ تعاملی که روی مبدأ رجیستری رندر می‌شود به یک اپ می‌رسد، و تنها برای حسابی که مالک همان فهرست است (ADR-0070). آنچه عبور می‌کند شناسهٔ زوجیِ اپ به‌همراه نام و آواتار نمایشی است. همراهانِ یک همراه، هر هم‌بستگیِ میان‌اپی از یک شخص، هر نشانه‌ای که به آواتار بچسبد و هر مسیری که به محیط برسد ممنوع می‌ماند.

کدِ دعوت (Invite code)#

کدِ همیشگی، مشتق‌شده و صدبیتی‌ای که هر حساب دارد — alamr- و بیست نویسه — و تنها نشانیِ لایهٔ همراهی است (ADR-0125). آدم کپی‌اش می‌کند، بیرونِ الامر می‌دهد، و هر کس آن را در پنلِ خودِ کلاینت بچسباند درخواستِ همراهی می‌فرستد. فقط digest ذخیره می‌شود؛ «کدِ تازه» آن را می‌چرخاند و کدِ قبلی دیگر پیدا نمی‌شود.

درخواستِ همراهی (Companionship request)#

آنچه چسباندنِ یک کد می‌سازد: یک درخواستِ در انتظار که صاحبِ کد می‌پذیرد، برای سی روز رد می‌کند، یا برای همیشه مسدود می‌کند — پاسخش در پنلِ دسکتاپ روی پلنِ دستگاه داده می‌شود. هر ردی که یک چسباندن می‌تواند بخورد یک منفیِ یکسان است، و کارت هیچ بایتی از فرستنده ندارد.

منبع اعلان (Notification source)#

اپ یا محیطی که اعلان از آن آمده است. منبع پیش از آنکه اجازهٔ انتشار داشته باشد واژگان رویدادهایش را در manifest اعلام می‌کند، و هویتی که روی اعلان دیده می‌شود از رجیستری می‌آید نه از متنی که منبع فرستاده. «منبع» با «مبدأ» یکی نیست: یکی اپ یا محیط است و دیگری مبدأ HTTP، و همین دو واژه به دو زیرسیستم متفاوت می‌روند — جدول واژگان پایین برای همین است.

شدت اعلان (Notification treatment)#

اینکه یک اعلان چقدر بلند است؛ پلتفرم تصمیم می‌گیرد، نه منبع (ADR-0085). دقیقاً سه حالت هست: announce یعنی صندوق، نشان نخوانده و کارت گذرا روی دنیا؛ file یعنی صندوق و نشان نخوانده؛ mute یعنی صندوق، بی‌صدا. mute هم سطر را می‌نویسد، چون ساکت‌کردن دستوری دربارهٔ توجه است نه دربارهٔ حافظه.

تنظیمات و هم‌زمانی#

دامنه‌های تنظیمات#

پنج لایه از بیشترین تا کمترین اولویت:

session > user_environment > user > environment > plugin_default

session محلی و ناپایدار است. user_environment برای یک کاربر در یک محیط است؛ user مقدار پشتیبان سراسری همان کاربر است؛ environment به پیکربندی تغییرناپذیر محیط تعلق دارد و plugin_default از طرح‌وارهٔ پلاگین می‌آید.

منشأ تنظیمات#

درخت موازی‌ای که مشخص می‌کند هر مقدار نهایی از کدام دامنه آمده است. مقدار ارث‌رسیده در لایهٔ پایدار کاربر کپی نمی‌شود.

ETag تنظیمات#

توکن تجمیعی هم‌زمانی که هم در بدنهٔ پاسخ و هم در سرآیند ETag برمی‌گردد. نوشتن و بازنشانی پایدار آن را در If-Match می‌فرستند. مقدار قدیمی با 412 شکست می‌خورد تا تغییر هم‌زمان دیگری بی‌صدا بازنویسی نشود.

واژگان فارسی#

گزارش اشکال به فارسی می‌رسد و همان واژه تعیین می‌کند عامل بعدی کدام زیرسیستم را باز کند. دو سطر اول گران‌ترین جفت‌اند: دو مفهوم متفاوت انگلیسی که واژهٔ فارسی‌شان یک حرف با هم فرق دارد و به دو نیمهٔ مخالف مخزن می‌روند.

فارسی	انگلیسی	کد کجاست
منبع	notification source	services/registry/src/notifications/
مبدأ	HTTP origin	بررسی CSRF و مبدأ iframe، بیشتر در پرتال توسعه‌دهندگان
اعلان	notice	services/registry/src/notifications/persist.ts
محیط	Environment	environments/
افزونه	Plugin	plugins/
اپ	App	apps/
همراه	companion	همراهی رجیستری، هرگز یک محیط
همراهی	companionship	لایهٔ پلتفرم که مالک فهرست همراهان است
کدِ دعوت	invite code	نشانیِ همیشگیِ همراهی، ADR-0125
درخواستِ همراهی	companionship request	یک درخواستِ در انتظار به ازای هر کدِ چسبانده
قدم	contribution credit	«هم‌قدم»، ابزار داخلی ساخت در apps/hamqadam

برای جزئیات گردش‌کار چرخهٔ انتشار، برای خطاهای عملیاتی عیب‌یابی و برای مدل کامل اعتماد اعتماد و امنیت را بخوانید.