Protokolai

Pitmaster palaiko kelis tinklo transporto protokolus ryšiui su git serveriais. Pagrindinis transportas yra išmanusis HTTP. Didesniam suderinamumui užtikrinti siūlomi ir kiti protokolai.

Išmanusis HTTP (pagrindinis)

Rekomenduojamas transportas. Veikia per HTTPS ir yra plačiausiai naudojamas protokolas. Nėra API pasirinktinių antraščių ar prisijungimo duomenų perdavimui; juos galima perduoti tik URL (https://user:token@host/repo.git), kurį PHP siunčia kaip Basic autentifikavimą. clone() saugo URL, įskaitant prisijungimo duomenis, .git/config faile kaip remote.origin.url. Užklausoms naudojami PHP srautų įvyniokliai, todėl turi būti įjungtas allow_url_fopen.

use Pitmaster\Protocol\SmartHttpClient;

$http = new SmartHttpClient(timeout: 30);
$discovery = $http->discoverRefs('https://github.com/user/repo.git');

Išsamią informaciją rasite skiltyje Išmanusis HTTP.

Protokolas v1

Tradicinis išmanusis HTTP protokolas. Aptikimo metu siunčiamos visos nuorodos, o derantis naudojamos norimų, turimų ir užbaigimo eilutės.

use Pitmaster\Protocol\ProtocolV1;

Protokolas v2

Naujesnis protokolas su struktūruotomis komandomis (ls-refs, fetch). Veiksmingesnis saugyklose su daug nuorodų, nes klientas gali filtruoti nuorodų sąrašą.

clone() ir fetch() visada naudoja protokolą v1. Protokolas v2 aiškiai pasiekiamas per išmanųjį HTTP naudojant SmartHttpClient::discoverRefsV2() ir UploadPackClient::fetchV2().

Paprastasis HTTP

Atsarginis protokolas serveriams, nepalaikantiems išmaniojo HTTP protokolo. Paprastuoju protokolu objektai ir paketai gaunami atskirai, siunčiant įprastas HTTP GET užklausas.

use Pitmaster\Protocol\DumbHttpClient;

$client = new DumbHttpClient();

Paprastojo HTTP apribojimai:

• Nėra derinimo (klientas turi atsisiųsti viską)
• Perduodant netaikomas deltų glaudinimas
• Gerokai lėtesnis už išmanųjį HTTP
• Kai kurie serveriai (GitHub, GitLab) jo nepalaiko

Paprastuoju protokolu gaunami:

1. GET /info/refs (paprastasis tekstas, be pkt-line)
2. GET /HEAD (numatytoji šaka)
3. GET /objects/info/packs (prieinamų paketų sąrašas)
4. GET /objects/pack/pack-<hash>.pack ir .idx (kiekvienas sąraše nurodytas paketas ir jo indeksas)
5. GET /objects/<xx>/<rest> (pavieniai palaidi objektai, pereinant nuo nuorodų viršūnių)

5 veiksmas atliekamas tik tada, kai serveris nenurodo jokių paketų. Jei paketai nurodyti, serveryje kaip palaidi failai esantys objektai neatsisiunčiami (#18). Paprastasis klientas priima tik 40 simbolių objektų ID (SHA-1). Išmaniesiems HTTP mainams nepavykus, clone() ir fetch() pereina prie paprastojo HTTP.

SSH

Jei įkeltas ssh2 PHP plėtinys, SSH transportas jį naudoja. Kitu atveju per proc_open() paleidžiamas sistemos ssh klientas. Abiem atvejais nuotolinėje saugykloje vykdoma git-upload-pack arba git-receive-pack.

use Pitmaster\Protocol\SshClient;

$client = new SshClient();

SSH URL:

git@github.com:user/repo.git
ssh://git@github.com/user/repo.git

Plėtinio nereikia. Šie du būdai veikia skirtingai:

Sistemos ssh klientas (naudojamas, kai ssh2 neįkeltas). Pitmaster vykdo ssh -o BatchMode=yes -o ConnectTimeout=30 -p <port> <user>@<host> <command>, todėl autentifikavimui ir pagrindinio kompiuterio raktų tikrinimui taikoma jūsų SSH konfigūracija bei agentas. Komandą keičia šie aplinkos kintamieji:

Šis kelias paleidžia procesą, todėl jo negalima naudoti su deskriptoriais, atidarytais naudojant ['processes' => false].

ssh2 plėtinys (visada naudojamas, kai įkeltas). Pitmaster autentifikuojasi naudodamas ~/.ssh/id_rsa, o jei RSA raktas yra, bet atmetamas, – naudodamas ~/.ssh/id_ed25519; kitais atvejais naudojamas SSH agentas. PITMASTER_SSH_* kintamųjų nepaisoma, o serverio pagrindinio kompiuterio raktas šiuo būdu netikrinamas (#22).

SSH transportas vykdo git-upload-pack arba git-receive-pack kaip nuotolinę komandą ir palaiko ryšį SSH kanalu, naudodamas tą patį pkt-line protokolą kaip ir išmanusis HTTP.

Git protokolas (TCP)

Savasis git protokolas palaiko ryšį per TCP prievadą 9418, naudodamas PHP lizdus. GitProtocolClient įgyvendina nuorodų aptikimą ir upload-pack (gavimą); siųsti duomenų juo negalima. clone() ir fetch() nenukreipia git:// URL į jį, todėl naudokite tiesiogiai klientą.

use Pitmaster\Protocol\GitProtocolClient;

$client = new GitProtocolClient();

Git URL:

git://github.com/user/repo.git

Savybės:

• Autentifikavimo nėra (praktiškai tik skaitoma prieiga)
• Šifravimo nėra
• Dauguma prieglobos paslaugų teikėjų šį protokolą laiko pasenusiu
• Naudojamas toks pats pkt-line formatavimas kaip išmaniajame HTTP

git protokolas pradinėje užklausoje siunčia paslaugos pavadinimą ir saugyklos kelią, tada vykdo įprastą pkt-line nuorodų aptikimą ir paketų derybą.

Paketai

Git paketai yra neprisijungus naudojami paketų failai su nuorodų informacija. Jie leidžia perkelti saugyklos duomenis be tinklo ryšio.

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 nuskaito v2 ir v3 paketų antraštes. Paketui importuoti nėra Repository metodo: įrašykite packData() į .git/objects/pack/, sukurkite jo indeksą naudodami PackIndexer::writeIndex() ir patys atnaujinkite nuorodas.

Paketų formatas:

# v2 git bundle\n
-<prerequisite hash>\n    (zero or more)
<hash> <refname>\n        (one or more)
\n
<pack data>               (standard pack file format)

Paketai naudingi:

• Perkeliant duomenis fizinėmis laikmenomis (USB įrenginiais)
• Laipsniškoms atsarginėms kopijoms
• Klonams paruošti izoliuotose aplinkose

Negiliosios klonuotos saugyklos

Pitmaster palaiko negilųjį klonavimą, kai gaunama tik riboto gylio pakeitimų istorija.

use Pitmaster\Protocol\ShallowClone;

Perduokite gylį į Pitmaster::clone($url, $path, $depth) arba $repo->fetch($remote, $depth). Prie užklausos pridedama galimybė shallow ir eilutė deepen:

want <hash>
deepen <depth>

Serveris atsako shallow <hash> eilutėmis, nurodančiomis, kur istorija buvo sutrumpinta. Pitmaster apskaičiuoja negiliąją ribą pagal patį gylį ir naudoja serverio shallow eilutes, jei apskaičiuojant nieko nerandama; rezultatas įrašomas į .git/shallow. ShallowClone::readShallow(), writeShallow() ir isShallow() tiesiogiai naudoja šį failą.

Protokolų palyginimas

Transporto pasirinkimas

Pitmaster::clone(), $repo->fetch() ir $repo->push() parenka transportą pagal URL:

git:// URL ir vietiniai keliai šių metodų nepalaikomi: jie perduodami išmaniojo HTTP klientui ir sukelia klaidą. Jei naudojate git://, tiesiogiai naudokite GitProtocolClient. Šiuo metu HTTPS URL, kuriame yra ir naudotojas, ir prievadas (https://user@host:8443/repo.git), klaidingai palaikomas SSH URL (#17).