Αρχιτεκτονική

Βρες πού βρίσκεται ο κώδικας και ποιοι κανόνες ισχύουν πριν αλλάξεις κάτι μεγάλο.

Με λίγα λόγια

Το HolyArrs είναι ένα πρόγραμμα σε Go με τη διαδικτυακή εφαρμογή ενσωματωμένη. Σερβίρει τη διαδικτυακή εφαρμογή και ένα JSON API στη θύρα 6262, και κρατά τα δεδομένα του σε 2 αρχεία SQLite στον φάκελο ρυθμίσεων. Επικοινωνεί με προγράμματα λήψεων, Πηγές (μέσω Jackett ή Prowlarr), διακομιστές πολυμέσων, κανάλια ειδοποιήσεων και τον διακομιστή μεταδεδομένων του 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 βρίσκεται στη ρίζα του repo επειδή το go:embed δεν φτάνει σε γονικό φάκελο.

Πού θα βρεις κάθε πράγμα

Θες να αλλάξεις	Κοίτα στο
Πώς επιλέγεται μια κυκλοφορία	internal/mediafiles
Έναν client προγράμματος λήψεων	internal/downloads, contract tests στο 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/
Την image του Docker	deploy/Dockerfile

Οι κανόνες

Οι έλεγχοι στο app/backend/tools/structurecheck αποτυγχάνουν το build όταν σπάσει κάποιος κανόνας. Τρέξε τους με τη γραμμή που βρίσκεται στις Δοκιμές.

• Σειρά επιπέδων. Ένα module εισάγει μόνο modules από χαμηλότερο επίπεδο, και μόνο το βασικό τους package. Modules του ίδιου επιπέδου δεν εισάγουν ποτέ το ένα το άλλο.
• Κλήση προς τα πάνω. Όταν ένα χαμηλότερο module χρειάζεται κάτι από ένα ψηλότερο, το ψηλότερο περνά απλά δεδομένα προς τα κάτω, ή το χαμηλότερο ορίζει ένα μικρό interface που το συμπληρώνει το wiring.go.
• Η SQL μένει σπίτι της. Μόνο τα δικά του αρχεία store*.go ενός module έχουν SQL, και μόνο πάνω στους δικούς του πίνακες. Για να διαβάσεις γραμμές άλλου module, κάλεσε το service του.
• Οι κοινοί πίνακες ανήκουν στο core. Φτάσε στα settings, schedules, secrets, jobs και events μέσα από βοηθητικές συναρτήσεις του core.
• Μία έξοδος. Κάθε εξωτερική κλήση περνά από το core/outbound.
• Οι κρατημένες λειτουργίες δηλώνουν έναν διακόπτη στο core/startup. Όσο είναι απενεργοποιημένος, η διαδρομή δεν υπάρχει και η σελίδα κρύβει τη λειτουργία.
• Όχι πακέτα-μπαούλα. Κανένα util, common, shared ή helpers.

Η σειρά των επιπέδων βρίσκεται στο Modules.

Για έμπειρους

Μέσα σε ένα module

Κάθε module του backend χρησιμοποιεί τα ίδια ονόματα αρχείων.

Αρχείο	Περιέχει
routes.go	Διαδρομές API, καθεμία με το δικαίωμα που χρειάζεται
service.go και αρχεία θεμάτων	Λογική που καλούν άλλα modules
store.go, store_<topic>.go	Όλη η SQL για τους δικούς του πίνακες του module
types.go	Οι εγγραφές του module

Στην πλευρά του web, το lib/<module>/ περιέχει το index.ts (ό,τι επιτρέπεται να χρησιμοποιούν τα άλλα modules), τα κομμάτια του σε Svelte και τις δοκιμές τους, και τα api.ts και state.svelte.ts μόνο όταν έχει δικές του κλήσεις ή δική του κατάσταση.

Πακέτα του core

Το core είναι οι σωληνώσεις. Δεν έχει κανόνες προϊόντος και δεν εισάγει κανένα module.

Πακέτο	Περιέχει
core/database	Άνοιγμα και migration και των δύο αρχείων SQLite, βοηθητικά για queries, ρυθμίσεις και events, κοινά πεδία γραμμών, κλάδεμα ιστορικού
core/files	Βοηθητικά για αρχεία και φακέλους, ελεύθερος χώρος δίσκου
core/releasename	Ποιότητα, ομάδα και αριθμούς επεισοδίων από το όνομα μιας κυκλοφορίας
core/outbound	Ο μοναδικός τρόπος κλήσης εξωτερικών διακομιστών, με ελέγχους διευθύνσεων
core/secrets	Το αποθηκευτήριο κλειδιών και η εναλλαγή κλειδιών
core/logs	Το αρχείο καταγραφής της εφαρμογής και οι σημειώσεις κατάρρευσης
core/jobs	Η ουρά εργασιών, οι χρονοπρογραμματισμοί και οι βρόχοι που ξαναξεκινούν μετά από κατάρρευση
core/webserver	Σωληνώσεις router, URL base, συμπίεση, live push
core/startup	Χρήστης εκτέλεσης, λειτουργία χαμηλής μνήμης, διακόπτες κρατημένων λειτουργιών, όριο μνήμης, ενότητες
core/parts	Οι διακόπτες των ενοτήτων που ρωτά κάθε module πριν σερβίρει ή τρέξει
core/model	Κοινοί τύποι, όπως actors και subjects

Όταν το core πρέπει να αγγίξει δεδομένα ενός module, το module καταχωρεί ένα hook στο core μέσα στο wiring.go. Έτσι δουλεύει η εναλλαγή κλειδιών.

Δεδομένα

Αρχείο	Περιέχει
holyarrs.db	Τη Βιβλιοθήκη, τα αιτήματα, τις ρυθμίσεις και ό,τι άλλο έχει σημασία
holyarrs-events.db	Το ιστορικό και άλλες γραμμές συμβάντων. Μεγαλώνει και κλαδεύεται χωρίς να αγγίξει το κύριο αρχείο

Τα migrations είναι αριθμημένα αρχεία SQL στα core/database/migrations/main και core/database/migrations/events. Τρέχουν στην εκκίνηση.

Σχετικά

• Modules
• Συνεισφορά
• Δοκιμές