مدیریت حساب‌ها از خط فرمان

در checkout مخزن WaterWall برنامهٔ tunnels/APIServer/client/ww_admin.py قرار دارد. این برنامه با Python نسخهٔ 3.10 یا جدیدتر و فقط کتابخانهٔ استاندارد، فرمان‌های مدیریت حساب را ارائه می‌کند. هنگام کپی‌کردن دایرکتوری کلاینت، ww_admin.py، ww_api.py و ww_api_cli.py را کنار یکدیگر نگه دارید؛ نصب package لازم نیست. transport و envelope بیرونی در ww_api.py است؛ گزینه‌های اتصال، خواندن محدود token و راهنمای نوشتن نامعلوم در ww_api_cli.py مشترک‌اند. اعتبارسنجی schema بدنهٔ AuthenticationServer در CLI باقی می‌ماند.

از پیکربندی سرور محلی شروع کنید و نقش‌های مستقل creator، editor و password-admin را طبق بخش مجوزهای مثال مدیریت حساب اضافه کنید. فرمان‌های زیر از دایرکتوری api-demo همان مثال اجرا می‌شوند؛ WATERWALL_REPO مسیر مطلق checkout است. مجوزها همچنان در APIServer تعریف می‌شوند؛ CLI دسترسی اضافه‌ای نمی‌دهد.

انتخاب سرور و اپراتور

یک فرمان کامل:

python3 "$WATERWALL_REPO/tunnels/APIServer/client/ww_admin.py" \
  --host 127.0.0.1 --port 9080 \
  --client monitor --token-file monitor-token \
  --config central --node auth-db status

گزینه‌های اتصال و احراز هویت باید پیش از status یا users باشند. پیش‌فرض‌ها: host برابر 127.0.0.1، port برابر 9080، timeout برابر ۱۰ ثانیه و سقف envelope پاسخ برابر 1 MiB. با --timeout و --max-response-bytes این حدها را تغییر دهید. هر خواندن socket حداکثر 64 KiB درخواست می‌کند و تمام chunkها همان deadline اصلی monotonic را دارند. سقف پاسخ از ۱ بایت تا 64 MiB قابل تنظیم است. timeout برای یک درخواست کامل است، ولی lookup مسدودکنندهٔ hostname در Python ممکن است پیش از بازگشت کنترل از آن بیشتر طول بکشد؛ اگر این محدودیت resolver مناسب نیست، آدرس IP بدهید. --client و --node لازم‌اند. یکی از --token-file PATH یا --token-env NAME را انتخاب کنید؛ دومی نام متغیر محیطی حاوی token است. گزینه‌ای برای قرار دادن مقدار token در آرگومان خط فرمان وجود ندارد.

--config central نام منطقی config است، نه نام فایل. حذف آن فقط وقتی ممکن است که نام node بین تمام configهای بارگذاری‌شده یکتا باشد. این CLI از TCP استفاده می‌کند؛ ورودی TCP محلی می‌تواند از پل UDP قابل اعتماد موجود استفاده کند. CLI درخواست HTTP نمی‌سازد و رمزنگاری اضافه نمی‌کند؛ دسترسی راه دور به transport حفاظت‌شده نیاز دارد.

برای کوتاه‌شدن فرمان‌های Bash بعدی این تابع را تعریف کنید:

wwadmin() {
  local operator="$1"
  shift
  python3 "$WATERWALL_REPO/tunnels/APIServer/client/ww_admin.py" \
    --client "$operator" --token-file "${operator}-token" \
    --config central --node auth-db "$@"
}

فرمان status همیشه object به نام audit را نیز برمی‌گرداند. enabled فعال‌بودن لاگ ممیزی AuthenticationServer را نشان می‌دهد؛ healthy، dropped_records، write_failures و last_error سلامت آن را مشخص می‌کنند. queued_records عمق صف و written_records تعداد append/flush موفق است. شمارنده‌ها رشتهٔ ده‌دهی و متعلق به همین فرایندند. در حالت غیرفعال، healthy true و شمارنده‌ها صفر هستند. خطای ممیزی نتیجهٔ commit حساب را تغییر نمی‌دهد. تنظیم و rotation در AuthenticationServer تعریف می‌شود؛ CLI فایل لاگ را مدیریت نمی‌کند.

خواندن حساب و پیمایش فهرست

wwadmin monitor status
wwadmin monitor users list --limit 50
wwadmin monitor users get 42

تا پیش از ساخت این ID، فرمان get خطای not_found می‌دهد. ID و مقدارهای unsigned حساب به‌شکل رشتهٔ ده‌دهی باقی می‌مانند؛ مقدارهای بزرگ‌تر از محدودهٔ integer دقیق JavaScript نیز حفظ می‌شوند. خروجی همان schema عمومی API بدون اطلاعات محرمانه است؛ رمز و credentialهای مشتق‌شده نمایش داده نمی‌شوند.

