small-software 0.6.0__py3-none-any.whl

small_cli/commands/db.py

@@ -0,0 +1,154 @@
+"""small db: база данных для приложения в один шаг.
+
+add — разворачивает шаблон Railway (как `railway add --database`) в проекте приложения и передаёт приложению
+ссылку на базу через переменную-ссылку Railway (${{Postgres.DATABASE_URL}}), поэтому пароль нигде не хранится
+у нас. База записывается в .small.json, и small destroy удаляет её вместе с приложением.
+"""
+
+import argparse
+import time
+
+from ..common import CliError, app_dir, ask, linked_state, require_token, say
+from ..config import STATE_FILE, save_state
+from ..i18n import tr
+from ..railway import Railway, RailwayError
+from .env import add_no_deploy, change_env, report_env_change
+
+# Тип -> (код шаблона Railway, переменная приложения, переменная базы).
+DATABASES = {
+    "postgres": ("postgres", "DATABASE_URL", "DATABASE_URL"),
+}
+WORKFLOW_TIMEOUT = 300
+
+
+def register(sub):
+    d = sub.add_parser("db", help=tr("databases: add, list, remove", "база данных: добавить, список, удалить"),
+                       description=tr("App databases. add deploys a database in the app's project and passes the "
+                                      "app a variable that points to it (for postgres, DATABASE_URL). "
+                                      "small destroy deletes databases together with the app.",
+                                      "Базы данных приложения. add разворачивает базу в проекте приложения и передаёт "
+                                      "приложению переменную со ссылкой на неё (для postgres — DATABASE_URL). "
+                                      "small destroy удаляет базы вместе с приложением."))
+    d.add_argument("-C", "--path", default=".", help=tr("app folder (default: current folder)",
+                                                        "папка приложения (по умолчанию текущая)"))
+    d.set_defaults(func=cmd_db_list)
+    db_sub = d.add_subparsers(dest="db_command", metavar="<list|add|remove>")
+    dl = db_sub.add_parser("list", help=tr("app databases", "базы приложения"))
+    dl.set_defaults(func=cmd_db_list)
+    da = db_sub.add_parser("add", help=tr("add a database: small db add postgres",
+                                          "добавить базу: small db add postgres"))
+    da.add_argument("kind", choices=sorted(DATABASES))
+    add_no_deploy(da)
+    da.set_defaults(func=cmd_db_add)
+    dr = db_sub.add_parser("remove", help=tr("delete a database with all its data: small db remove postgres",
+                                             "удалить базу вместе с данными: small db remove postgres"))
+    dr.add_argument("kind", choices=sorted(DATABASES))
+    dr.add_argument("--yes", action="store_true", help=tr("don't ask for confirmation (for scripts)",
+                                                          "не спрашивать подтверждение (для скриптов)"))
+    add_no_deploy(dr)
+    dr.set_defaults(func=cmd_db_remove)
+    for parser in (dl, da, dr):
+        parser.add_argument("-C", "--path", default=argparse.SUPPRESS, help=tr("app folder", "папка приложения"))
+
+
+def cmd_db_list(args):
+    root = app_dir(args.path)
+    state = linked_state(root)
+    databases = state.get("databases", [])
+    if not databases:
+        say(tr("No databases. Add one: small db add postgres", "Баз данных нет. Добавить: small db add postgres"))
+        return 0
+    api = Railway(require_token())
+    for db in databases:
+        try:
+            deployment = api.instance_status(db["serviceId"], state["environmentId"])["deployment"]
+            status = deployment["status"] if deployment else tr("no deploys", "нет деплоев")
+        except (RailwayError, KeyError, TypeError) as e:  # базу могли удалить в дашборде Railway
+            status = tr("unavailable: %s", "недоступна: %s") % e
+        print("%-10s %-20s %s" % (db["type"], db["name"], status))
+    return 0
+
+
+def cmd_db_add(args):
+    root = app_dir(args.path)
+    state = linked_state(root)
+    if any(db["type"] == args.kind for db in state.get("databases", [])):
+        raise CliError(tr("%s is already added. List: small db list", "%s уже подключена. Список: small db list")
+                       % args.kind)
+    template_code, app_var, db_var = DATABASES[args.kind]
+    api = Railway(require_token())
+    project, env = state["projectId"], state["environmentId"]
+
+    before = {s["id"] for s in api.project_services(project)[1]}
+    template = api.template(template_code)
+    config = template["serializedConfig"]
+    for service in config.get("services", {}).values():  # как `railway add`: значения по умолчанию шаблона
+        for variable in (service.get("variables") or {}).values():
+            if variable and variable.get("defaultValue"):
+                variable["value"] = variable["defaultValue"]
+    say(tr("Deploying %s in project %s…", "Разворачиваю %s в проекте %s…")
+        % (template["name"], state.get("name", project)))
+    workflow = api.deploy_template(project, env, template["id"], config)
+    if workflow:
+        wait_workflow(api, workflow)
+
+    created = [s for s in api.project_services(project)[1] if s["id"] not in before]
+    if len(created) != 1:
+        raise CliError(tr("expected one new database service, got: %s",
+                          "ожидался один новый сервис базы, появилось: %s")
+                       % (", ".join(s["name"] for s in created) or "0"))
+    service = created[0]
+    state.setdefault("databases", []).append({"type": args.kind, "serviceId": service["id"], "name": service["name"]})
+    save_state(root / STATE_FILE, state)  # сразу: даже если дальше что-то упадёт, destroy удалит и базу
+
+    reference = "${{%s.%s}}" % (service["name"], db_var)
+    linked = change_env(root, {app_var: reference}, deploy=not args.no_deploy)
+    report_env_change(linked, not args.no_deploy, tr("Database %s (%s) added, %s = %s",
+                                                     "База %s (%s) добавлена, %s = %s")
+                      % (args.kind, service["name"], app_var, reference))
+    say(tr("The database takes about a minute to start; if the app connects to it on startup, "
+           "the first start may happen before it is ready.",
+           "База запускается около минуты; если приложение подключается к ней при старте, "
+           "первый запуск может не застать её."))
+    return 0
+
+
+def wait_workflow(api, workflow_id):
+    deadline = time.monotonic() + WORKFLOW_TIMEOUT
+    while True:
+        result = api.workflow_status(workflow_id)
+        if result["status"] == "Complete":
+            return
+        if result["status"] in ("Error", "NotFound"):
+            raise CliError(tr("Railway could not deploy the database: %s", "Railway не смог развернуть базу: %s")
+                           % (result.get("error") or result["status"]))
+        if time.monotonic() > deadline:
+            raise CliError(tr("the database was not deployed within %d s; check the project in the Railway dashboard",
+                              "база не развернулась за %d с; проверьте проект в дашборде Railway") % WORKFLOW_TIMEOUT)
+        time.sleep(2)
+
+
+def cmd_db_remove(args):
+    root = app_dir(args.path)
+    state = linked_state(root)
+    db = next((d for d in state.get("databases", []) if d["type"] == args.kind), None)
+    if db is None:
+        raise CliError(tr("%s is not added. List: small db list", "%s не подключена. Список: small db list")
+                       % args.kind)
+    say(tr("This will delete the %s database (%s) with all its data.",
+           "Будет удалена база %s (%s) вместе со всеми данными.") % (args.kind, db["name"]))
+    if not args.yes:
+        answer = ask(tr("Type %s to confirm: ", "Введите %s для подтверждения: ") % db["name"])
+        if answer is None:
+            raise CliError(tr("confirm the deletion with --yes. Nothing was deleted",
+                              "подтвердите удаление флагом --yes. Ничего не удалено"))
+        if answer != db["name"]:
+            raise CliError(tr("the name did not match. Nothing was deleted", "имя не совпало. Ничего не удалено"))
+    api = Railway(require_token())
+    api.delete_service(db["serviceId"])
+    state["databases"] = [d for d in state["databases"] if d is not db]
+    save_state(root / STATE_FILE, state)
+    linked = change_env(root, unset=[DATABASES[args.kind][1]], deploy=not args.no_deploy)
+    report_env_change(linked, not args.no_deploy, tr("Database %s deleted, %s removed", "База %s удалена, %s убрана")
+                      % (args.kind, DATABASES[args.kind][1]))
+    return 0

