Resterm

عميل API وبيئة عمل أصلية للطرفية (Terminal) لـ REST وGraphQL وgRPC وWebSocket وSSE.

Resterm هو بيئة عمل API-as-code — أو بعبارة مألوفة أكثر، عميل API — مبني حول ملفات .http و.rest نصية يمكنك مقارنتها (diff) ومراجعتها وإدارتها بالتحكم بالإصدارات. فهو يجمع بين التحرير التفاعلي للطلبات وسير العمل التصريحي (Workflows) والتأكيدات (Assertions) وخوادم المحاكاة (Mock Servers) والتتبّع (Tracing) والتنميط (Profiling) والأتمتة بدون واجهة (Headless). يبقى كل شيء على جهازك. لا حسابات، لا مزامنة سحابية، لا بيانات تتبع.

إذا كنت تبحث عن عميل بأسلوب Postman يتمحور حول مجموعات بواجهة رسومية (GUI)، فمن المحتمل أن Resterm ليس مناسبًا لك، لكن جرّبه على أي حال!

[!NOTE] أصبح Resterm الآن في الإصدار v1! اطّلع على ملاحظات إصدار v1.0.0 للتعرف على الميزات الجديدة والتغييرات الجذرية.

روابط سريعة: لقطات الشاشة، التثبيت، البدء السريع، التوثيق.

جولة في لقطات الشاشة

لماذا Resterm

• HTTP وGraphQL وgRPC وWebSocket وSSE بشكل جاهز.
• الأتمتة تعيش داخل ملفات الطلبات: الشروط (@when, @if/@elif/@else, @for-each)، وسير العمل متعدد الخطوات (@workflow / @step)، والالتقاطات، والمتغيرات والتأكيدات (@capture, @var, @assert).
• RestermScript، لغة تعبيرات صغيرة صُمّمت لـ Resterm، مع خطافات JavaScript عندما تحتاج إليها.
• أدوات تحكم بأسلوب Vim مع تلميحات سياقية في الشريط السفلي، ومساعدة دون اتصال قابلة للبحث، ومساعدة K تحت المؤشر، وبحث / وأوامر مثل :w و:q و و.

البدء السريع

1. ثبّت Resterm (انظر التثبيت للسكربتات ونظام Windows والتثبيت اليدوي).

   root@kitploit:~

   brew install resterm
   

2. جهّز مساحة عمل.

   root@kitploit:~

   mkdir my-api && cd my-api
   resterm init
   

   يمنحك resterm init مشروعًا صغيرًا يعمل دون اتصال بالإنترنت. يتضمن ملف requests.http المُولَّد سيناريوهات محاكاة محلية وعددًا من الطلبات التي يعتمد بعضها على الآخر. تغطي هذه السيناريوهات التأكيدات، ومصادقة Bearer، ومطابقة JSON، وjson-rules، و@for-each.

3. شغّله وأرسل طلبك الأول.

   root@kitploit:~

   resterm
   

   اضغط Ctrl+Enter في المحرر لإرسال الطلب المميّز.

لا توجد ملفات بعد؟ فقط شغّل resterm، واكتب عنوان URL ثم اضغط Ctrl+Enter. كما يعمل لصق أمر curl أيضًا.

CLI

ينفّذ resterm run ملفات .http / .rest دون فتح واجهة TUI، وهذا ما تستخدمه أنظمة CI.

resterm run --request CreateUser requests.http

يتواصل المشروع المُولَّد مع خادم محاكاة محلي. شغّله أولًا في طرفية أخرى:

resterm mock requests.http

داخل واجهة TUI، اضغط g Shift+M بدلًا من ذلك لتشغيل خادم المحاكاة نفسه من مساحة العمل.

يغطي توثيق CLI المحددات (Selectors) وصيغ الإخراج والمزيد من الأمثلة.

الخوادم الوهمية (Mock Servers)

يمكن للملفات نفسها التي تحتوي طلباتك أن تقدّم عمليات محاكاة HTTP.

