معماری

پیش از تغییرات بزرگ، جای کد و قوانین مربوط به آن را پیدا کنید.

خلاصه

HolyArrs یک برنامهٔ Go است که برنامهٔ وب در آن تعبیه شده است. برنامهٔ وب و یک API از نوع JSON را روی پورت 6262 ارائه می‌کند و داده‌هایش را در 2 فایل SQLite داخل پوشهٔ پیکربندی نگه می‌دارد. به دانلودرها، منبع‌ها (از طریق Jackett یا Prowlarr)، سرورهای رسانه، کانال‌های اعلان و سرور فراداده (metadata) HolyArrs درخواست می‌فرستد.

یک درخواست را دنبال کنید. کسی در صفحهٔ کشف یک فیلم را درخواست می‌دهد.

1. requests درخواست را ثبت می‌کند.
2. بعد از تأیید، movies از sources ریلیزها را می‌خواهد.
3. قوانین انتخاب در mediafiles به آن‌ها امتیاز می‌دهند.
4. downloads بهترین ریلیز را به دانلودر می‌فرستد.
5. وقتی دانلود تمام شد، mediafiles فایل را وارد می‌کند.
6. به mediaservers و alerts خبر داده می‌شود.

نقشهٔ کد

app/backend/cmd/holyarrs/            main.go starts the program; wiring.go builds the modules and joins them
app/backend/internal/<module>/       one flat folder per module
app/backend/internal/core/           plumbing every module may use
app/backend/tools/                   dev-only programs
app/frontend/                        the SvelteKit web app; embed.go bundles its build
app/frontend/src/routes/<page>/      thin pages that combine module parts
app/frontend/src/lib/<module>/       each module's web code
app/frontend/src/lib/ui/             parts used by 2 or more modules, and nothing else
app/frontend/src/lib/core/           server client, app state, helpers
app/tests/                           end-to-end tests (Playwright)
deploy/                              the Dockerfile and release scripts
docs/                                guides and these pages

فایل go.mod در ریشهٔ ریپو است، چون go:embed نمی‌تواند به پوشهٔ والد برسد.

هر چیز کجاست

می‌خواهید این را تغییر دهید	اینجا ببینید
چگونگی انتخاب یک ریلیز	internal/mediafiles
یک کلاینت دانلودر	internal/downloads، آزمایش‌های قرارداد در internal/downloads/conformance_test.go
یک کانال اعلان	internal/alerts
ورود، کاربران، کلیدهای API	internal/accounts
ویزارد اولین اجرا	internal/setup، app/frontend/src/routes/welcome
وارد کردن یک فایل تمام‌شده (باز کردن آرشیو، تگ‌ها، تطبیق)	internal/importer
پوشه‌های کتابخانه، پذیرفتن و تغییر نام	internal/library
چگونگی انتخاب و ترتیب ردیف‌ها و قفسه‌ها	internal/suggest
کدام بخش‌های برنامه روشن‌اند	internal/core/parts
نشانی یک صفحه	app/frontend/src/routes/
یک مهاجرت (migration)	internal/core/database/migrations/
ایمیج Docker	deploy/Dockerfile

قوانین

بررسی‌های app/backend/tools/structurecheck اگر یکی از قوانین شکسته شود، بیلد را رد می‌کنند. آن‌ها را با دستور صفحهٔ آزمایش اجرا کنید.