small_cli/commands/deploy.py

@@ -0,0 +1,248 @@
+"""small deploy: упаковать код -> найти проект по имени или создать его (projectCreate + serviceCreate)
+-> serviceDomainCreate -> записать переменные из small.json (variableCollectionUpsert) -> загрузить архив
+(POST .../up) -> опрашивать deployment(id).status -> напечатать https://<домен>.
+
+Прогресс пишется в stderr, итоговый URL — в stdout, поэтому `URL=$(small deploy)` работает.
+"""
+
+import argparse
+import os
+import time
+
+from ..archive import collect_files, make_tarball
+from ..common import CliError, app_dir, format_elapsed, human_size, require_token, say, slugify
+from ..config import CONFIG_FILE, STATE_FILE, load_config, load_state, save_state
+from ..i18n import lang, tr
+from ..railway import Railway, RailwayError
+
+OK_STATUSES = {"SUCCESS", "SLEEPING"}
+FAILED_STATUSES = {"FAILED", "CRASHED", "REMOVED", "REMOVING", "SKIPPED", "NEEDS_APPROVAL"}
+MAX_POLL_ERRORS = 5
+
+
+def register(sub):
+    d = sub.add_parser("deploy", help=tr("deploy a code folder and print its public URL",
+                                         "задеплоить папку с кодом и вывести публичный URL"),
+                       description=tr("Deploy a code folder to Railway and print its public URL. "
+                                      "The token is read from RAILWAY_API_TOKEN.",
+                                      "Задеплоить папку с кодом в Railway и вывести публичный URL. "
+                                      "Токен берётся из RAILWAY_API_TOKEN."))
+    d.add_argument("path", nargs="?", default=".",
+                   help=tr("code folder (default: current folder)", "папка с кодом (по умолчанию текущая)"))
+    d.add_argument("--name", help=tr("project and service name (default: name from small.json, "
+                                     "otherwise the folder name)",
+                                     "имя проекта и сервиса (по умолчанию — name из small.json, иначе имя папки)"))
+    d.add_argument("--workspace", help=tr("workspace ID if you have several (or the RAILWAY_WORKSPACE_ID variable)",
+                                          "ID workspace, если их несколько (или переменная RAILWAY_WORKSPACE_ID)"))
+    d.add_argument("--port", type=int, help=tr("port the app listens on (by default Railway uses $PORT)",
+                                               "порт, который слушает приложение (по умолчанию Railway берёт $PORT)"))
+    d.add_argument("-m", "--message", help=tr("deploy message", "подпись деплоя"))
+    d.add_argument("--new", action="store_true",
+                   help=tr("create a new project even if %s exists", "создать новый проект, даже если есть %s")
+                   % STATE_FILE)
+    d.add_argument("--no-wait", action="store_true",
+                   help=tr("do not wait for the build to finish", "не ждать окончания сборки"))
+    d.add_argument("--timeout", type=int, default=900,
+                   help=tr("how many seconds to wait for the build (default: 900)",
+                           "сколько секунд ждать сборку (по умолчанию 900)"))
+    d.add_argument("--interval", type=float, default=3.0, help=argparse.SUPPRESS)
+    d.set_defaults(func=cmd_deploy)
+
+
+def cmd_deploy(args):
+    token = require_token()
+    root = app_dir(args.path)
+
+    config = load_config(root / CONFIG_FILE)
+    state_path = root / STATE_FILE
+    state = {} if args.new else load_state(state_path)
+    reused = bool(state.get("serviceId"))
+    explicit_name = args.name or config["name"]
+    name = slugify(explicit_name or root.name)
+
+    files = collect_files(str(root), skip_root_files=(CONFIG_FILE, STATE_FILE))
+    if not files:
+        raise CliError(tr("nothing to deploy in %s (everything filtered out by .gitignore/.railwayignore?)",
+                          "в %s нечего деплоить (всё отфильтровано .gitignore/.railwayignore?)") % root)
+    tarball = make_tarball(str(root), files)
+    say(tr("Packed %d file (%s)" if len(files) == 1 else "Packed %d files (%s)", "Упаковано файлов: %d (%s)")
+        % (len(files), human_size(len(tarball))))
+
+    api = Railway(token)
+    if reused:
+        say(tr("Project %s from %s", "Проект %s из %s") % (state["name"], STATE_FILE))
+        if explicit_name and name != state["name"]:
+            say(tr("  Name %s not applied: the folder is already linked to %s. To link it to %s, delete %s.",
+                   "  Имя %s не применено: папка уже привязана к %s. Чтобы привязать её к %s, удалите %s.")
+                % (name, state["name"], name, STATE_FILE))
+    else:
+        workspace_id = args.workspace or os.environ.get("RAILWAY_WORKSPACE_ID") or pick_workspace(api)
+        # Явно заданное имя (small.json или --name) идентифицирует сервис: если проект уже есть
+        # в Railway (например, деплой с другого компьютера), подключаемся к нему, а не создаём дубликат.
+        state = bind_existing(api, name, workspace_id) if explicit_name and not args.new else None
+        if state:
+            say(tr("Found project %s in Railway, linked the folder to it",
+                   "Найден проект %s в Railway, папка привязана к нему") % name)
+        else:
+            project_id, environment_id = api.create_project(name, workspace_id)
+            say(tr("Created project %s", "Создан проект %s") % name)
+            service_id = api.create_service(project_id, environment_id, name)
+            say(tr("Created service %s", "Создан сервис %s") % name)
+            state = {"name": name, "projectId": project_id,
+                     "environmentId": environment_id, "serviceId": service_id}
+        # Сохраняем сразу: если сборка упадёт, повторный запуск не наплодит новых проектов.
+        save_state(state_path, state)
+
+    if not state.get("domain"):
+        # Домен — до загрузки кода: его адрес нужен уже первой сборке (ссылки в письмах для входа по почте).
+        state["domain"] = ensure_domain(api, state, args.port)
+        save_state(state_path, state)
+        say(tr("Public domain: %s", "Публичный домен: %s") % state["domain"])
+
+    variables = dict(config["env"])
+    if variables.get("ACCESS_EMAILS") and "PUBLIC_URL" not in variables:
+        # После переименования домена Railway оставляет в RAILWAY_PUBLIC_DOMAIN прежний адрес — ссылки для входа
+        # вели бы на 404. Поэтому настоящий адрес передаём сами (только в Railway: домен может смениться).
+        variables["PUBLIC_URL"] = "https://" + state["domain"]
+    if variables and "OWNER_LANG" not in variables:
+        variables["OWNER_LANG"] = lang()  # строки лога и уведомления в Telegram — на языке владельца
+    if variables:
+        # До загрузки кода, чтобы новая сборка сразу получила переменные. Значения не печатаем.
+        api.upsert_variables(state["projectId"], state["environmentId"], state["serviceId"], variables)
+        say(tr("Variables from %s: %s%s", "Переменные из %s: %s%s")
+            % (CONFIG_FILE, ", ".join(sorted(config["env"])),
+               tr(" (+ PUBLIC_URL for sign-in emails)", " (+ PUBLIC_URL для писем входа)")
+               if "PUBLIC_URL" not in config["env"] and "PUBLIC_URL" in variables else ""))
+
+    try:
+        up = api.upload(state["projectId"], state["environmentId"], state["serviceId"], tarball, args.message)
+    except RailwayError as e:
+        if reused:
+            raise RailwayError(tr("%s\nIf the project was deleted in Railway, run `small deploy --new`.",
+                                  "%s\nЕсли проект удалён в Railway, запустите `small deploy --new`.") % e) from None
+        raise
+    deployment_id = up["deploymentId"]
+    say(tr("Code uploaded, deploy %s", "Код загружен, деплой %s") % deployment_id)
+    if up.get("logsUrl"):
+        say(tr("Logs: %s", "Логи: %s") % up["logsUrl"].rstrip("&"))
+
+    url = "https://" + state["domain"]
+
+    if args.no_wait:
+        print(url)
+        return 0
+
+    status = wait_for_deployment(api, deployment_id, args.timeout, args.interval)
+    if status not in OK_STATUSES:
+        show_logs(api, deployment_id, build=(status == "FAILED"))
+        raise CliError(tr("deploy finished with status %s", "деплой завершился со статусом %s") % status)
+    say(tr("Done!", "Готово!"))
+    print(url)
+    return 0
+
+
+def pick_workspace(api):
+    try:
+        workspaces = api.workspaces()
+    except RailwayError:
+        return None  # токен workspace: `me` ему недоступен, проект создастся в его же workspace
+    if len(workspaces) <= 1:
+        return workspaces[0]["id"] if workspaces else None
+    listing = "\n".join("  %s  %s" % (w["id"], w["name"]) for w in workspaces)
+    raise CliError(tr("the account has several workspaces — pick one: small deploy --workspace <id>\n",
+                      "у аккаунта несколько workspace — укажите нужный: small deploy --workspace <id>\n") + listing)
+
+
+def bind_existing(api, name, workspace_id):
+    """Ищет в Railway проект с именем name и возвращает state для привязки к нему, либо None."""
+    try:
+        projects = api.find_projects(name, workspace_id)
+    except RailwayError as e:
+        say(tr("Could not check whether project %s exists in Railway (%s), creating a new one",
+               "Не удалось проверить, есть ли проект %s в Railway (%s), создаю новый") % (name, e))
+        return None
+    if not projects:
+        return None
+    if len(projects) > 1:
+        raise CliError(tr("Railway has several projects named %s (%s). Delete the extra ones or choose another name.",
+                          "в Railway несколько проектов с именем %s (%s). Удалите лишние или задайте другое имя.")
+                       % (name, ", ".join(p["id"] for p in projects)))
+    project = projects[0]
+    if not project["environments"]:
+        raise CliError(tr("project %s in Railway has no environments", "у проекта %s в Railway нет окружений") % name)
+    env = next((e for e in project["environments"] if e["name"] == "production"), project["environments"][0])
+    services = project["services"]
+    service = next((s for s in services if s["name"] == name), services[0] if len(services) == 1 else None)
+    if service is None and services:
+        raise CliError(tr("project %s has several services (%s), none of them is named %s",
+                          "в проекте %s несколько сервисов (%s), ни один не называется %s")
+                       % (name, ", ".join(s["name"] for s in services), name))
+    state = {"name": name, "projectId": project["id"], "environmentId": env["id"]}
+    if service is None:
+        state["serviceId"] = api.create_service(project["id"], env["id"], name)
+        say(tr("Created service %s", "Создан сервис %s") % name)
+        return state
+    state["serviceId"] = service["id"]
+    domains = api.service_domains(project["id"], env["id"], service["id"])
+    if domains:
+        state["domain"] = domains[0]["domain"]
+    return state
+
+
+def ensure_domain(api, state, port):
+    """Создаёт домен *.up.railway.app и пытается переименовать его в <name>.up.railway.app."""
+    sid, eid = state["serviceId"], state["environmentId"]
+    domain_id, domain = api.create_domain(sid, eid, port)
+    wanted = state["name"] + ".up.railway.app"
+    if domain == wanted:
+        return domain
+    try:
+        if not api.domain_available(wanted):
+            return domain
+        api.rename_domain(domain_id, sid, eid, wanted, port)
+    except RailwayError as e:
+        say(tr("Could not claim %s (%s), keeping %s", "Не удалось занять %s (%s), оставляю %s") % (wanted, e, domain))
+        return domain
+    try:
+        return api.service_domain(state["projectId"], eid, sid, domain_id) or wanted
+    except RailwayError:
+        return wanted
+
+
+def wait_for_deployment(api, deployment_id, timeout, interval):
+    started = time.monotonic()
+    last, errors = None, 0
+    while True:
+        try:
+            status = api.deployment_status(deployment_id)
+            errors = 0
+        except RailwayError as e:
+            errors += 1
+            if errors >= MAX_POLL_ERRORS:
+                raise
+            say(tr("  retrying status request: %s", "  повторяю запрос статуса: %s") % e)
+            status = last
+        elapsed = time.monotonic() - started
+        if status != last:
+            say("[%s] %s" % (format_elapsed(elapsed), status))
+            last = status
+        if status in OK_STATUSES or status in FAILED_STATUSES:
+            return status
+        if elapsed > timeout:
+            raise CliError(tr("build did not finish in %d s (status %s); it keeps running in Railway",
+                              "сборка не завершилась за %d с (статус %s); она продолжается в Railway")
+                           % (timeout, status))
+        time.sleep(interval)
+
+
+def show_logs(api, deployment_id, build):
+    try:
+        lines = api.logs(deployment_id, build=build)
+    except RailwayError as e:
+        say(tr("Could not fetch logs: %s", "Не удалось получить логи: %s") % e)
+        return
+    if lines:
+        say(tr("Last lines of the %s:", "Последние строки %s:")
+            % (tr("build log", "лога сборки") if build else tr("app log", "лога приложения")))
+        for line in lines:
+            say("  " + line)