• طابِق الطلبات الواردة حسب الاستعلام (Query) أو الترويسات (Headers) أو نص JSON، ثم اختر استجابة مسماة أو افتراضية.
• صمّم تدفقات الاستطلاع (Polling) وإعادة المحاولة بتسلسلات استجابات، بما في ذلك مؤشرات مستقلة لكل مورد أو متصل.
• أخّر الاستجابات بمقدار ثابت، أو امنح كل طلب تأخيرًا مختلفًا باستخدام random أو normal أو jitter.
• أنشئ استجابات من قيم المسار والاستعلام والترويسات والنص، مع مولّدات (Generators) للبيانات الديناميكية.
• تحقق من أعداد الاستدعاءات باستخدام @expect أو افحص حركة المرور المستلمة من RestermScript.
• أعد تحميل ملفات المصدر والملفات المساعدة (Fixtures) بشكل ساخن، مع دعم اختياري لـ TLS.

سيناريوهان على مسار واحد:

### Payment accepted
# @mock method=POST path=/payments name=accepted default=true latency=150ms
HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"pay_123","status":"pending"}

### Payment declined
# @mock method=POST path=/payments name=declined
# @match query={"mode":"decline"} headers={"X-Tenant":"demo"} json={"amount":0}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"error":"amount must be positive"}

قدّم ملفًا واحدًا أو دليلًا كاملًا:

resterm mock ./requests.http
resterm mock --recursive --addr 127.0.0.1:9090 ./requests

المزيد في مرجع الخوادم الوهمية، ودليل resterm mock في CLI، والمثال العملي.

بدون واجهة (Headless)

حزمة headless هي واجهة Go العامة للمحرك نفسه الذي يشغّل TUI وCLI. استخدمها لتشغيل الطلبات وسير العمل والتأكيدات ومقارنة التشغيلات والتنميطات من كود Go الخاص بك أو من CI.

إذا كنت تفضّل عدم بناء مُشغّل بنفسك، فهناك resterm-runner.

ورقة اختصارات لوحة المفاتيح

• تركيز الألواح وتخطيطها
  • Tab / Shift+Tab: التنقل بين الشريط الجانبي والمحرر والاستجابة.
  • g+r وg+i وg+p: الانتقال إلى الطلبات أو المحرر أو الاستجابة.
  • g+h / g+l: تغيير الحجم أفقيًا. يغيّر عرض الشريط الجانبي عندما يكون مركّزًا عليه، أو تقسيم المحرر/الاستجابة في الحالات الأخرى.
  • g+j / g+k: تغيير ارتفاع المحرر/الاستجابة عند التكديس، أو طيّ/توسيع الفروع في المستكشف (Navigator).
  • g+v / g+s: التبديل بين التخطيط المضمّن (Inline) والمكدّس (Stacked) للوحة الاستجابة.
  • g+1 وg+2 وg+3: تصغير أو استعادة الشريط الجانبي والمحرر والاستجابة.

[!TIP] إذا كنت ستتذكر ثلاث اختصارات فقط:

• Ctrl+Enter لإرسال الطلب
• Tab / Shift+Tab للتبديل بين الألواح
• g+p للانتقال إلى الاستجابة

التثبيت

Linux / macOS (Homebrew)

brew install resterm

[!NOTE] يجب تحديث تثبيتات Homebrew باستخدام Homebrew (brew upgrade resterm). أما أمر resterm --update المدمج فهو مخصص للملفات الثنائية المثبتة من إصدارات GitHub أو سكربتات التثبيت.

Linux / macOS (Shell script)

[!IMPORTANT] تعتمد الملفات الثنائية الجاهزة لنظام Linux على glibc 2.32 أو أحدث. على توزيعة أقدم، قم بالبناء من المصدر باستخدام سلسلة أدوات glibc أحدث، أو قم بترقية glibc قبل استخدام أرشيفات الإصدارات.

curl -fsSL https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

أو باستخدام wget:

wget -qO- https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.ps1 | iex

تكتشف السكربتات بنية جهازك، وتنزّل أحدث إصدار، وتثبّت الملف الثنائي.

التثبيت اليدوي

[!NOTE] تستخدم أداة التثبيت اليدوي curl وjq. ثبّت jq باستخدام مدير الحزم لديك (brew install jq أو sudo apt install jq أو ما شابه).

Linux / macOS

