diff --git a/GEMINI.md b/GEMINI.md index 4ee32c1..6c3153a 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -13,26 +13,31 @@ A production-ready Python utility for robust synchronization of SharePoint Onlin ## Core Features (Production Ready) -1. **Resumable Downloads:** Implements HTTP `Range` headers to resume partially downloaded files, critical for multi-gigabyte assets. -2. **Reliability:** Includes a custom `retry_request` decorator for Exponential Backoff, handling throttling (429) and transient network errors. -3. **Concurrency:** Multi-threaded architecture (5 workers) for simultaneous scanning and downloading. -4. **Pagination:** Full support for OData pagination, ensuring complete folder traversal regardless of item count. -5. **Self-Healing Sessions:** Automatically detects and resolves 401 Unauthorized errors by refreshing both expiring Microsoft Graph Download URLs and MSAL Access Tokens mid-process. -6. **Logging & Audit:** Integrated Python `logging` to `sharepoint_download.log` and structured CSV reports for error auditing. +1. **Timestamp Synchronization:** Intelligent sync logic that compares SharePoint `lastModifiedDateTime` with local file `mtime`. Only downloads if the remote source is newer, significantly reducing sync time. +2. **Optimized Integrity Validation:** Implements the official Microsoft **QuickXorHash** (160-bit circular XOR). Includes a configurable threshold (default 30MB) and a global toggle to balance security and performance for large assets. +3. **Resumable Downloads:** Implements HTTP `Range` headers to resume partially downloaded files, critical for multi-gigabyte assets. +4. **Reliability:** Includes a custom `retry_request` decorator for Exponential Backoff, handling throttling (429) and transient network errors. +5. **Robust Library Discovery:** Automatic resolution of document library IDs with built-in fallbacks for localized names (e.g., "Delte dokumenter" to "Documents"). +6. **Self-Healing Sessions:** Automatically detects and resolves 401 Unauthorized errors by refreshing both expiring Microsoft Graph Download URLs and MSAL Access Tokens mid-process. +7. **Concurrency:** Multi-threaded architecture (5 workers) for simultaneous scanning and downloading. +8. **Pagination:** Full support for OData pagination, ensuring complete folder traversal regardless of item count. ## Building and Running ### Setup 1. **Dependencies:** `pip install -r requirements.txt` -2. **Configuration:** Use `connection_info.template.txt` to create `connection_info.txt`. +2. **Configuration:** Settings are managed via `connection_info.txt` or the GUI. + * `ENABLE_HASH_VALIDATION`: (True/False) + * `HASH_THRESHOLD_MB`: (Size limit for hashing) ### Execution -`python download_sharepoint.py` +* **GUI:** `python sharepoint_gui.py` +* **CLI:** `python download_sharepoint.py` ## Development Conventions -* **Error Handling:** Always use the `safe_get` (retry-wrapped) method for Graph API calls. For item-specific operations, use `get_fresh_download_url` to handle token/URL expiry. -* **Authentication:** Use `get_headers(app, force_refresh=True)` when a 401 error is encountered from Graph API to ensure session continuity. -* **Thread Safety:** Use `report_lock` when updating the shared error list from worker threads. -* **Logging:** Prefer `logger.info()` or `logger.error()` over `print()` to ensure persistence in `sharepoint_download.log`. -* **Integrity:** Always verify file integrity using `size` and `quickXorHash` where available. +* **QuickXorHash:** When implementing/updating hashing, ensure the file length is XORed into the **last 64 bits** (bits 96-159) of the 160-bit state per MS spec. +* **Timezone Handling:** Always use UTC (ISO8601) when comparing timestamps with SharePoint to avoid daylight savings mismatches. +* **Error Handling:** Always use the `safe_get` (retry-wrapped) method for Graph API calls. For item-specific operations, use `get_fresh_download_url`. +* **Authentication:** Use `get_headers(app, force_refresh=True)` when a 401 error is encountered. +* **Logging:** Prefer `logger.info()` or `logger.error()` over `print()`. diff --git a/README.md b/README.md index bf94003..aeed862 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,18 @@ Dette script gør det muligt at downloade specifikke mapper fra et SharePoint do * **Moderne GUI (UX):** Flot mørkt interface med CustomTkinter, der gør det nemt at gemme indstillinger, vælge mapper og se status i realtid. * **Stop-funktionalitet:** Afbryd synkroniseringen midt i processen direkte fra UI. * **Paralleldownload:** Benytter `ThreadPoolExecutor` (default 5 tråde) for markant højere overførselshastighed. +* **Timestamp Synkronisering:** Downloader kun filer, hvis kilden på SharePoint er nyere end din lokale fil (`lastModifiedDateTime` vs. lokal `mtime`). Hvis din lokale fil er nyere, springes download over. +* **Konfigurerbar Integritet:** Validerer filernes korrekthed med Microsofts officielle **QuickXorHash**-algoritme. + * **Toggle:** Mulighed for at slå hash-validering helt til/fra. + * **Smart Grænse:** Definer en MB-grænse (standard 30 MB), hvor filer herunder hashes, mens større filer (f.eks. 65 GB) kun sammenlignes på størrelse for at spare tid. +* **Robust Bibliotekssøgning:** Finder automatisk dit bibliotek og har indbygget fallback (f.eks. fra "Delte dokumenter" til "Documents"), hvis SharePoint bruger engelske navne bag kulisserne. * **Resume Download:** Understøtter HTTP `Range` headers, så afbrudte downloads af store filer (f.eks. >50GB) genoptages fra det sidste byte i stedet for at starte forfra. * **Auto-Refresh af Downloads & Tokens:** Håndterer automatisk udløbne download-links og Access Tokens (401 Unauthorized). Værktøjet fornyer både URL'er og adgangsnøgler midt i processen uden at afbryde synkroniseringen. -* **Exponential Backoff:** Håndterer automatisk Microsoft Graph throttling (`429 Too Many Requests`) og netværksfejl med intelligente genforsøg — gælder alle API-kald, inkl. URL-refresh. -* **Dybdebeskyttelse:** Mappegennemgang stopper ved 50 niveauers dybde og logger en advarsel, så unormalt dybe strukturer ikke kan crashe synkroniseringen. +* **Exponential Backoff:** Håndterer automatisk Microsoft Graph throttling (`429 Too Many Requests`) og netværksfejl med intelligente genforsøg. +* **Dybdebeskyttelse:** Mappegennemgang stopper ved 50 niveauers dybde for at beskytte mod unormalt dybe strukturer. * **Struktureret Logging:** Gemmer detaljerede logs i `sharepoint_download.log` samt en CSV-fejlrapport for hver kørsel. -* **Paginering:** Håndterer automatisk mapper med mere end 200 elementer via `@odata.nextLink`. -* **Smart Skip & Integritet:** Skipper filer der allerede findes lokalt med korrekt størrelse og bestået QuickXorHash-validering. Filer med korrekt størrelse men forkert indhold (korrupt) detekteres og re-downloades automatisk. -* **Entra ID Integration:** Benytter MSAL for sikker godkendelse via Client Credentials flow med automatisk token-refresh. +* **Paginering:** Håndterer automatisk mapper med mere end 200 elementer. +* **Entra ID Integration:** Benytter MSAL for sikker godkendelse via Client Credentials flow. ## Installation @@ -34,10 +38,10 @@ For at scriptet kan få adgang til SharePoint, skal du oprette en App-registreri 4. Noter din **Application (client) ID** og **Directory (tenant) ID**. 5. Gå til **API permissions** > **Add a permission** > **Microsoft Graph**. 6. Vælg **Application permissions**. -7. Søg efter og tilføj `Sites.Read.All` (eller `Sites.ReadWrite.All` hvis du har brug for skriveadgang). -8. **VIGTIGT:** Klik på **Grant admin consent for [dit domæne]** for at godkende rettighederne. -9. Gå til **Certificates & secrets** > **New client secret**. Tilføj en beskrivelse og vælg udløbsdato. -10. **VIGTIGT:** Kopier værdien under **Value** med det samme (det er din `CLIENT_SECRET`). Du kan ikke se den igen senere. +7. Søg efter og tilføj `Sites.Read.All`. +8. **VIGTIGT:** Klik på **Grant admin consent for [dit domæne]**. +9. Gå til **Certificates & secrets** > **New client secret**. +10. **VIGTIGT:** Kopier værdien under **Value** med det samme (din `CLIENT_SECRET`). ## Anvendelse @@ -48,17 +52,20 @@ For en moderne grafisk brugerflade, kør: ```bash python sharepoint_gui.py ``` -Her kan du nemt indtaste indstillinger, gemme dem, vælge destinationsmappe og starte/stoppe synkroniseringen. +Her kan du nemt indtaste indstillinger, gemme dem, vælge destinationsmappe og starte/stoppe synkroniseringen. Du kan også styre om Hash-validering skal være aktiv og ved hvilken størrelse den skal springes over. ### 2. CLI Version (Til automatisering) Hvis du ønsker at køre scriptet direkte fra terminalen: -1. Kopier `connection_info.template.txt` til `connection_info.txt`. -2. Udfyld dine oplysninger. -3. Kør: +1. Udfyld `connection_info.txt`. +2. Kør: ```bash python download_sharepoint.py ``` +## Konfiguration (connection_info.txt) +* `ENABLE_HASH_VALIDATION`: Sæt til `"True"` eller `"False"`. +* `HASH_THRESHOLD_MB`: Talværdi (f.eks. `"30"` eller `"50"`). + ## Logfiler * `sharepoint_download.log`: Teknisk log over alle handlinger og fejl. * `download_report_YYYYMMDD_HHMMSS.csv`: En hurtig oversigt over filer der fejlede.