NetDrop

Serwer synchronizacji plików zgodny z klientami Nextclouda — desktopowym, androidowym i iOS-owym — oraz z menedżerami plików przez WebDAV. Napisany w Go: jeden statyczny binarek i jeden plik SQLite, bez PHP, bez osobnej bazy danych, bez Redisa, bez CGO.

Klient Nextcloud Desktop (33.0.7 i 34.0.4) synchronizuje się w obie strony, łącznie z wysyłaniem dużych plików na raty. Do tego interfejs w przeglądarce z edytorem, podglądem, udostępnianiem i działaniami na wielu plikach naraz.

NetDrop nie jest Nextcloudem i nie udaje go. Jest z nim zgodny.

---

Co potrafi

Synchronizacja i klienty

• Klienty Nextclouda — logowanie przez przeglądarkę (Login Flow v1 i v2), hasło aplikacji na każde urządzenie, PROPFIND z właściwościami oc:/nc:, zapis warunkowy (If-Match), wysyłanie na raty ze wznawianiem.
• Powiadomienia na żywo zgodne z notify_push (WebSocket) — zmiana dociera do klienta od razu, a nie po cyklu odpytywania.
• Menedżery plików — Dolphin, Nautilus, Thunar, Windows, rclone, Cyberduck montują /remote.php/dav/files/{konto}/ bez żadnego klienta. Adres do skopiowania pokazuje pozycja „WebDAV” w pasku bocznym.
• Albumy z aplikacji Zdjęcia (/remote.php/dav/photos) — tworzone w aplikacji na telefonie, widoczne i udostępniane publicznym linkiem w przeglądarce.
• Kosz i historia wersji — w interfejsie i po WebDAV, tak jak oczekuje klient.
• Wyszukiwarka — w przeglądarce i przez OCS Search API.

Interfejs w przeglądarce

• Pasek boczny z drzewem katalogów (zwijany do ikon), trzy układy listy — tabela, kafelki, galeria — sortowanie, miniatury zdjęć i filmów.
• Podgląd na pełnym ekranie zdjęć i filmów z każdego układu; podgląd Markdowna, tekstu i kodu, PDF-ów i obrazów.
• Edytor plików .md i .txt — pasek formatowania, podgląd Markdowna na żywo obok tekstu, zapis bez przeładowania strony, szkic chroniony przed zamknięciem karty i wykrywanie konfliktu, gdy ktoś zmienił plik w międzyczasie.
• Zaznaczanie wielu plików i katalogów — przycisk „Zaznacz”, Shift+klik, Ctrl+A, przytrzymanie na telefonie; na zaznaczonych: pobierz jako ZIP, przenieś, kopiuj, do kosza. Także w koszu: przywróć i usuń trwale wiele naraz.
• Przenoszenie i kopiowanie przez okno wyboru celu — także między własnymi plikami a katalogiem udostępnionym przez kogoś innego. Treść się przy tym nie kopiuje: pliki są adresowane skrótem, więc kopia gigabajtowego katalogu to kilka wierszy w bazie.
• Wgrywanie przeciągnięciem na całą stronę, pobieranie katalogu jako ZIP.
• Zdjęcie profilowe (domyślnie pierwsza litera na kolorze wyliczonym z nazwy konta), jasny i ciemny motyw, układ dopasowany do telefonu.

Udostępnianie

• Publiczne odnośniki z hasłem i terminem ważności — tylko do odczytu.
• Dzielenie z innym kontem — cudzy katalog widać w korzeniu odbiorcy, w przeglądarce i w kliencie synchronizującym.
• OCS Share API — okno udostępniania w aplikacji Nextclouda działa.

Administracja i serwis

• Panel administratora z osobnym logowaniem: konta, uprawnienia, limity miejsca, odłączanie urządzeń, deduplikacja, tapeta ekranu logowania.
• netdropd kopia-pelna / odtworz — spójny obraz bazy i treści, przyrostowo, z kontrolą skrótów, przy działającym serwerze.
• netdropd import — katalog z dysku wprost do konta, bez HTTP, z zachowaniem dat, wznawialny.
• Kopia bazy przed każdą migracją schematu; profil CPU (pprof) na żądanie, tylko na adresie pętli zwrotnej.

Rozszerzenia NetDrop

Opcjonalne, ogłaszane w capabilities — klient, który ich nie zna, działa zwykłym protokołem Nextclouda (docs/ROZSZERZENIA.md):