# Detect latest tag
LATEST_TAG=$(curl -fsSL https://api.github.com/repos/unkn0wn-root/resterm/releases/latest | jq -r .tag_name)

# Download the matching binary (Darwin/Linux + amd64/arm64)
curl -fL -o resterm "https://github.com/unkn0wn-root/resterm/releases/download/${LATEST_TAG}/resterm_$(uname -s)_$(uname -m)"

# Make it executable and move it onto your PATH
chmod +x resterm
sudo install -m 0755 resterm /usr/local/bin/resterm

Windows (PowerShell)

$latest = Invoke-RestMethod https://api.github.com/repos/unkn0wn-root/resterm/releases/latest
$asset  = $latest.assets | Where-Object { $_.name -like 'resterm_Windows_*' } | Select-Object -First 1
Invoke-WebRequest -Uri $asset.browser_download_url -OutFile resterm.exe
# Optionally relocate to a directory on PATH, e.g.:
Move-Item resterm.exe "$env:USERPROFILE\bin\resterm.exe"

من المصدر

go install github.com/unkn0wn-root/resterm/cmd/resterm@latest

التحديث

resterm --check-update
resterm --update

يُخبرك الأمر الأول بوجود إصدار أحدث أم لا، بينما يقوم الثاني بتنزيله والتحقق منه وتثبيته في مكانه. على Windows، يبقى الملف الثنائي القديم بجانب الجديد باسم resterm.exe.old ويُزال في التحديث التالي.

الإعدادات

• البيئات هي ملفات JSON (resterm.env.json) يتم اكتشافها في دليل الطلبات، أو جذر مساحة العمل، أو دليل العمل الحالي (CWD). يمكن للملف تعريف بيئات مسماة أو مجموعات مستقلة، مثل api وapp وcredentials، تتحد لتكوّن بيئة واحدة. ملفات Dotenv (.env, .env.*) اختيارية عبر --env-file وتكون خاصة بمساحة عمل واحدة. انظر البيئات المجمعة والعينة القابلة للتشغيل في _examples/grouped/.
• يُخزَّن الإعداد حسب نظام التشغيل ويمكن تجاوزه باستخدام RESTERM_CONFIG_DIR:
  • macOS: ~/Library/Application Support/resterm
  • Windows: %APPDATA%\resterm
  • Linux/Unix: ~/.config/resterm

المجموعات (Collections)

صدّر مساحة عمل كحزمة متوافقة مع Git واستوردها في مساحة أخرى. تحمل الحزم ملف manifest.json مع مجاميع اختبارية (Checksums)، لذلك تتحقق عمليات الاستيراد من سلامة الملفات أولًا. تُصدَّر قيم البيئة كعناصر نائبة REPLACE_ME، فلا تغادر أسرارك جهازك أبدًا.

resterm collection export --workspace ./my-api --out ./shared/my-api-bundle
resterm collection import --in ./shared/my-api-bundle --workspace ./my-local-api

أضف --dry-run لمعاينة الاستيراد و--force للكتابة فوق الملفات الموجودة. التوثيق: مشاركة المجموعات.

استيراد Curl

الصق أمر curl في المحرر واضغط Ctrl+Enter لتحويله إلى طلب منظم. يفهم Resterm العلامات الشائعة، ويدمج مقاطع البيانات المكررة، ويُبقي عمليات الرفع متعددة الأجزاء (Multipart) سليمة. تُتجاهَل بادئات الصدفة (Shell) مثل sudo أو $. يقوم CLI بنفس التحويل باستخدام --from-curl.

هذا:

curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  --user demo:secret \
  -d '{"user":"demo"}'

يصبح هكذا:

### POST https://api.example.com/login
# @auth basic demo secret
POST https://api.example.com/login
Content-Type: application/json

{"user":"demo"}

التوثيق: الطلبات المضمّنة وأمثلة الاستيراد.

RestermScript

RestermScript (RTS) هي لغة تعبيرات صغيرة صُمّمت لـ Resterm. تستهدف تنسيق الطلبات وسير العمل والتوجيهات مباشرة، مما يُبقي السكربتات قصيرة ويمكن التنبؤ بها. تبقى خطافات JavaScript متاحة عندما تحتاج إلى المزيد.

مثال سريع (وحدة RTS + طلب):

// rts/helpers.rts
module helpers
export fn authHeader(token) {
  return token ? "Bearer " + token : ""
}

# @use ./rts/helpers.rts
# @when env.has("feature")
# @assert response.statusCode == 200
GET https://api.example.com/users/{{= vars.get("user") }}
Authorization: {{= helpers.authHeader(vars.get("auth.token")) }}

المرجع الكامل: docs/restermscript.md.

الغوص في التفاصيل

OAuth 2.0

بيانات اعتماد العميل، ومنح كلمة المرور، ورمز التفويض مع PKCE. في تدفقات رمز التفويض، يفتح Resterm متصفحك، ويشغّل خادم استدعاء محليًا على 127.0.0.1، ويلتقط إعادة التوجيه ويستبدل الرمز. تُخزَّن الرموز مؤقتًا لكل بيئة وتُحدَّث عند انتهاء صلاحيتها. التوثيق: docs/resterm.md#oauth-20-directive و_examples/oauth2.http.

سير العمل والبرمجة النصية

سلسِل الطلبات باستخدام @workflow و@step، ومرّر البيانات بين الخطوات، وأضف خطافات JS عند الحاجة. التوثيق والعينة: docs/resterm.md#workflows و_examples/workflows.http.

مقارنة التشغيلات

شغّل الطلب نفسه عبر بيئات متعددة باستخدام @compare أو --compare، ثم قارن الاستجابات جنبًا إلى جنب بـ g+c. التوثيق: docs/resterm.md#compare-runs.

التتبّع والخط الزمني

أضف @trace مع ميزانيات (Budgets) لالتقاط توقيتات DNS والاتصال وTLS وTTFB والنقل. يسلّط Resterm الضوء على التجاوزات ويمكنه تصدير الامتدادات (Spans) إلى OpenTelemetry. التوثيق: docs/resterm.md#timeline--tracing.

البث (WebSocket وSSE)

استخدم @websocket مع خطوات @ws أو @sse لبرمجة البث وتسجيله. يحتفظ تبويب Stream بنصوص الجلسات (Transcripts) ويتضمن وحدة تحكم تفاعلية. التوثيق: docs/resterm.md#streaming-sse--websocket.

gRPC

استدعاءات Unary وبث مع نصوص جلسات وبيانات وصفية (Metadata) وتوسيع للنص. التوثيق: docs/resterm.md#grpc.

استيراد OpenAPI

حوّل مواصفات OpenAPI 3 إلى مجموعات .http باستخدام --from-openapi، من ملف محلي أو عنوان http(s) URL. اختر الكتل المُولَّدة باستخدام --openapi-mode requests أو mocks أو both. تحترم عمليات الجلب عن بُعد العلامتين العامتين --insecure و--proxy. التوثيق: docs/cli.md#import-examples.

أنفاق SSH

وجّه حركة مرور HTTP وgRPC وWebSocket وSSE عبر خوادم Bastion باستخدام ملفات تعريف @ssh. التوثيق: docs/resterm.md#ssh-tunnels و_examples/ssh.http.

إعادة توجيه المنافذ في Kubernetes

الفكرة نفسها مع ملفات تعريف @k8s، تستهدف Pods أو Services أو Deployments أو StatefulSets. التوثيق: docs/resterm.md#kubernetes-port-forwards و_examples/k8s.http.

السمات وربطات المفاتيح

خصّص الألوان وربطات المفاتيح (Keybindings) باستخدام themes/*.toml وbindings.toml أو bindings.json في دليل الإعدادات. التوثيق: docs/resterm.md#theming وdocs/resterm.md#custom-bindings.

التوثيق

• يغطي docs/resterm.md صيغة الطلبات والتوجيهات والبرمجة النصية ووسائط النقل.
• يغطي docs/cli.md resterm run وأدوات الاستيراد والمجموعات والسجل.
• يشرح التوافقية ضمانات التوافقية في Resterm للإصدار v1.

داخل TUI، اضغط ? أو شغّل :help. استخدم :docs عندما تريد الدليل الكامل على الويب للإصدار المثبت.

الترخيص

Apache License 2.0.