کتابخانه‌ی استاندارد · شبکه

فست سی جی آی net.fastcgi

کارخواه فست‌سی‌جی‌آی: اجرای PHP یا هر برنامه‌ی فست‌سی‌جی‌آی پشت یک سرور سلام.

واردسازی net.fastcgi

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

فست‌سی‌جی‌آی همان پروتکلی است که php-fpm و php-cgi -b می‌فهمند و این بسته یک کارخواه برای آن است. سرور وب در net.httpd برای تنظیم fastcgi_pass از همین بسته استفاده می‌کند؛ خودتان هم می‌توانید مستقیم از آن استفاده کنید وقتی برنامه‌ای باید یک درخواست را به یک اسکریپت PHP بسپارد.

یک درخواست فهرستی از متغیرهای CGI و یک بدنه است. NewParams فهرست را می‌سازد، Add آن را پر می‌کند، Connect اتصال TCP به پشتیبان باز می‌کند و Execute همه را می‌فرستد و منتظر پاسخ می‌ماند. پاسخ وضعیت، همه‌ی سرآیندها به همان ترتیبی که پشتیبان فرستاده و بدنه را به‌صورت اشاره‌گر و طول نگه می‌دارد، پس تصویر یا فایل فشرده سالم برمی‌گردد.

// lang: en
package main

import net.fastcgi
import net.tcp

func main:
    p := fastcgi.NewParams()
    defer fastcgi.Free(p)
    fastcgi.Add(p, "GATEWAY_INTERFACE", "CGI/1.1")
    fastcgi.Add(p, "REQUEST_METHOD", "GET")
    fastcgi.Add(p, "SCRIPT_NAME", "/index.php")
    fastcgi.Add(p, "SCRIPT_FILENAME", "/srv/app/index.php")
    fastcgi.Add(p, "QUERY_STRING", "a=1")

    c := fastcgi.Connect("127.0.0.1", 9000, 5000)
    if not tcp.ConnOk(c):
        println "cannot reach the FastCGI backend"
        ret 1
    end
    defer tcp.Close(c)

    r := fastcgi.Execute(c, p, null, 0, 5000)
    if not r.ok:
        println "the request failed: ", r.error
        ret 1
    end
    println r.status, " ", r.len, " bytes"
    fastcgi.FreeResponse(r)
    ret 0
end

هر اتصال یک درخواست را می‌برد، که همان چیزی است که php-fpm از یک جلوی ساده انتظار دارد. زمان‌سنج به میلی‌ثانیه است و کل تبادل را در بر می‌گیرد، از اتصال هم؛ صفر یعنی ۳۰ ثانیه. پشتیبانی که اتصال را زود ببندد، پاسخی که بلوک سرآیند نداشته باشد یا خطای پروتکل به‌صورت ok = false و پیام در error برمی‌گردد، نه به‌صورت از کار افتادن برنامه.

چیزهایی که مردم اشتباه می‌کنند:

  • Execute بدنه را به‌صورت اشاره‌گر و طول می‌گیرد. وقتی بدنه‌ای نیست null و 0 بدهید؛ رشته‌ی خالی اشاره‌گر نیست.
  • Add نام و مقدار را کپی می‌کند، پس رشته‌ی موقت را می‌توانید بلافاصله بعد از Add آزاد کنید و Free همه‌ی کپی‌ها را آزاد می‌کند.
  • بدنه‌ی پاسخ متعلق به پاسخ است: وقتی کارتان تمام شد FreeResponse را صدا بزنید، وگرنه بافر آزاد نمی‌شود.
  • نشانی TCP است. php-fpm باید روی یک درگاه مثل 127.0.0.1:9000 گوش بدهد، نه روی سوکت یونیکس، و پر کردن متغیرهای CGI با شماست: پشتیبان دست‌کم به SCRIPT_FILENAME و REQUEST_METHOD نیاز دارد تا پاسخ بدهد.
  • خروجی خطای پشتیبان خطا نیست. یک اخطار PHP روی stderr درخواست را خراب نمی‌کند؛ فقط پاسخ شکسته یا نبودِ پاسخ این کار را می‌کند.

توصیف درخواست با متغیرهای CGI

PHP درباره‌ی یک درخواست فقط از متغیرهایی که می‌فرستید باخبر می‌شود. با پارامترهای جدید یک فهرست بسازید، هر نام و مقدار را با افزودن بیفزایید و آخر کار فهرست را آزاد کنید. آیتم‌ها به ترتیب افزوده شدن می‌مانند و افزودن هر دو رشته را کپی می‌کند.

net-fastcgi-guide-params.salam
واردسازی شبکه.فست سی جی آی

