.\" Automatically generated by Pandoc 3.9.0.2
.\"
.TH "CHA-CGI" "5"
.SH "نام (NAME)"
cha-cgi \- رابط CGI و پروتکل اسکریپت‌نویسی مرورگر وب متنی chawan
.SH "پشتیبانی از CGI محلی در Chawan (Local CGI support in Chawan)"
برنامه Chawan از فراخوانی اسکریپت‌های CGI قرارگرفته در دایرکتوری
مشخص‌شده در گزینه پیکربندی \f[CR]external.cgi\-dir\f[R] پشتیبانی می‌کند.
به‌طور پیش‌فرض، این گزینه روی \f[CR]$CHA_DIR/cgi\-bin\f[R]
(یعنی \f[CR]\(ti/.chawan/cgi\-bin\f[R] یا
\f[CR]\(ti/.config/chawan/cgi\-bin\f[R]، بسته به مکان
\f[CR]config.toml\f[R]) و
\f[CR]/usr/local/libexec/chawan/cgi\-bin\f[R] تنظیم شده است.
.PP
یک اسکریپت CGI در یکی از این دایرکتوری‌ها می‌تواند با باز کردن
نشانی \f[CR]cgi\-bin:script\-name\f[R] اجرا شود.
متغیرهای \f[CR]$PATH_INFO\f[R] و \f[CR]$QUERY_STRING\f[R] طبق معمول تنظیم می‌شوند،
یعنی \f[CR]cgi\-bin:script\-name/abcd?defgh=ijkl\f[R] مقدار
\f[CR]$PATH_INFO\f[R] را روی \f[CR]/abcd\f[R] و مقدار \f[CR]$QUERY_STRING\f[R]
را روی \f[CR]defgh=ijkl\f[R] تنظیم خواهد کرد.
.PP
نکات بیشتر درباره پردازش مسیرهای CGI:
.IP \(bu 2
نشانی باید کدر (opaque) باشد، بنابراین نباید بعد از طرح‌واره (scheme) دو اسلش اضافه کنید.
به عنوان مثال \f[CR]cgi\-bin://script\-name\f[R] کار نخواهد کرد و فقط
\f[CR]cgi\-bin:script\-name\f[R] معتبر است.
.IP \(bu 2
مسیرهایی که با \f[CR]/cgi\-bin/\f[R] یا \f[CR]/$LIB/\f[R] شروع می‌شوند به‌طور خودکار این بخش از آن‌ها حذف می‌شود.
بنابراین برای نمونه \f[CR]cgi\-bin:/cgi\-bin/script\-name\f[R] به
\f[CR]cgi\-bin:script\-name\f[R] تبدیل می‌شود.
.IP \(bu 2
اگر مقدار \f[CR]external.w3m\-cgi\-compat\f[R] برابر با true باشد، نشانی‌های file: در صورتی که نام مسیر با
\f[CR]/cgi\-bin/\f[R]، \f[CR]/$LIB/\f[R] یا مسیر یک اسکریپت CGI محلی شروع شود، به
نشانی‌های \f[CR]cgi\-bin:\f[R] تبدیل می‌شوند.
نکته: این رفتار ناامن است؛ لطفاً از آن استفاده نکنید مگر آنکه واقعاً نیاز باشد.
.IP \(bu 2
مسیرهای مطلق نیز پذیرفته می‌شوند، مانند
\f[CR]cgi\-bin:/path/to/cgi/dir/script\-name\f[R].
با این حال توجه داشته باشید که این حالت تنها زمانی کار می‌کند که \f[CR]/path/to/cgi/dir\f[R] از قبل
به عنوان یک دایرکتوری CGI در
\f[CR]external.cgi\-dir\f[R] تعیین شده باشد.
.SS "سرآیندها (Headers)"
اسکریپت‌های CGI محلی ممکن است سرآیندهایی ارسال کنند که Chawan آن‌ها را به‌طور ویژه تفسیر می‌کند (و بنابراین آن‌ها را به عنوان مثال به fetch API و غیره هدایت نخواهد کرد):
.IP \(bu 2
\f[CR]Status\f[R]: به عنوان کد وضعیت HTTP تفسیر می‌شود.
.IP \(bu 2
\f[CR]Cha\-Control\f[R]: سرآیند ویژه، به توضیحات زیر مراجعه کنید.
.PP
این سرآیندها \f[B]باید\f[R] پیش از هرگونه سرآیند عادی ارسال شوند.
سرآیندهایی که پس از یک سرآیند عادی یا سرآیند
\f[CR]Cha\-Control: ControlDone\f[R] دریافت شوند، به عنوان سرآیندهای عادی در نظر گرفته می‌شوند.
.PP
مقدار سرآیند \f[CR]Cha\-Control\f[R] به صورت زیر تجزیه می‌شود:
.IP
.EX
Cha\-Control\-Value = Command *Parameter
Command = ALPHA *ALPHA
Parameter = SPACE *CHAR
.EE
.PP
به عبارت دیگر ساختار آن به صورت \f[CR]Command [Param1] [Param2] ...\f[R] است.
.PP
دستورات در دسترس فعلی عبارتند از:
.IP \(bu 2
\f[CR]Connected\f[R]: هیچ پارامتری نمی‌پذیرد.
باید نخستین سرآیند گزارش‌شده باشد؛ این نشان می‌دهد که اتصال به سرور با موفقیت برقرار شده، اما هنوز داده‌ای دریافت نشده است.
هنگامی که هر سرآیند دیگری پیش از آن ارسال شود، Chawan به‌گونه‌ای عمل می‌کند که گویی سرآیند
\f[CR]Cha\-Control: Connected\f[R] پیش از آن به‌طور ضمنی ارسال شده است.
.IP \(bu 2
\f[CR]ConnectionError\f[R]: باید نخستین سرآیند گزارش‌شده باشد.
پارامتر ۱ کد خطا است، به ادامه مراجعه کنید.
اگر هرگونه پارامتر بعدی داده شود، آن‌ها به هم متصل می‌شوند تا یک پیام خطای سفارشی را تشکیل دهند.
.RS 2
.PP
نکته: پیام‌های خطای کوتاه اما گویا ترجیح داده می‌شوند؛ پیام‌هایی که در صفحه جا نمی‌شوند در حال حاضر کوتاه (truncate) می‌شوند.
.RE
.IP \(bu 2
\f[CR]ControlDone\f[R]: نشان می‌دهد که دیگر هیچ سرآیند ویژه‌ای ارسال نخواهد شد؛ این بدان معناست که سرآیندهای \f[CR]Cha\-Control\f[R] و \f[CR]Status\f[R]
که پس از این ارسال شوند باید به عنوان سرآیندهای عادی تفسیر گردند (و بنابراین به عنوان مثال برای کدهای جاوااسکریپتی که با استفاده از fetch API اسکریپت را فراخوانی می‌کنند در دسترس خواهند بود).
.RS 2
.PP
هشدار: این سرآیند باید پیش از هر سرآیند غیر کدگذاری‌شده‌ثابت که ورودی خارجی دریافت می‌کند ارسال شود.
برای مثال، یک کلاینت HTTP باید پیش از بازگرداندن سرآیندهای دریافتی،
\f[CR]Cha\-Control: ControlDone\f[R] را ارسال کند.
.RE
.PP
در ادامه فهرستی از کدهای خطا و معادل‌های رشته‌ای آن‌ها آمده است.
اسکریپت‌های CGI می‌توانند از هر یک (اما نه هر دو) در یک سرآیند ConnectionError استفاده کنند.
.IP \(bu 2
\f[CR]1 InternalError\f[R]: یک خطای داخلی مانع از بازیابی منبع درخواستی توسط اسکریپت شد.
اسکریپت‌های CGI همچنین می‌توانند از این کد استفاده کنند تا نشان دهند هیچ اطلاعی از علت بروز خطا ندارند.
.IP \(bu 2
\f[CR]2 InvalidMethod\f[R]: کلاینت داده‌ها را با استفاده از متدی درخواست کرده که توسط این پروتکل پشتیبانی نمی‌شود.
.IP \(bu 2
\f[CR]3 InvalidURL\f[R]: نشانی وب درخواستی نتوانست به عنوان یک نشانی وب معتبر برای این قالب تفسیر شود.
.IP \(bu 2
\f[CR]4 FileNotFound\f[R]: هیچ فایلی در نشانی درخواستی یافت نشد، بنابراین درخواست بی‌معنی است.
نکته: این مورد فقط باید توسط پروتکل‌هایی استفاده شود که متکی به معماری کلاینت-سرور نیستند، مانند دسترسی به فایل محلی، پایگاه‌های داده محلی یا سازوکارهای همتابه‌همتا (P2P) بازیابی فایل.
پاسخ سرور با \(lqno file found\(rq یک خطای اتصال نیست و بهتر است به عنوان پاسخی با کد وضعیت 404 نشان داده شود.
.IP \(bu 2
\f[CR]5 ConnectionRefused\f[R]: سرور از برقراری اتصال خودداری کرد.
.IP \(bu 2
\f[CR]6 ProxyRefusedToConnect\f[R]: پروکسی از برقراری اتصال خودداری کرد.
.IP \(bu 2
\f[CR]7 FailedToResolveHost\f[R]: نام میزبان نتوانست تحلیل (resolve) شود.
.IP \(bu 2
\f[CR]8 FailedToResolveProxy\f[R]: پروکسی نتوانست تحلیل (resolve) شود.
.IP \(bu 2
\f[CR]9 ProxyAuthFail\f[R]: پروکسی نام کاربری/گذرواژه ارائه‌شده را رد کرد.
.IP \(bu 2
\f[CR]10 InvalidResponse\f[R]: پاسخ سرور به قدری با مشخصات مغایرت دارد که پردازش معنادار آن امکان‌پذیر نیست.
.IP \(bu 2
\f[CR]11 ProxyInvalidResponse\f[R]: پاسخ پروکسی به قدری با مشخصات مغایرت دارد که پردازش معنادار آن امکان‌پذیر نیست.
.SS "متغیرهای محیطی (Environment variables)"
برنامه Chawan متغیرهای محیطی زیر را تنظیم می‌کند:
.IP \(bu 2
\f[CR]SERVER_SOFTWARE=\(dqChawan\(dq\f[R]
.IP \(bu 2
\f[CR]SERVER_PROTOCOL=\(dqHTTP/1.0\(dq\f[R]
.IP \(bu 2
\f[CR]SERVER_NAME=\(dqlocalhost\(dq\f[R]
.IP \(bu 2
\f[CR]SERVER_PORT=\(dq80\(dq\f[R]
.IP \(bu 2
\f[CR]REMOTE_HOST=\(dqlocalhost\(dq\f[R]
.IP \(bu 2
\f[CR]REMOTE_ADDR=\(dq127.0.0.1\(dq\f[R]
.IP \(bu 2
\f[CR]GATEWAY_INTERFACE=\(dqCGI/1.1\(dq\f[R]
.IP \(bu 2
\f[CR]SCRIPT_NAME=\(dq/cgi\-bin/script\-name\(dq\f[R] در صورت فراخوانی با یک
مسیر نسبی، و \f[CR]\(dq/path/to/script/script\-name\(dq\f[R] در صورت
فراخوانی با یک مسیر مطلق.
.IP \(bu 2
\f[CR]SCRIPT_FILENAME=\(dq/path/to/script/script\-name\(dq\f[R]
.IP \(bu 2
\f[CR]QUERY_STRING=\f[R] رشته پرس‌وجو (یعنی \f[CR]URL.search\f[R]).
این متغیر با کدگذاری درصدی (percent-encoded) تنظیم می‌شود.
.IP \(bu 2
\f[CR]PATH_INFO=\f[R] همه موارد بعد از نام مسیر اسکریپت،
مثلاً برای \f[CR]cgi\-bin:script\-name/abcd/efgh\f[R] برابر با
\f[CR]\(dq/abcd/efgh\(dq\f[R].
این متغیر با کدگذاری درصدی کدگذاری \f[B]نمی‌شود\f[R].
.IP \(bu 2
\f[CR]REQUEST_URI=\(dq$SCRIPT_NAME/$PATH_INFO?$QUERY_STRING\f[R]
.IP \(bu 2
\f[CR]REQUEST_METHOD=\f[R] متد HTTP استفاده‌شده برای ارسال درخواست،
مانند GET یا POST
.IP \(bu 2
\f[CR]REQUEST_HEADERS=\f[R] فهرستی جداشده با خط جدید از تمام سرآیندهای این درخواست.
.IP \(bu 2
\f[CR]CHA_LIBEXEC_DIR=\f[R] دایرکتوری libexec که Chawan در زمان کامپایل برای استفاده از آن پیکربندی شده است.
برای جزئیات درباره سودمند بودن این متغیر، بخش ابزارها را در ادامه ببینید.
.IP \(bu 2
\f[CR]CONTENT_TYPE=\f[R] برای درخواست‌های POST، مقدار سرآیند Content\-Type.
برای سایر انواع درخواست (مانند GET) تنظیم نمی‌شود.
.IP \(bu 2
\f[CR]CONTENT_LENGTH=\f[R] طول محتوا، در صورتی که $CONTENT_TYPE تنظیم شده باشد.
.IP \(bu 2
\f[CR]ALL_PROXY=\f[R] در صورت تعیین پروکسی، نشانی پروکسی.
هشدار: به دلایل امنیتی، این مورد \f[B]باید\f[R] هنگام برقراری ارتباطات خارجی رعایت شود.
اگر یک اسکریپت CGI از پروکسی پشتیبانی نمی‌کند، در زمان تنظیم بودن متغیر \f[CR]ALL_PROXY\f[R] هرگز نباید هیچ اتصال خارجی برقرار کند، بلکه باید یک پیام خطا بازگرداند.
.IP \(bu 2
\f[CR]HTTP_COOKIE=\f[R] در صورت تعیین، مقدار سرآیند Cookie.
.IP \(bu 2
\f[CR]HTTP_REFERER=\f[R] در صورت تعیین، مقدار سرآیند Referer.
.IP \(bu 2
\f[CR]CHA_TMP_DIR=\f[R] دایرکتوری مورداستفاده برای ذخیره فایل‌های موقت.
.IP \(bu 2
\f[CR]CHA_DIR=\f[R] مکان فایل پیکربندی.
.PP
برای درخواست‌هایی که از بازنویسی urimethodmap ناشی می‌شوند، Chawan همچنین بخش‌های تجزیه‌شده نشانی را به عنوان متغیرهای محیطی تنظیم می‌کند.
استفاده از این متغیرها به شدت توصیه می‌شود تا از اکسپلویت‌های ناشی از تجزیه دوگانه نشانی‌ها جلوگیری شود.
.PP
اگر
\f[CR]example://username:password\(atexample.org:1234/path/name.html?example\f[R]
نشانی اصلی باشد، در این صورت:
.IP \(bu 2
\f[CR]MAPPED_URI_SCHEME=\f[R] طرح‌واره نشانی اصلی، در این مورد \f[CR]example\f[R].
.IP \(bu 2
\f[CR]MAPPED_URI_USERNAME=\f[R] بخش نام کاربری، در این مورد \f[CR]username\f[R].
اگر هیچ نام کاربری مشخص نشده باشد، این متغیر روی رشته خالی تنظیم می‌شود.
.IP \(bu 2
\f[CR]MAPPED_URI_PASSWORD=\f[R] بخش گذرواژه، در این مورد \f[CR]password\f[R].
اگر هیچ گذرواژه‌ای مشخص نشده باشد، این متغیر روی رشته خالی تنظیم می‌شود.
.IP \(bu 2
\f[CR]MAPPED_URI_HOST=\f[R] بخش میزبان، در این مورد \f[CR]host.org\f[R].
اگر هیچ میزبانی مشخص نشده باشد، این متغیر روی رشته خالی تنظیم می‌شود.
(نمونه‌ای از نشانی بدون میزبان: \f[CR]about:blank\f[R]، که در اینجا \f[CR]blank\f[R] نام مسیر است.)
.IP \(bu 2
\f[CR]MAPPED_URI_PORT=\f[R] پورت، در این مورد \f[CR]1234\f[R].
اگر هیچ پورتی مشخص نشده باشد، این متغیر روی رشته خالی تنظیم می‌شود.
(در این حالت، انتظار می‌رود اسکریپت CGI در صورت وجود، از پورت پیش‌فرض طرح‌واره استفاده کند.)
.IP \(bu 2
\f[CR]MAPPED_URI_PATH=\f[R] نام مسیر، در این مورد \f[CR]/path/name.html?example\f[R].
اگر هیچ مسیری مشخص نشده باشد، این متغیر روی رشته خالی تنظیم می‌شود.
نام مسیر با کدگذاری درصدی ذخیره می‌شود.
.IP \(bu 2
\f[CR]MAPPED_URI_QUERY=\f[R] رشته پرس‌وجو، در این مورد \f[CR]example\f[R].
برخلاف جاوااسکریپت، علامت سؤال به ابتدای رشته افزوده نمی‌شود.
رشته پرس‌وجو نیز با کدگذاری درصدی ذخیره می‌شود.
.PP
بخش قطعه (fragment) عمداً نادیده گرفته شده است.
.SS "بدنه درخواست (Request body)"
اگر بدنه درخواست خالی نباشد، از طریق ورودی استاندارد به درون برنامه جریان می‌یابد.
.PP
توجه داشته باشید که این درخواست ممکن است از هر دو نوع application/x\-www\-form\-urlencoded یا multipart/form\-data باشد؛ متغیر \f[CR]CONTENT_TYPE\f[R] اطلاعات مربوط به نوع درخواست و در مورد درخواست چندبخشی (multipart)، مرز (boundary) را نیز ذخیره می‌کند.
.SS "ابزارها (Tools)"
برنامه Chawan باینری‌های کمکی خاصی فراهم می‌کند که ممکن است برای اسکریپت‌های CGI سودمند باشند.
این ابزارها می‌توانند با اجرای قابل‌حمل
\f[CR]\(dq$CHA_LIBEXEC_DIR\(dq/[program]\f[R] در دسترس قرار گیرند.
.PP
در حال حاضر، ابزارهای زیر در دسترس هستند:
.IP \(bu 2
\f[CR]urldec\f[R]: رمزگشایی درصدی رشته‌های ارائه‌شده در ورودی استاندارد.
.IP \(bu 2
\f[CR]urlenc\f[R]: کدگذاری درصدی رشته‌های ارائه‌شده در ورودی استاندارد، با دریافت مجموعه کدگذاری درصدی به عنوان پارامتر اول.
.SS "عیب‌یابی (Troubleshooting)"
توجه داشته باشید که خطای استاندارد (stderr) به کنسول مرورگر هدایت می‌شود (به‌طور پیش‌فرض، M\-cM\-c).
این قابلیت اشکال‌زدایی یک اسکریپت CGI با رفتار نادرست را آسان می‌کند، اما ممکن است در صورت ثبت بیش از حد لاگ، مرورگر را کُند سازد.
اگر این رفتار مورد نظر نیست، اسکریپت خود را در قالب یک اسکریپت شل بسته‌بندی کنید که stderr را به /dev/null هدایت کند.
.SS "اسکریپت من پیام خطای \(lqFailed to execute script\(rq برمی‌گرداند"
این بدان معناست که فراخوانی \f[CR]execl\f[R] برای اسکریپت با شکست مواجه شده است.
اطمینان حاصل کنید که بیت اجرایی اسکریپت CGI شما تنظیم شده باشد، یعنی دستور
\f[CR]chmod +x /path/to/cgi/script\f[R] را اجرا کنید.
.SS "اسکریپت من پیام خطای \(lqinvalid CGI path\(rq برمی‌گرداند"
مطمئن شوید که اسلش‌های ابتدایی اضافه نکرده‌اید.
یادآوری: \f[CR]cgi\-bin://script\-name\f[R] کار نمی‌کند، از
\f[CR]cgi\-bin:script\-name\f[R] استفاده کنید.
.SS "اسکریپت من پیام خطای \(lqCGI file not found\(rq برمی‌گرداند"
دوباره بررسی کنید که اسکریپت CGI شما در مکان درستی قرار داشته باشد.
همچنین، مطمئن شوید که تصادفاً اسکریپت را با یک مسیر مطلق از طریق \f[CR]cgi\-bin:/script\-name\f[R] (به جای حالت صحیح \f[CR]cgi\-bin:script\-name\f[R]) فراخوانی نمی‌کنید.
.PP
همچنین ممکن است مقدار \f[CR]external.cgi\-dir\f[R] روی دایرکتوری واقعی که اسکریپت شما در آن است تنظیم نشده باشد.
توجه داشته باشید که به‌طور پیش‌فرض، این مورد به مسیر فایل باینری وابسته است؛ بنابراین برای نمونه اگر فایل باینری شما در \f[CR]\(ti/src/chawan/target/release/bin/cha\f[R] قرار دارد، اما
اسکریپت CGI خود را در
\f[CR]/usr/local/libexec/chawan/cgi\-bin\f[R] قرار داده‌اید، کار نخواهد کرد.
.SS "اسکریپت من پیام خطای \(lqfailed to set up CGI script\(rq برمی‌گرداند"
این بدان معناست که یکی از فراخوانی‌های \f[CR]pipe\f[R] یا \f[CR]fork\f[R] با شکست مواجه شده است.
شاید با کمبود حافظه مواجه شده‌اید؟
.SH "همچنین ببینید (SEE ALSO)"
\f[B]cha\f[R](1) \f[B]cha\-urimethodmap\f[R](5)