نام (NAME)

gitprotocol-http - پروتکل‌های مبتنی بر HTTP در گیت

خلاصه (SYNOPSIS)

<over-the-wire-protocol>

توضیحات (DESCRIPTION)

گیت از دو پروتکل انتقال مبتنی بر HTTP پشتیبانی می‌کند: یک پروتکل «ساده» (dumb) که در سمت سرور تنها به یک وب‌سرور استاندارد HTTP نیاز دارد، و یک پروتکل «هوشمند» (smart) که به یک ماژول سرور یا CGI آگاه به گیت نیازمند است. این سند هر دو پروتکل را شرح می‌دهد.

به عنوان یک ویژگی طراحی، کلاینت‌های هوشمند می‌توانند به طور خودکار نشانی‌های URL پروتکل «ساده» را به URLهای «هوشمند» ارتقا دهند. این کار به همه کاربران اجازه می‌دهد از یک نشانی URL منتشرشده یکسان استفاده کنند، و طرفین ارتباط (peers) به طور خودکار بهینه‌ترین روش انتقال در دسترس را انتخاب نمایند.

قالب نشانی اینترنتی (URL FORMAT)

نشانی‌های اینترنتی (URL) برای مخازن گیت که از طریق HTTP قابل دسترسی هستند از ساختار استاندارد HTTP URL مستندشده در RFC 1738 استفاده می‌کنند، بنابراین به فرم زیر هستند:

http://<host>:<port>/<path>?<searchpart>

در این مستند، عبارت جایگزین $GIT_URL نمایانگر نشانی مخزن http:// واردشده توسط کاربر نهایی خواهد بود.

سرورها باید تمام درخواست‌ها به مسیرهای منطبق با $GIT_URL را مدیریت کنند، زیرا هر دو پروتکل HTTP «هوشمند» و «ساده» مورد استفاده در گیت با افزودن اجزای مسیر اضافی به انتهای رشته $GIT_URL ارائه‌شده توسط کاربر کار می‌کنند.

یک نمونه از یک کلاینت ساده که یک شیء منفرد (loose object) را درخواست می‌کند:

$GIT_URL:     http://example.com:8080/git/repo.git
URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355

یک نمونه از یک درخواست هوشمند به یک درگاه همه‌منظوره (catch-all gateway):

$GIT_URL:     http://example.com/daemon.cgi?svc=git&q=
URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack

یک نمونه از یک درخواست به یک زیرماژول (submodule):

$GIT_URL:     http://example.com/git/repo.git/path/submodule.git
URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs

کلاینت‌ها باید در صورت وجود، اسلش پایانی / را از انتهای رشته $GIT_URL ارائه‌شده توسط کاربر حذف کنند تا از ظاهر شدن توکن‌های مسیر خالی (//) در نشانی‌های URL ارسالی به سرور جلوگیری شود. کلاینت‌های سازگار باید $GIT_URL/info/refs را به صورت foo/info/refs گسترش دهند نه foo//info/refs.

احراز هویت (AUTHENTICATION)

در صورتی که برای دسترسی به یک مخزن نیاز به احراز هویت باشد، از احراز هویت استاندارد HTTP استفاده می‌شود و ممکن است توسط نرم‌افزار سرور HTTP پیکربندی و اعمال گردد.

از آنجا که مخازن گیت از طریق اجزای استاندارد مسیر در دسترس هستند، مدیران سرور می‌توانند از مجوزهای مبتنی بر دایرکتوری در وب‌سرور HTTP خود برای کنترل دسترسی به مخزن استفاده کنند.

کلاینت‌ها باید از احراز هویت پایه (Basic authentication) مطابق با RFC 2617 پشتیبانی کنند. سرورها باید با اتکا به سرور HTTP قرار گرفته در جلوی نرم‌افزار سرور گیت، از احراز هویت Basic پشتیبانی نمایند.

سرورها نباید برای اهداف احراز هویت یا کنترل دسترسی نیازمند کوکی‌های HTTP باشند.

کلاینت‌ها و سرورها می‌توانند از سایر روش‌های رایج احراز هویت مبتنی بر HTTP مانند احراز هویت چکیده (Digest authentication) پشتیبانی کنند.

اس‌اس‌ال (SSL)

کلاینت‌ها و سرورها باید از SSL پشتیبانی کنند، به ویژه برای محافظت از گذرواژه‌ها هنگام اتکا به احراز هویت Basic در HTTP.

وضعیت نشست (SESSION STATE)

پروتکل گیت روی HTTP (همانند خود HTTP) از دیدگاه سمت سرور HTTP بدون حالت (stateless) است. تمام وضعیت‌ها باید توسط فرآیند کلاینت نگهداری و مدیریت شوند. این امر توزیع بار نوبتی (round-robin load-balancing) ساده در سمت سرور را بدون نیاز به نگرانی درباره مدیریت وضعیت ممکن می‌سازد.

کلاینت‌ها نباید برای عملکرد صحیح نیازمند مدیریت وضعیت در سمت سرور باشند.

سرورها نباید برای عملکرد صحیح نیازمند کوکی‌های HTTP باشند. کلاینت‌ها می‌توانند هنگام پردازش درخواست، مطابق با RFC 2616 (HTTP/1.1) کوکی‌های HTTP را ذخیره و ارسال کنند. سرورها باید کوکی‌های ارسالی توسط کلاینت را نادیده بگیرند.

پردازش عمومی درخواست‌ها (GENERAL REQUEST PROCESSING)

به جز مواردی که ذکر شده است، تمام رفتارهای استاندارد HTTP باید از سوی هر دو طرف کلاینت و سرور فرض شود. این شامل موارد زیر است (اما لزوماً محدود به آن‌ها نیست):

اگر هیچ مخزنی در $GIT_URL وجود نداشته باشد، یا منبعی که توسط مکانی منطبق بر $GIT_URL اشاره شده موجود نباشد، سرور نباید با پاسخ 200 OK پاسخ دهد. سرور باید با 404 Not Found، 410 Gone، یا هر کد وضعیت مناسب دیگر HTTP که دلالت بر وجود منبع درخواستی ندارد پاسخ دهد.

اگر مخزنی در $GIT_URL وجود داشته باشد اما دسترسی در حال حاضر مجاز نباشد، سرور باید با کد وضعیت HTTP 403 Forbidden پاسخ دهد.

سرورها باید از هر دو نسخه HTTP 1.0 و HTTP 1.1 پشتیبانی کنند. سرورها باید از کدگذاری تکه‌ای (chunked encoding) برای بدنه درخواست و پاسخ پشتیبانی کنند.

کلاینت‌ها باید از هر دو نسخه HTTP 1.0 و HTTP 1.1 پشتیبانی کنند. کلاینت‌ها باید از کدگذاری تکه‌ای (chunked encoding) برای بدنه درخواست و پاسخ پشتیبانی کنند.

سرورها می‌توانند هدرهای ETag و/یا Last-Modified را بازگردانند.

کلاینت‌ها می‌توانند با گنجاندن هدرهای درخواست If-Modified-Since و/یا If-None-Match، موجودیت‌های ذخیره‌شده در حافظه نهان (کَش) را مجدداً اعتبارسنجی کنند.

در صورتی که هدرهای مربوطه در درخواست موجود باشند و موجودیت تغییری نکرده باشد، سرورها می‌توانند 304 Not Modified را بازگردانند. کلاینت‌ها باید با استفاده مجدد از موجودیت ذخیره‌شده، رفتاری کاملاً یکسان با 304 Not Modified نسبت به 200 OK داشته باشند.

اگر هدر Cache-Control و/یا Expires اجازه کش کردن را بدهد، کلاینت‌ها می‌توانند موجودیت ذخیره‌شده را بدون اعتبارسنجی مجدد استفاده کنند. کلاینت‌ها و سرورها باید از RFC 2616 برای کنترل‌های حافظه نهان پیروی کنند.

کشف ارجاعات (DISCOVERING REFERENCES)

تمام کلاینت‌های HTTP باید تبادل واکشی (fetch) یا ارسال (push) را با کشف ارجاعات موجود در مخزن راه دور آغاز کنند.

C: GET $GIT_URL/info/refs HTTP/1.0

S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}

info_refs   =  *( ref_record )
ref_record  =  any_ref / peeled_ref

any_ref     =  obj-id HTAB refname LF
peeled_ref  =  obj-id HTAB refname LF
               obj-id HTAB refname "^{}" LF

C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0

S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}

S: 200 OK
S: Content-Type: application/x-git-upload-pack-advertisement
S: Cache-Control: no-cache
S:
S: 001e# service=git-upload-pack\n
S: 0000
S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
S: 0000

smart_reply     =  PKT-LINE("# service=$servicename" LF)
                   "0000"
                   *1("version 1")
                   ref_list
                   "0000"
ref_list        =  empty_list / non_empty_list

empty_list      =  PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)

non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)
                   *ref_record

cap-list        =  capability *(SP capability)
capability      =  1*(LC_ALPHA / DIGIT / "-" / "_")
LC_ALPHA        =  %x61-7A