GET /api/netdrop/v1/changes	zmiany od numeru zamiast chodzenia po drzewie
POST /api/netdrop/v1/have + link	deduplikacja po stronie klienta — kopia istniejącej treści bez przesyłania bajtów
POST /api/netdrop/v1/delta	zmiana fragmentu dużego pliku wysyła tylko zmieniony fragment

---

Instalacja

Docker (najprościej)

Obraz digitalninja4/netdrop na Docker Hubie, dla linux/amd64 i linux/arm64 (Raspberry Pi), z ffmpeg do miniatur filmów. Serwer działa w kontenerze jako zwykły użytkownik (UID 10001), nie jako root.

openssl rand -base64 24 > admin_password.txt               # hasło pierwszego administratora
echo 'NETDROP_BASEURL=https://chmura.twojadomena.pl' > .env  # adres widoczny dla klientów
docker compose up -d

NETDROP_BASEURL jest wymagany do logowania klientami Nextclouda — bez niego dostaną adres nasłuchu kontenera i się nie połączą. Zmienne, wolumeny, pośrednik odwrotny, konta i kopie w kontenerze: docs/DOCKER.md.

Paczka z instalatorem (LXC, VPS, Raspberry Pi)

make dist                                    # buduje paczkę w dist/
scp dist/netdrop-*.tar.gz root@serwer:/tmp/
ssh root@serwer 'cd /tmp && tar xzf netdrop-*.tar.gz && cd netdrop-* && ./instaluj.sh'

Instalator pyta o adres publiczny oraz nazwę i hasło pierwszego administratora, a resztę robi sam: konto systemowe, binarek, konfiguracja, usługa w autostarcie. Rozpoznaje Alpine (OpenRC) i Debiana/Ubuntu (systemd) i nie instaluje żadnych pakietów. Pełne wdrożenie za Nginx Proxy Managerem na Proxmoksie: docs/WDROZENIE.md.

Na maszynie deweloperskiej

make build
./netdropd useradd -data ./data -user kamil -password-stdin -admin   # hasło z klawiatury, Ctrl+D
./netdropd -data ./data -listen 127.0.0.1:8080 -baseurl http://127.0.0.1:8080

useradd wypisuje hasło aplikacji raz — w bazie leży tylko jego skrót. Konto bez -admin można awansować później: ./netdropd admin -data ./data -user kamil.

Pierwsze połączenie klientem

W kliencie Nextclouda wpisz adres z -baseurl (albo NETDROP_BASEURL). Klient otworzy przeglądarkę, logujesz się hasłem konta, zatwierdzasz urządzenie, a klient sam odbiera własne hasło aplikacji. Hasło konta nigdy nie przechodzi przez okienko klienta.

---

Konfiguracja

Plik konfiguracyjny zawiera tylko to, co potrzebne, zanim serwer otworzy bazę — gdzie nasłuchiwać, gdzie leżą dane, jak jest widoczny z zewnątrz, czy stoi za pośrednikiem:

netdropd config > /etc/netdrop/netdrop.toml   # wzór z komentarzami
netdropd -config /etc/netdrop/netdrop.toml

Flagi (-listen, -data, -baseurl, -behind-proxy) nadpisują plik i służą do doraźnego uruchomienia. Panel administratora trzyma ustawienia, które zmienia się w działającym serwerze (domena treści, czas w koszu, tapeta) — bez powłoki i bez restartu.

Aktualizacja

make wdroz CEL=root@serwer                 # przez SSH prosto na serwer
make pve CTID=718 HOST=root@proxmox        # do kontenera LXC przez host Proxmoksa
bash scripts/docker-wyslij.sh              # obraz Dockera: testy, budowa, wysyłka na Docker Hub

Wdrożenie buduje, wysyła, aktualizuje i sprawdza, czy po restarcie działa naprawdę ta wersja, którą wysłaliśmy. Konfiguracji, bazy ani plików nie rusza; przy zmianie schematu serwer sam robi kopię bazy przed migracją.

---

Czego jeszcze nie ma