users list به‌طور پیش‌فرض ۵۰ خلاصه می‌خواند و limit از ۱ تا ۱۰۰ می‌پذیرد. برای یک صفحهٔ بعدی، مقدار دقیق next_cursor را به --cursor بدهید. پیمایش خودکار:

wwadmin monitor users list --all --limit 50 --max-pages 100 > pages.jsonl

خروجی هر صفحهٔ کامل در یک خط JSON است، شامل metadata صفحه و آرایهٔ users. صفحه‌ها هنگام رسیدن نوشته می‌شوند و به یک آرایهٔ نامحدود تبدیل نمی‌شوند. پیش‌فرض --max-pages برابر ۱۰۰ و بازهٔ مجاز آن ۱ تا ۱۰۰۰۰ است. رسیدن به این سقف وقتی cursor دیگری باقی است خطا محسوب می‌شود، نه پیمایش کامل. cursor تکراری، پاسخ نامعتبر، درخواست ناموفق یا stale_cursor نیز فرمان را متوقف می‌کند. کد خروج را بررسی کنید؛ اگر صفحهٔ بعدی شکست بخورد، خط‌های قبلی نتیجهٔ ناقص هستند.

ویرایش تنظیمات cursorها را نامعتبر می‌کند. CLI مخفیانه پیمایش را از اول شروع نمی‌کند تا صفحهٔ تکراری به خروجی اضافه شود؛ پس از stale شدن، صریحاً پیمایش تازه بسازید و خروجی قبلی را جایگزین کنید. آمار مصرف ممکن است بین صفحه‌های معتبر عوض شود؛ پیمایش موفق snapshot ثابت مصرف نیست. نام در خلاصه ممکن است کوتاه شود؛ برای جزئیات کامل مجاز از users get استفاده کنید.

ساخت حساب

wwadmin creator users create 42 --set name=alice --set enabled=false

CLI رمز اولیه را دو بار و بدون نمایش ورودی می‌پرسد. ID عددی غیرصفر و دائمی را شما انتخاب می‌کنید. ساخت حساب مجوز create-user می‌خواهد ولی edit token لازم ندارد؛ ID موجود هیچ‌وقت جایگزین نمی‌شود.

برای policy اولیه --set FIELD=VALUE را تکرار کنید. فیلدهای حذف‌شده از پیش‌فرض سرور استفاده می‌کنند، از جمله حساب فعال با سقف‌های صفر به معنی نامحدود/تنظیم‌نشده. enabled=false در مثال، حساب را غیرفعال آماده می‌کند. نام فیلدها همان snake_case و nesting نقطه‌ای API عمومی است:

--set limit.traffic.total=1000000000
--set time.expire_after_first_usage_ms=2592000000
--set wireguard_allowed_ips=10.44.0.1/32
--set notes=

مقدار عددی رشتهٔ unsigned ده‌دهی canonical است؛ boolean فقط true یا false می‌پذیرد. رشته به‌صورت literal استفاده می‌شود؛ مقدار خالی فیلد را پاک می‌کند. فیلد ناشناخته یا تکراری رد می‌شود. واحد، بازه، معنای صفر و محدودیت‌های ۱۸ فیلد قابل ویرایش در مرجع API آمده است. ذخیرهٔ policy قابلیت اجرای آن را به nodeهای دیگر اضافه نمی‌کند.

خواندن، بررسی و ویرایش

با token ویرایشگر حساب را بخوانید:

wwadmin editor users get 42 > account.json

فقط در صورت موفقیت ادامه دهید. account.json را بررسی کنید و token همان read را بردارید:

EDIT_TOKEN="$(python3 -c 'import json; print(json.load(open("account.json"))["edit_token"])')"
wwadmin editor users update 42 --if-match "$EDIT_TOKEN" \
  --set enabled=true --set limit.traffic.total=1000000000

CLI فقط فیلدهای انتخاب‌شده را ارسال می‌کند. مصرف، تاریخ اولین استفاده و credential قابل patch نیستند. enable و disable میان‌بر ویرایش یک فیلد هستند:

wwadmin editor users get 42 > account.json
# پس از read موفق، حساب را بررسی و token جاری آن را دوباره دریافت کنید.
EDIT_TOKEN="$(python3 -c 'import json; print(json.load(open("account.json"))["edit_token"])')"
wwadmin editor users disable 42 --if-match "$EDIT_TOKEN"

users enable هم به همین شکل است. برای این فرمان‌ها و تغییر رمز، --if-match اجباری است. token هویت نمونهٔ سرور و revision سراسری تنظیمات را دارد؛ ویرایش حساب دیگر هم می‌تواند آن را نامعتبر کند. conflict یعنی این invocation تغییر را commit نکرده است. دوباره بخوانید و تغییر را بازبینی کنید. CLI هیچ‌وقت token تازه را خودکار نمی‌خواند تا write قبلی را دوباره اجرا کند.