small_cli/commands/destroy.py

@@ -0,0 +1,63 @@
+"""small destroy: удалить приложение из Railway — проект целиком, если в нём только сервисы этого приложения
+(сам сервис и его базы данных), иначе только их. Затем удаляется .small.json; small.json остаётся."""
+
+from ..common import CliError, app_dir, ask, linked_state, require_token, say
+from ..config import CONFIG_FILE, STATE_FILE
+from ..i18n import tr
+from ..railway import Railway, RailwayError
+
+
+def register(sub):
+    x = sub.add_parser("destroy", help=tr("delete the app from Railway", "удалить приложение из Railway"),
+                       description=tr("Delete the app from Railway: the whole project if it only has this app's "
+                                      "services (the service itself and its databases), otherwise just those. "
+                                      "Then %s is deleted; %s stays.",
+                                      "Удалить приложение из Railway: проект целиком, если в нём только сервисы этого "
+                                      "приложения (сам сервис и его базы данных), иначе только их. Затем удаляется %s; "
+                                      "%s остаётся.") % (STATE_FILE, CONFIG_FILE))
+    x.add_argument("path", nargs="?", default=".", help=tr("app folder (default: current folder)",
+                                                           "папка приложения (по умолчанию текущая)"))
+    x.add_argument("--yes", action="store_true", help=tr("don't ask for confirmation (for scripts)",
+                                                         "не спрашивать подтверждение (для скриптов)"))
+    x.set_defaults(func=cmd_destroy)
+
+
+def cmd_destroy(args):
+    root = app_dir(args.path)
+    state = linked_state(root)
+    api = Railway(require_token())
+    try:
+        project_name, services = api.project_services(state["projectId"])
+    except RailwayError as e:
+        raise CliError(tr("project %s not found in Railway (%s). If it is already deleted, delete %s manually",
+                          "проект %s не найден в Railway (%s). Если он уже удалён, удалите %s вручную")
+                       % (state["projectId"], e, root / STATE_FILE)) from None
+    own_ids = {state["serviceId"]} | {db["serviceId"] for db in state.get("databases", [])}
+    own = [s for s in services if s["id"] in own_ids]
+    others = [s["name"] for s in services if s["id"] not in own_ids]
+    if others:
+        say(tr("This will delete services %s from project %s. Other services in the project stay: %s",
+               "Будут удалены сервисы %s из проекта %s. Другие сервисы проекта останутся: %s")
+            % (", ".join(s["name"] for s in own) or state.get("name", ""), project_name, ", ".join(others)))
+    else:
+        say(tr("This will delete the whole project %s: %s, domain %s, variables and all deploys.",
+               "Будет удалён проект %s целиком: %s, домен %s, переменные и все деплои.")
+            % (project_name, ", ".join(s["name"] for s in own) or tr("service", "сервис"), state.get("domain") or "—"))
+    if not args.yes:
+        answer = ask(tr("Type the project name (%s) to confirm: ", "Введите имя проекта (%s) для подтверждения: ")
+                     % project_name)
+        if answer is None:
+            raise CliError(tr("confirm the deletion with --yes. Nothing was deleted",
+                              "подтвердите удаление флагом --yes. Ничего не удалено"))
+        if answer != project_name:
+            raise CliError(tr("the name did not match. Nothing was deleted", "имя не совпало. Ничего не удалено"))
+
+    if others:
+        for service in own:
+            api.delete_service(service["id"])
+    else:
+        api.delete_project(state["projectId"])
+    (root / STATE_FILE).unlink()
+    say(tr("Deleted. %s removed, %s kept: the next small deploy creates a new project.",
+           "Удалено. %s удалён, %s оставлен: следующий small deploy создаст новый проект.") % (STATE_FILE, CONFIG_FILE))
+    return 0