تابع ریشه:
    ناپایا پ := فست سی جی آی.پارامترهای جدید()
    دیرکن فست سی جی آی.آزادسازی(پ)
    فست سی جی آی.افزودن(پ، "GATEWAY_INTERFACE"، "CGI/1.1")
    فست سی جی آی.افزودن(پ، "REQUEST_METHOD"، "POST")
    فست سی جی آی.افزودن(پ، "SCRIPT_FILENAME"، "/srv/app/index.php")
    فست سی جی آی.افزودن(پ، "SCRIPT_NAME"، "/index.php")
    فست سی جی آی.افزودن(پ، "QUERY_STRING"، "page=2")
    فست سی جی آی.افزودن(پ، "CONTENT_TYPE"، "application/json")
    فست سی جی آی.افزودن(پ، "CONTENT_LENGTH"، "13")
    هر آیتم در پ.آیتم ها:
        سرچاپ آیتم.نام + "=" + آیتم.مقدار
    پایان
پایان
خروجیGATEWAY_INTERFACE=CGI/1.1 REQUEST_METHOD=POST SCRIPT_FILENAME=/srv/app/index.php SCRIPT_NAME=/index.php QUERY_STRING=page=2 CONTENT_TYPE=application/json CONTENT_LENGTH=13

پشتیبان دست‌کم به REQUEST_METHOD و SCRIPT_FILENAME نیاز دارد؛ نام‌های دیگر همان‌هایی هستند که کد PHP معمولاً از $_SERVER می‌خواند. برای درخواستی که بدنه دارد، CONTENT_LENGTH باید دقیقاً برابر تعداد بایت‌هایی باشد که می‌فرستید.

فرستادن درخواست به php-fpm و خواندن پاسخ

با اتصال یک ارتباط باز کنید و با اتصال معتبر از بسته‌ی تی‌سی‌پی آن را بیازمایید، بعد اجرا را با ارتباط، متغیرها، بدنه و مهلت به میلی‌ثانیه صدا بزنید. GET بدنه ندارد، پس بدنه پوچ و طول ۰ است. پاسخ وضعیت، سرصفحه‌ها به ترتیب، و بدنه را با اندازه‌اش می‌دهد؛ موفق فقط وقتی نادرست است که پاسخ کاملی نرسیده باشد، پس ۴۰۴ از PHP هم موفق است.

net-fastcgi-guide-request.salam
واردسازی شبکه.فست سی جی آی
واردسازی شبکه.تی سی پی

تابع ریشه:
    ناپایا پ := فست سی جی آی.پارامترهای جدید()
    دیرکن فست سی جی آی.آزادسازی(پ)
    فست سی جی آی.افزودن(پ، "GATEWAY_INTERFACE"، "CGI/1.1")
    فست سی جی آی.افزودن(پ، "REQUEST_METHOD"، "GET")
    فست سی جی آی.افزودن(پ، "SCRIPT_NAME"، "/index.php")
    فست سی جی آی.افزودن(پ، "SCRIPT_FILENAME"، "/srv/app/index.php")
    فست سی جی آی.افزودن(پ، "QUERY_STRING"، "a=1")

    ا := فست سی جی آی.اتصال("127.0.0.1"، ۹۰۰۰، ۳۰۰۰)
    اگر وارونه تی سی پی.اتصال معتبر(ا):
        سرچاپ "php-fpm is not listening on 127.0.0.1:9000"
        برگشت ۱
    پایان
    دیرکن تی سی پی.بستن(ا)

    ناپایا پاسخ := فست سی جی آی.اجرا(ا، پ، پوچ، ۰، ۵۰۰۰)
    اگر وارونه پاسخ.موفق:
        سرچاپ "failed:"، پاسخ.خطا
        برگشت ۱
    پایان
    سرچاپ پاسخ.وضعیت، پاسخ.اندازه، "bytes"
    هر س در پاسخ.سرصفحه ها:
        سرچاپ س.نام + ": " + س.مقدار
    پایان
    فست سی جی آی.آزادسازی پاسخ(پاسخ)
پایان

برای امتحان، php-fpm را با listen = 127.0.0.1:9000 اجرا کنید و SCRIPT_FILENAME را به یک اسکریپت واقعی بدهید. پاسخ را با آزادسازی پاسخ آزاد کنید و ارتباط را ببندید؛ هر ارتباط یک درخواست را حمل می‌کند. اگر فقط می‌خواهید سایت‌های PHP را سرو کنید لازم نیست این کار را خودتان بنویسید: تنظیم fastcgi_pass در net.httpd آن را برایتان انجام می‌دهد.

گونه‌ها

پارامتر Param

ساختار پارامتر
یک متغیر CGI: نامی مثل REQUEST_METHOD و مقدارش.
نامانگلیسیگونهتوضیح
نامnameرشته = ""نام متغیر، همان‌طور که PHP از $_SERVER می‌خواند.
مقدارvalueرشته = ""مقدار متغیر.
net-fastcgi-Params.salam
واردسازی شبکه.فست سی جی آی

تابع ریشه:
    ناپایا p := فست سی جی آی.پارامترهای جدید()
    دیرکن فست سی جی آی.آزادسازی(p)

    فست سی جی آی.افزودن(p، "REQUEST_METHOD"، "GET")
    فست سی جی آی.افزودن(p، "SCRIPT_NAME"، "/index.php")

    هر item در p.آیتم ها:
        سرچاپ item.نام + "=" + item.مقدار
    پایان