• Wgrywanie całych katalogów w przeglądarce z zachowaniem hierarchii (Etap 8).
• Blokady WebDAV (LOCK/UNLOCK, Etap 10) — bez nich nie połączy się Finder z macOS-a, a pakiety biurowe nie mają jak się umówić przy edycji.
• Adapter klienta (Etap 12d) — rozszerzenia działają po stronie serwera, ale zwykły klient Nextclouda ich nie woła.
• Grupy i własny punkt zaczepienia otrzymanego udostępnienia.
• Testy na telefonach są cząstkowe — klient Androida był używany ręcznie (logowanie, albumy), systematyczna weryfikacja objęła klient desktopowy; iOS nie był testowany (docs/PROTOKOL.md, §20).

Adres publicznego odnośnika pokazujemy raz, przy tworzeniu — w bazie leży tylko skrót tokenu. To świadoma cena za to, że wyciek samej bazy nie otwiera udostępnionych plików.

Dlaczego tak

Klienty Nextclouda istnieją na wszystkie platformy, są dopracowane i zawierają najtrudniejszą część problemu: silnik uzgadniania zmian. Implementując ich protokół po stronie serwera dostajemy desktop i telefony za darmo i wycinamy z projektu tysiące linii logiki, w której najłatwiej o błąd kosztujący kogoś pliki. Cena: protokół nie jest nasz i gonimy cel, który przesuwa się z każdą aktualizacją klienta.

Nextcloud jest ciężki nie dlatego, że robi dużo, tylko dlatego, że PHP nie ma pamięci między żądaniami: każdy PROPFIND startuje od zera i liczy wszystko w SQL-u. NetDrop ma trwały proces, dziennik zmian i propagację ETagów w jednej krótkiej transakcji. Pomiary i wprowadzone optymalizacje (np. PROPFIND katalogu z 2000 plików 14,8 → 4,3 ms, przeniesienie katalogu z 5000 plików w bazie ze 100 tys. węzłów 46 s → 0,3 ms): docs/WYDAJNOSC.md.

---

Dokumentacja

docs/PLAN.md	ustalenia projektowe, reguły architektoniczne, etapy
docs/PROTOKOL.md	protokół klienta Nextclouda odtworzony z żywej instancji i prawdziwego klienta
docs/ROZSZERZENIA.md	rozszerzenia NetDrop ponad protokół Nextclouda
docs/WDROZENIE.md	wdrożenie, pośrednik, kopie zapasowe, przenosiny
docs/DOCKER.md	obraz, Compose, zmienne, wolumeny
docs/WYDAJNOSC.md	audyt wydajności i pomiary przed/po
docs/ZAZNACZANIE.md	zaznaczanie wielu elementów i działania zbiorcze
docs/NAPRAWY.md	naprawy po audycie bezpieczeństwa
CLAUDE.md	niezmienniki obowiązujące przy każdej zmianie i spis plików docs/kontekst/

Praca z kodem

make check    # go vet + wszystkie testy
make cross    # czy obietnica braku CGO nadal się trzyma
make build

Nieudana make cross jest pierwszym sygnałem, że do projektu wkradła się zależność od C — a razem z nią koniec jednoplikowego wdrożenia. Przed zmianą w kodzie przeczytaj CLAUDE.md: cztery niezmienniki (jedno gardło zapisu, krótka transakcja, uprawnienia raz na żądanie, propagacja ETagów) psują rzeczy po cichu, gdy się je złamie.

Profil CPU działającego serwera: -pprof 127.0.0.1:6060, potem go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds=30.

Licencja

NetDrop jest wolnym oprogramowaniem na licencji GNU Affero General Public License, wersja 3 (AGPL-3.0-only) — pełny tekst w pliku LICENSE.

Copyright (C) 2026 Kamil

W skrócie: wolno uruchamiać, studiować, zmieniać i rozpowszechniać, ale zmiany udostępniane innym — także przez sieć, jako usługa — trzeba oddać na tej samej licencji razem ze źródłami (art. 13). Zależności (goldmark, modernc SQLite, coder/websocket, x/crypto, x/image, x/text, BurntSushi/toml) mają licencje permisywne zgodne z AGPL, a ikony Tabler — MIT.

Ikony i znaki towarowe

Interfejs używa Tabler Icons (MIT), wbudowanych jako sprite SVG — strona nie robi żadnego zapytania na zewnątrz.

NetDrop jest zgodny z klientami Nextclouda, ale nie jest z Nextcloudem powiązany. Klient Nextclouda jest na GPL, serwer na AGPL; czytanie ich kodu dla zrozumienia protokołu jest normalną praktyką interoperacyjną, kopiowanie fragmentów do tego projektu — nie. Referencją o licencji permisywnej jest oCIS (Apache 2.0).