# Protokoll Pitmaster stöder flera nätverkstransportprotokoll för kommunikation med git-servrar. Smart HTTP är den primära transporten. Ytterligare protokoll finns för bredare kompatibilitet. ## Smart HTTP (primär) Den rekommenderade transporten. Den fungerar över HTTPS och är det mest spridda protokollet. Det finns ingen API för anpassade headers eller autentiseringsuppgifter; dessa kan bara skickas i URL (`https://user:token@host/repo.git`), som PHP skickar med Basic-autentisering. `clone()` lagrar URL, inklusive autentiseringsuppgifter, som `remote.origin.url` i `.git/config`. Förfrågningar använder strömomslagen i PHP, så `allow_url_fopen` måste vara aktiverat. ```php use Pitmaster\Protocol\SmartHttpClient; $http = new SmartHttpClient(timeout: 30); $discovery = $http->discoverRefs('https://github.com/user/repo.git'); ``` Se [Smart HTTP](https://pitmaster.inline0.dev/sv/docs/network/smart-http) för fullständig information. ### Protokoll v1 Det traditionella smarta HTTP-protokollet. Alla referenser skickas under upptäckten, och förhandlingen använder want/have/done-rader. ```php use Pitmaster\Protocol\ProtocolV1; ``` ### Protokoll v2 Det nyare protokollet med strukturerade kommandon (`ls-refs`, `fetch`). Effektivare för repon med många referenser eftersom klienten kan filtrera referenslistan. `clone()` och `fetch()` använder alltid protokoll v1. Protokoll v2 kan användas uttryckligen över smart HTTP via `SmartHttpClient::discoverRefsV2()` och `UploadPackClient::fetchV2()`. ## Dumb HTTP Reservlösning för servrar som inte stöder smart HTTP-protokoll. Dumb-protokollet hämtar objekt och pack-filer separat via vanliga HTTP GET-förfrågningar. ```php use Pitmaster\Protocol\DumbHttpClient; $client = new DumbHttpClient(); ``` Begränsningar för dumb HTTP: - Ingen förhandling (klienten måste ladda ned allt) - Ingen deltakomprimering under överföringen - Betydligt långsammare än smart HTTP - Vissa servrar (GitHub, GitLab) stöder det inte Dumb-protokollet hämtar: 1. `GET /info/refs` (vanlig text, inga pkt-line) 2. `GET /HEAD` (standardgren) 3. `GET /objects/info/packs` (lista över tillgängliga pack-filer) 4. `GET /objects/pack/pack-.pack` och `.idx` (varje listad pack-fil och dess index) 5. `GET /objects//` (enskilda lösa objekt, genomgångna från referenstopparna) Steg 5 körs endast när servern inte listar några pack-filer. När pack-filer listas hämtas inte objekt som bara finns som lösa filer på servern ([#18](https://github.com/inline0/pitmaster/issues/18)). Dumb-klienten godtar endast objekts-ID:n med 40 tecken (SHA-1). `clone()` och `fetch()` faller tillbaka på dumb HTTP när den smarta HTTP-kommunikationen misslyckas. ## SSH Transporten SSH använder tillägget `ssh2` PHP när det är laddat. Annars startar den systemets `ssh`-klient via `proc_open()`. I båda fallen körs `git-upload-pack` eller `git-receive-pack` på fjärrservern. ```php use Pitmaster\Protocol\SshClient; $client = new SshClient(); ``` URL:er av typen SSH: ``` git@github.com:user/repo.git ssh://git@github.com/user/repo.git ``` Inget tillägg krävs. De två sökvägarna fungerar olika: **Systemets `ssh`-klient** (används när `ssh2` inte är laddat). Pitmaster kör `ssh -o BatchMode=yes -o ConnectTimeout=30 -p @ `, så autentisering och kontroll av värdnyckel följer din SSH-konfiguration och agent. Dessa miljövariabler justerar kommandot: | Variabel | Effekt | |----------|--------| | `PITMASTER_SSH_COMMAND` | Körbar fil att köra i stället för `ssh` | | `PITMASTER_SSH_IDENTITY_FILE` | Skickas som `-i ` | | `PITMASTER_SSH_KNOWN_HOSTS` | Skickas som `-o UserKnownHostsFile=` | | `PITMASTER_SSH_STRICT_HOST_KEY_CHECKING` | Skickas som `-o StrictHostKeyChecking=` | Den här sökvägen startar en process och är därför inte tillgänglig för handtag som öppnats med `['processes' => false]`. **Tillägget `ssh2`** (prioriteras alltid när det är laddat). Pitmaster autentiserar med `~/.ssh/id_rsa`, därefter med `~/.ssh/id_ed25519` om RSA-nyckeln finns men avvisas, och annars med agenten SSH. Variablerna `PITMASTER_SSH_*` ignoreras, och serverns värdnyckel verifieras inte med den här metoden ([#22](https://github.com/inline0/pitmaster/issues/22)). Transporten SSH kör `git-upload-pack` eller `git-receive-pack` som ett fjärrkommando och kommunicerar via kanalen SSH med samma pkt-line-protokoll som smart HTTP. ## Protokollet Git (TCP) Det inbyggda protokollet git kommunicerar via TCP-port 9418 med PHP-sockets. `GitProtocolClient` implementerar referensupptäckt och `upload-pack` (hämtning); det kan inte skicka ändringar. `clone()` och `fetch()` dirigerar inte URL:er av typen `git://` till det, så använd klienten direkt. ```php use Pitmaster\Protocol\GitProtocolClient; $client = new GitProtocolClient(); ``` URL:er av typen Git: ``` git://github.com/user/repo.git ``` Egenskaper: - Ingen autentisering (i praktiken skrivskyddat) - Ingen kryptering - Föråldrat hos de flesta hosting-leverantörer - Använder samma pkt-line-inramning som smart HTTP Protokollet git skickar tjänstenamnet och sökvägen till repot som den första begäran och fortsätter sedan med standardiserad referensupptäckt och packförhandling via pkt-line. ## Paketfiler Git-paketfiler är pack-filer för offlinebruk med referensinformation. De gör det möjligt att överföra repodata utan nätverksanslutning. ```php use Pitmaster\Protocol\Bundle; // Read a bundle file $bundle = Bundle::open('/path/to/repo.bundle'); $refs = $bundle->refs(); $packData = $bundle->packData(); $prerequisites = $bundle->prerequisites(); // Create one $bundle = Bundle::create(['refs/heads/main' => $commitId], $packData); $bundle->writeTo('/path/to/out.bundle'); ``` Pitmaster läser rubriker för paketfiler av typen v2 och v3. Det finns ingen `Repository`-metod för att importera en paketfil: skriv `packData()` till `.git/objects/pack/`, skapa dess index med `PackIndexer::writeIndex()` och uppdatera referenserna själv. Paketfilformat: ``` # v2 git bundle\n -\n (zero or more) \n (one or more) \n (standard pack file format) ``` Paketfiler är användbara för: - Överföring utan nätverk (USB-enheter) - Inkrementella säkerhetskopior - Förberedelse av kloner i isolerade miljöer ## Ytliga kloner Pitmaster stöder ytliga kloner, där endast en begränsad del av commithistoriken hämtas. ```php use Pitmaster\Protocol\ShallowClone; ``` Ange ett djup för `Pitmaster::clone($url, $path, $depth)` eller `$repo->fetch($remote, $depth)`. Begäran lägger till funktionen `shallow` och en rad med `deepen`: ``` want deepen ``` Servern svarar med `shallow `-rader som anger var historiken trunkerades. Pitmaster beräknar den grunda gränsen utifrån själva djupet och använder serverns `shallow`-rader när beräkningen inte hittar något; resultatet sparas i `.git/shallow`. `ShallowClone::readShallow()`, `writeShallow()` och `isShallow()` arbetar direkt med den filen. ## Protokolljämförelse | Protokoll | Autentisering | Kryptering | Push | Typisk användning | |----------|------|-----------|------|-------------| | Smart HTTP | Autentiseringsuppgifter i URL | HTTPS | Ja | Primär transport | | Dumb HTTP | Autentiseringsuppgifter i URL | HTTPS | Nej | Äldre reservlösning | | SSH | SSH-nycklar eller agent | SSH | Ja | Privata repos, CI | | Git (TCP) | Ingen | Ingen | Nej | Speglar med endast läsåtkomst | | Bundle | Ej tillämpligt | Ej tillämpligt | Ej tillämpligt | Överföring offline | ## Val av transport `Pitmaster::clone()`, `$repo->fetch()` och `$repo->push()` väljer transport utifrån URL: | URL-mönster | Transport | |------------|-----------| | `ssh://...` | SSH | | `user@host:path` | SSH | | Allt annat (`https://...`, `http://...`) | Smart HTTP; clone och fetch går tillbaka till dumb HTTP | `git://`-URL:er och lokala sökvägar stöds inte av dessa metoder: de skickas till smart HTTP-klienten och misslyckas. Använd `GitProtocolClient` direkt för `git://`. En HTTPS URL som innehåller både en användare och en port (`https://user@host:8443/repo.git`) misstas för närvarande för en SSH URL ([#17](https://github.com/inline0/pitmaster/issues/17)).