پایان
خروجیREQUEST_METHOD=GET SCRIPT_NAME=/index.php

پارامترها Params

ساختار پارامترها
فهرست متغیرهای CGI یک درخواست. Add به آن می‌افزاید و Free آزادش می‌کند.
نامانگلیسیگونهتوضیح
آیتم هاitemsوکتور<پارامتر>متغیرها، به ترتیبی که افزوده شده‌اند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Params.salam

ساختار سرصفحه
یک سرآیند پاسخ، همان‌طور که پشتیبان فرستاده. یک نام می‌تواند چند بار بیاید و این‌گونه چند سرآیند Set-Cookie می‌رسد.
نامانگلیسیگونهتوضیح
نامnameرشته = ""نام سرآیند.
مقدارvalueرشته = ""مقدار سرآیند، بدون نام و دونقطه.
net-fastcgi-Connect.salam
واردسازی شبکه.فست سی جی آی
واردسازی شبکه.تی سی پی

تابع ریشه:
    ناپایا p := فست سی جی آی.پارامترهای جدید()
    دیرکن فست سی جی آی.آزادسازی(p)
    فست سی جی آی.افزودن(p، "REQUEST_METHOD"، "GET")
    فست سی جی آی.افزودن(p، "SCRIPT_NAME"، "/index.php")
    فست سی جی آی.افزودن(p، "SCRIPT_FILENAME"، "/srv/app/index.php")

    c := فست سی جی آی.اتصال("127.0.0.1"، 9000، 1000)
    اگر وارونه تی سی پی.اتصال معتبر(c):
        سرچاپ "no FastCGI backend on 127.0.0.1:9000"
        برگشت 1
    پایان
    دیرکن تی سی پی.بستن(c)

    ناپایا r := فست سی جی آی.اجرا(c، p، پوچ، 0، 5000)
    اگر وارونه r.موفق:
        سرچاپ r.خطا
        برگشت 1
    پایان
    سرچاپ r.وضعیت، r.اندازه
    فست سی جی آی.آزادسازی پاسخ(r)
    برگشت 0
پایان

پاسخ Response

ساختار پاسخ
پاسخ پشتیبان: وضعیت، سرآیندها و بدنه به‌صورت اشاره‌گر با طولش.
نامانگلیسیگونهتوضیح
وضعیتstatusصحیح = 0وضعیت HTTP از خط Status:، یا ۲۰۰ وقتی پشتیبان چنین خطی نمی‌فرستد.
سرصفحه هاheadersوکتور<سرصفحه>سرآیندها به ترتیبی که پشتیبان فرستاده، بدون Status.
بدنهbodyتهی*بایت‌های بدنه که متعلق به پاسخ‌اند. وقتی کارتان تمام شد به FreeResponse بدهید.
اندازهlenصحیح = 0تعداد بایت‌های بدنه؛ صفر وقتی بدنه خالی است و body تهی است.
موفقokمنطقی = نادرستدرست وقتی پاسخی کامل خوانده شد، هر وضعیتی که داشته باشد. ۴۰۴ از PHP هم ok است.
خطاerrorرشته = ""دلیل شکست درخواست وقتی ok نادرست است: نبود اتصال، پاسخ نیمه‌کاره، خطای پروتکل، یا متن stderr وقتی بلوک سرآیند نرسیده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Connect.salam

تابع‌ها

پارامترهای جدید NewParams

تابع پارامترهای جدید(): پارامترها
فهرست خالی متغیرهای CGI می‌سازد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Params.salam

افزودن Add

تابع افزودن(p &: پارامترها، name: رشته، value: رشته)
یک متغیر CGI می‌افزاید و نام و مقدار را کپی می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Params.salam

آزادسازی Free

تابع آزادسازی(p &: پارامترها)
فهرست و همه‌ی نام‌ها و مقدارهایش را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Params.salam

اتصال Connect

تابع اتصال(host: رشته، port: صحیح، timeout_ms: صحیح): تی سی پی.اتصال شبکه
اتصال TCP به پشتیبان فست‌سی‌جی‌آی باز می‌کند. زمان‌سنج به میلی‌ثانیه است؛ صفر یعنی ۳۰ ثانیه. با tcp.ConnOk بررسی‌اش کنید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Connect.salam

اجرا Execute

تابع اجرا(c: تی سی پی.اتصال شبکه، params: پارامترها، data: تهی*، n: صحیح، timeout_ms: صحیح): پاسخ
پارامترها و بدنه را می‌فرستد و پاسخ را می‌خواند. بدنه اشاره‌گر و طول است و زمان‌سنج کل تبادل را در بر می‌گیرد. پاسخ برگشتی را باید با FreeResponse آزاد کنید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Connect.salam

آزادسازی پاسخ FreeResponse

تابع آزادسازی پاسخ(r &: پاسخ)
بدنه و رشته‌های سرآیند یک پاسخ را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: net-fastcgi-Connect.salam