ref_record      =  any_ref / peeled_ref
any_ref         =  PKT-LINE(obj-id SP name LF)
peeled_ref      =  PKT-LINE(obj-id SP name LF)
                   PKT-LINE(obj-id SP name "^{}" LF

سرویس هوشمند GIT-UPLOAD-PACK (SMART SERVICE GIT-UPLOAD-PACK)

این سرویس از مخزنی که توسط $GIT_URL مشخص شده است می‌خواند.

کلاینت‌ها ابتدا باید فرآیند کشف ارجاع را با $GIT_URL/info/refs?service=git-upload-pack انجام دهند.

C: POST $GIT_URL/git-upload-pack HTTP/1.0
C: Content-Type: application/x-git-upload-pack-request
C:
C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
C: 0000

S: 200 OK
S: Content-Type: application/x-git-upload-pack-result
S: Cache-Control: no-cache
S:
S: ....ACK %s, continue
S: ....NAK

کلاینت‌ها نباید یک پاسخ ذخیره‌شده در حافظه نهان را مجدداً استفاده یا اعتبارسنجی کنند. سرورها باید هدرهای Cache-Control کافی برای جلوگیری از کش شدن پاسخ را درج نمایند.

سرورها باید از تمام قابلیت‌های تعریف‌شده در اینجا پشتیبانی کنند.

کلاینت‌ها باید حداقل یک دستور "want" را در بدنه درخواست ارسال نمایند. کلاینت‌ها نباید به شناسه‌ای در دستور "want" ارجاع دهند که در پاسخ دریافتی از طریق کشف ارجاع وجود نداشته است، مگر اینکه سرور قابلیت allow-tip-sha1-in-want یا allow-reachable-sha1-in-want را اعلان کرده باشد.

compute_request   =  want_list
                     have_list
                     request_end
request_end       =  "0000" / "done"

want_list         =  PKT-LINE(want SP cap_list LF)
                     *(want_pkt)
want_pkt          =  PKT-LINE(want LF)
want              =  "want" SP id
cap_list          =  capability *(SP capability)

have_list         =  *PKT-LINE("have" SP id LF)

در دست تکمیل: این بخش در آینده کامل‌تر مستندسازی خواهد شد.

C: 0032want <want-#1>...............................
C: 0032want <want-#2>...............................
....
C: 0032have <common-#1>.............................
C: 0032have <common-#2>.............................
....
C: 0032have <have-#1>...............................
C: 0032have <have-#2>...............................
....
C: 0000

C: 0009done

S: PACK...

سرویس هوشمند GIT-RECEIVE-PACK (SMART SERVICE GIT-RECEIVE-PACK)

این سرویس از مخزنی که توسط $GIT_URL اشاره شده است می‌خواند.

کلاینت‌ها ابتدا باید کشف ارجاع را با $GIT_URL/info/refs?service=git-receive-pack انجام دهند.

C: POST $GIT_URL/git-receive-pack HTTP/1.0
C: Content-Type: application/x-git-receive-pack-request
C:
C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
C: 0000
C: PACK....

S: 200 OK
S: Content-Type: application/x-git-receive-pack-result
S: Cache-Control: no-cache
S:
S: ....

کلاینت‌ها نباید یک پاسخ کش‌شده را مجدداً استفاده یا اعتبارسنجی کنند. سرورها باید هدرهای Cache-Control کافی برای جلوگیری از کش شدن پاسخ را درج کنند.

سرورها باید از تمام قابلیت‌های تعریف‌شده در اینجا پشتیبانی کنند.

کلاینت‌ها باید حداقل یک دستور در بدنه درخواست ارسال کنند. در بخش دستور از بدنه درخواست، کلاینت‌ها باید شناسه‌ای را که از طریق کشف ارجاع به دست آورده‌اند به عنوان old_id ارسال کنند.

update_request  =  command_list
                   "PACK" <binary-data>

command_list    =  PKT-LINE(command NUL cap_list LF)
                   *(command_pkt)
command_pkt     =  PKT-LINE(command LF)
cap_list        =  *(SP capability) SP

command         =  create / delete / update
create          =  zero-id SP new_id SP name
delete          =  old_id SP zero-id SP name
update          =  old_id SP new_id SP name

در دست تکمیل: این بخش در آینده کامل‌تر مستندسازی خواهد شد.

منابع (REFERENCES)

RFC 1738: Uniform Resource Locators (URL)[1] RFC 2616: Hypertext Transfer Protocol — HTTP/1.1[2]

همچنین ببینید (SEE ALSO)

gitprotocol-pack(5) gitprotocol-capabilities(5)

گیت (GIT)

بخشی از مجموعه git(1)

نکات (NOTES)

1.

RFC 1738: Uniform Resource Locators (URL)

2.

RFC 2616: Hypertext Transfer Protocol — HTTP/1.1