• ترتیب لایه‌ها. یک ماژول فقط ماژول‌های لایهٔ پایین‌تر را import می‌کند، آن هم فقط بستهٔ ریشهٔ آن‌ها را. ماژول‌های هم‌لایه هرگز یکدیگر را import نمی‌کنند.
• صدا زدن به بالا. وقتی ماژولی پایین چیزی از ماژولی بالاتر لازم دارد، ماژول بالا داده‌های ساده را به پایین می‌دهد، یا ماژول پایین یک interface کوچک تعریف می‌کند که wiring.go آن را پر می‌کند.
• SQL در خانهٔ خودش می‌ماند. فقط فایل‌های store*.go خود ماژول SQL دارند و فقط روی جدول‌های خودش. برای خواندن ردیف‌های ماژول دیگر، سرویس آن را صدا بزنید.
• جدول‌های مشترک مال core هستند. به settings، schedules، secrets، jobs و events از راه کمک‌کننده‌های core برسید.
• یک راه برای بیرون رفتن. هر درخواست به بیرون از core/outbound می‌گذرد.
• ویژگی‌های نگه‌داشته‌شده یک کلید در core/startup ثبت می‌کنند. تا وقتی کلید خاموش است، مسیر وجود ندارد و صفحه آن ویژگی را پنهان می‌کند.
• بستهٔ همه‌کاره نداریم. هیچ util، common، shared یا helpers نیست.

ترتیب لایه‌ها در ماژول‌ها آمده است.

برای حرفه‌ای‌ها

داخل یک ماژول

همهٔ ماژول‌های بک‌اند از یک نام‌گذاری فایل استفاده می‌کنند.

فایل	محتوا
routes.go	مسیرهای API، هر کدام با دسترسی لازمش
service.go و فایل‌های موضوعی	منطقی که ماژول‌های دیگر صدا می‌زنند
store.go، store_<topic>.go	همهٔ SQL مربوط به جدول‌های خود ماژول
types.go	رکوردهای ماژول

در سمت وب، lib/<module>/ شامل index.ts (آنچه ماژول‌های دیگر مجازند استفاده کنند)، بخش‌های Svelte و آزمایش‌های آن‌هاست، و api.ts و state.svelte.ts فقط وقتی ماژول فراخوانی یا state مخصوص خودش دارد.

بسته‌های core

Core زیرساخت است. قانون محصول ندارد و هیچ ماژولی را import نمی‌کند.

بسته	محتوا
core/database	باز کردن و مهاجرت هر دو فایل SQLite، کمک‌کننده‌های query، تنظیمات و رویدادها، فیلدهای مشترک ردیف، کوتاه کردن تاریخچه
core/files	کمک‌کننده‌های فایل و پوشه، فضای خالی دیسک
core/releasename	کیفیت، گروه و شمارهٔ قسمت‌ها از روی نام یک ریلیز
core/outbound	تنها راه صدا زدن سرورهای بیرونی، همراه با بررسی نشانی
core/secrets	ذخیرهٔ کلیدها و چرخش کلید
core/logs	لاگ برنامه و یادداشت‌های کرش
core/jobs	صف کارها، زمان‌بندی‌ها و حلقه‌هایی که بعد از کرش دوباره شروع می‌شوند
core/webserver	زیرساخت router، URL base، فشرده‌سازی، ارسال زنده
core/startup	کاربر اجرا، حالت کم‌حافظه، کلیدهای ویژگی‌های نگه‌داشته‌شده، سقف حافظه، بخش‌ها
core/parts	کلیدهای بخش‌ها که هر ماژول پیش از ارائه یا اجرا از آن‌ها می‌پرسد
core/model	نوع‌های مشترک مثل actor و subject

وقتی core باید به داده‌های یک ماژول دست بزند، ماژول در wiring.go یک hook در core ثبت می‌کند. چرخش کلید این‌طور کار می‌کند.

داده

فایل	محتوا
holyarrs.db	کتابخانه، درخواست‌ها، تنظیمات و هر چیز مهم دیگر
holyarrs-events.db	تاریخچه و ردیف‌های رویداد دیگر. بزرگ می‌شود و بدون دست زدن به فایل اصلی کوتاه می‌شود

مهاجرت‌ها فایل‌های SQL شماره‌دار در core/database/migrations/main و core/database/migrations/events هستند. هنگام شروع اجرا می‌شوند.

صفحه‌های مرتبط

• ماژول‌ها
• مشارکت
• آزمایش