تغییر رمز

با مجوز مستقل مدیر رمز بخوانید و حساب را بررسی کنید:

wwadmin password-admin users get 42 > account.json
# فقط پس از read موفق و بررسی حساب ادامه دهید.
EDIT_TOKEN="$(python3 -c 'import json; print(json.load(open("account.json"))["edit_token"])')"
wwadmin password-admin users change-password 42 --if-match "$EDIT_TOKEN"

پیش‌فرض، prompt پنهان همراه تأیید دوباره است. برای automation، ساخت حساب و تغییر رمز یکی از --password-file PATH یا --password-stdin را می‌پذیرند. هیچ‌کدام مقدار رمز را در آرگومان خط فرمان نمی‌پذیرند. ورودی فایل و stdin باید UTF-8 غیرخالی و بدون NUL باشد و دقیق حفظ می‌شود: newline انتهای فایل بخشی از رمز است. منبع secret باید بایت‌های مورد نظر را بنویسد؛ echo معمولی newline اضافه می‌کند. فایل token رفتار جدا دارد: دقیقاً ۶۴ نویسهٔ hexadecimal، با CR، LF یا CRLF اختیاری در انتها. خواندن به ۶۶ بایت و یک بایت تشخیص سرریز محدود است؛ ورودی غیر ASCII یا بزرگ و نام خالی گزینهٔ environment پیش از transport رد می‌شود.

تغییر رمز ID، policy، مصرف و تاریخ اولین استفاده را حفظ می‌کند و session موجود را اجباری قطع نمی‌کند. برای معنای credentialهای مشتق‌شده و هویت UUID، مرجع تغییر رمز را بخوانید.

پیش از write بعدی نتیجه را تفسیر کنید

فرمان موفق JSON را روی stdout می‌نویسد. خطا و راهنمای بازیابی روی stderr است؛ پیام دلخواه خطای سرور و secret ورودی بازتاب داده نمی‌شوند.

کد خروج	معنا
`0`	موفق؛ در `--all` صفحهٔ آخر رسیده است.
`1`	خطای معتبر operation در node، مانند `conflict` یا `stale_cursor`.
`2`	اعتبارسنجی محلی، read ناموفق، رد قطعی gateway، یا شکست سقف/سازگاری محلی pagination.
`3`	ممکن است write انجام شده باشد، ولی نتیجه قابل اثبات نیست.

کلاینت retry خودکار ندارد. اگر پاسخ write گم شود، نامعتبر باشد یا پس از dispatch احتمالی timeout رخ دهد، ورودی مورد نظر را نگه دارید و دوباره بخوانید. پیش از تصمیم صریح دربارهٔ تغییر بعدی، حساب را مقایسه کنید. برای ساخت حساب ID اولیه را نگه دارید؛ وجود آن ثابت نمی‌کند چه کسی آن را ساخته یا چه رمزی دارد. ID تازه را خودکار انتخاب نکنید.

خطاهای busy و shutting_down در سطح gateway برای ساخت، ویرایش و تغییر رمز، رد قطعی پیش از فراخوانی handler هستند؛ با exit code برابر 2 و بدون راهنمای نتیجهٔ نامعلوم یا retry برمی‌گردند. همان code در نتیجهٔ node، outcome جداگانهٔ operation است؛ خطاهای gateway پس از dispatch همچنان می‌توانند نتیجهٔ نامعلوم داشته باشند.

read عمومی رمز نصب‌شده را اثبات نمی‌کند. پس از تغییر رمز با نتیجهٔ نامعلوم، صریحاً تصمیم بگیرید آیا رمز مورد نظر را با edit token تازه دوباره ارسال می‌کنید. ارسال مجددِ تأییدشده همان رمز را در نقطهٔ commit خودش برقرار می‌کند. تغییر revision به‌تنهایی موفقیت یک درخواست قبلی خاص را ثابت نمی‌کند.

ACK تغییر در حافظهٔ سرور را تأیید می‌کند، نه ذخیره روی دیسک یا refresh شدن AuthenticationClient. کلاینت آفلاین تا refresh معتبر با policy و credential cacheشده ادامه می‌دهد. این CLI crash recovery یا رکورد retry سمت سرور اضافه نمی‌کند. تضمین API اصلی در workflowهای سطح wire و قواعد تحویل پروتکل آمده است.

انتخاب سرور و اپراتور​

خواندن حساب و پیمایش فهرست​

ساخت حساب​

خواندن، بررسی و ویرایش​

تغییر رمز​

پیش از write بعدی نتیجه را تفسیر کنید​