small_cli/commands/domain.py

@@ -0,0 +1,123 @@
+"""small domain: свой домен вместо *.up.railway.app — Railway выдаёт DNS-записи, их нужно прописать у регистратора."""
+
+import argparse
+import re
+
+from ..common import CliError, app_dir, linked_state, require_token, say
+from ..i18n import tr
+from ..railway import Railway
+
+DOMAIN_RE = re.compile(r"(?=.{1,253}\Z)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}\Z")
+
+
+def register(sub):
+    d = sub.add_parser("domain", help=tr("custom domains: add, list, remove", "свой домен: добавить, список, удалить"),
+                       description=tr("A custom domain for the app. add registers the domain in Railway and prints "
+                                      "the DNS records to set at your registrar; Railway issues the HTTPS "
+                                      "certificate itself once the records work.",
+                                      "Свой домен для приложения. add регистрирует домен в Railway и печатает "
+                                      "DNS-записи, которые нужно прописать у регистратора; HTTPS-сертификат Railway "
+                                      "выпустит сам, когда записи заработают."))
+    d.add_argument("-C", "--path", default=".", help=tr("app folder (default: current folder)",
+                                                        "папка приложения (по умолчанию текущая)"))
+    d.set_defaults(func=cmd_domain_list)
+    domain_sub = d.add_subparsers(dest="domain_command", metavar="<list|add|remove>")
+    dl = domain_sub.add_parser("list", help=tr("app domains and their status", "домены приложения и их состояние"))
+    dl.set_defaults(func=cmd_domain_list)
+    da = domain_sub.add_parser("add", help=tr("add a domain: small domain add app.example.com",
+                                              "добавить домен: small domain add app.example.com"))
+    da.add_argument("domain")
+    da.add_argument("--port", type=int, help=tr("app port, if the app doesn't listen on $PORT",
+                                                "порт приложения, если оно не слушает $PORT"))
+    da.set_defaults(func=cmd_domain_add)
+    dr = domain_sub.add_parser("remove", help=tr("remove a domain: small domain remove app.example.com",
+                                                 "убрать домен: small domain remove app.example.com"))
+    dr.add_argument("domain")
+    dr.set_defaults(func=cmd_domain_remove)
+    for parser in (dl, da, dr):
+        parser.add_argument("-C", "--path", default=argparse.SUPPRESS, help=tr("app folder", "папка приложения"))
+
+
+def normalize(domain):
+    domain = domain.strip().lower().rstrip(".")
+    for prefix in ("https://", "http://"):
+        if domain.startswith(prefix):
+            domain = domain[len(prefix):]
+    domain = domain.split("/")[0]
+    if not DOMAIN_RE.match(domain):
+        raise CliError(tr("%r does not look like a domain (example: app.example.com)",
+                          "%r не похож на домен (пример: app.example.com)") % domain)
+    return domain
+
+
+def ids(state):
+    return state["projectId"], state["environmentId"], state["serviceId"]
+
+
+def cmd_domain_list(args):
+    state = linked_state(app_dir(args.path))
+    domains = Railway(require_token()).custom_domains(*ids(state))
+    say(tr("Railway URL: https://%s", "Адрес Railway: https://%s") % state.get("domain", "—"))
+    if not domains:
+        say(tr("No custom domains. Add one: small domain add app.example.com",
+               "Своих доменов нет. Добавить: small domain add app.example.com"))
+        return 0
+    for item in domains:
+        print("%-40s %s" % (item["domain"], summary(item.get("status") or {})))
+    return 0
+
+
+def cmd_domain_add(args):
+    domain = normalize(args.domain)
+    state = linked_state(app_dir(args.path))
+    api = Railway(require_token())
+    if any(item["domain"] == domain for item in api.custom_domains(*ids(state))):
+        raise CliError(tr("%s is already added. Records: small domain list",
+                          "%s уже добавлен. Записи: small domain list") % domain)
+    created = api.create_custom_domain(*ids(state), domain, args.port)
+    say(tr("Domain %s added. Set these DNS records at your registrar:",
+           "Домен %s добавлен. Пропишите у регистратора DNS-записи:") % domain)
+    print_records(created.get("status") or {})
+    say(tr("Once the records work (from a few minutes to a day), Railway issues the HTTPS certificate itself.",
+           "Когда записи заработают (от минут до суток), Railway сам выпустит HTTPS-сертификат."))
+    say(tr("Check: small domain list · the invite link will also work at https://%s/?token=…",
+           "Проверить: small domain list · ссылка-приглашение будет работать и на https://%s/?token=…") % domain)
+    return 0
+
+
+def cmd_domain_remove(args):
+    domain = normalize(args.domain)
+    state = linked_state(app_dir(args.path))
+    api = Railway(require_token())
+    item = next((d for d in api.custom_domains(*ids(state)) if d["domain"] == domain), None)
+    if item is None:
+        raise CliError(tr("%s is not one of the app's domains. List: small domain list",
+                          "%s не найден среди доменов приложения. Список: small domain list") % domain)
+    api.delete_custom_domain(item["id"])
+    say(tr("Domain %s removed from Railway. You can delete its DNS records at your registrar.",
+           "Домен %s убран из Railway. DNS-записи у регистратора можно удалить.") % domain)
+    return 0
+
+
+def print_records(status):
+    rows = [(r["recordType"].replace("DNS_RECORD_TYPE_", ""), r.get("fqdn") or r.get("hostlabel") or "@",
+             r["requiredValue"]) for r in status.get("dnsRecords") or []]
+    if status.get("verificationToken") and not status.get("verified"):
+        rows.append(("TXT", status.get("verificationDnsHost") or "", status["verificationToken"]))
+    if not rows:
+        say(tr("  Railway returned no records; check later: small domain list",
+               "  Railway не вернул записи — посмотрите позже: small domain list"))
+    for kind, name, value in rows:
+        print("  %-6s %-40s %s" % (kind, name, value))
+
+
+def summary(status):
+    records = status.get("dnsRecords") or []
+    dns_ok = bool(records) and all("PROPAGATED" in (r.get("status") or "") for r in records)
+    cert = (status.get("certificateStatus") or "").replace("CERTIFICATE_STATUS_TYPE_", "").lower()
+    parts = [tr("DNS configured", "DNS настроен") if dns_ok else tr("waiting for DNS records", "ждёт DNS-записей")]
+    if cert:
+        parts.append(tr("certificate: %s", "сертификат: %s") % cert)
+    if status.get("verificationToken") and not status.get("verified"):
+        parts.append(tr("TXT verification needed", "нужна TXT-проверка"))
+    return ", ".join(parts)