Požadavek test-smtp

Účel a dopady

Otestuje dostupnost a vlastnosti daného SMTP serveru (dosažitelný port, doporučená metoda přihlášení, šifrování) a volitelně ověří, zda se jím zadaným uživatelským jménem/heslem (nebo OAuth profilem) lze k tomuto serveru přihlásit. Požadavek nic nezapisuje do databáze ani session – jde o čistě diagnostický síťový test (naváže reálné spojení k testovanému serveru).

Dostupnost, kontext, oprávnění apod.

• Dostupné každému přihlášenému uživateli; nevyžaduje zvláštní roli ani oprávnění.
• Na rozdíl od většiny mutujících požadavků tento blok netestuje transactional/odvolání transakce obálky <request> – účastní se tedy transakčního přeskakování jinak než ostatní požadavky v této revizi.

XML požadavek (syntax + popis)

  <request>
   <test-smtp
    server="{string}"
    config="{string}"
    port="{number}"
    uid="{string}"
    password="{string}"
    verbose="{bool}"
    oauth-profile="{string}"
    oauth-user="{number}"
    oauth-scope="{string}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• server - Adresa serveru - Název SMTP serveru, host-name nebo IP adresa. (typ: string; povinný – bez něj požadavek vždy skončí chybou)
• config - Konfigurační parametry - Použije se jako vynucené nastavení spojení (ENC syntaxe); přesná gramatika zde není dokumentována. (typ: string; nepovinný)
• port - Testovaný port - Cílový port. Chybějící nebo nečíselná hodnota se nahrazuje 0, což znamená vyzkoušet všechny obvyklé porty. (typ: number; nepovinný; výchozí: 0)
• uid - Přihlašovací jméno - Pouhá PŘÍTOMNOST tohoto atributu (i s prázdnou hodnotou) aktivuje test přihlášení; server jej předává jako řetězec, nikoli jako číselné ID uživatele. (typ: string; nepovinný)
• password - Heslo - Použije se společně s uid při testu přihlášení. (typ: string; nepovinný)
• verbose - Detailní odpověď - Řídí, zda odpověď obsahuje potomky step s průběhem testu a zda se diagnostika vůbec sbírá (při verbose jiném než "true" se diagnostický log ani nepředává testovací třídě). (typ: bool; nepovinný; výchozí: false)
• oauth-profile - OAuth profil - Je-li uveden, aktivuje se ověření přes OAuth místo uid/password. Hodnota se nejprve zkusí převést na číslo; pokud se to nezdaří, server se pokusí profil dohledat podle jména. Nepodaří-li se profil rozpoznat žádným způsobem, požadavek skončí chybou. (typ: string; nepovinný)
• oauth-user - OAuth uživatel - Použije se jen je-li uveden oauth-profile. Neplatná nebo chybějící hodnota se nahrazuje ID přihlášeného uživatele. (typ: number; nepovinný; výchozí: ID volajícího uživatele)
• oauth-scope - OAuth scope - Atribut nemá pozorovatelný efekt; místo něj server pro OAuth scope použije hodnotu oauth-user (viz „Zpracování“). (typ: string; nepovinný)

Požadavek nemá žádné potomky.

Závislosti

• Pokud je uveden oauth-profile, řídí ověření tato skupina atributů (oauth-profile/oauth-user/oauth-scope) a atributy uid/password se nepoužijí.
• uid/password mají smysl jen bez oauth-profile.

Příklady požadavku

(Zatím bez ověřeného příkladu.)

Zpracování a vedlejší účinky

• Chybí-li server, požadavek okamžitě skončí chybou bez jakéhokoli síťového pokusu.
• Je-li uveden oauth-profile, ale server se z něj nedokáže odvodit platné ID profilu (ani přímým převodem, ani dohledáním podle jména), požadavek skončí chybou dříve, než dojde na samotný síťový test.
• Jinak server naváže reálné spojení k server:port a provede detekci vlastností SMTP serveru; je-li uveden uid, pokusí se jím i přihlásit.
• Pozorované chování: jako OAuth scope se použije hodnota oauth-user, ne oauth-scope; atribut oauth-scope proto nemá pozorovatelný efekt. Jde o chování serveru, které vypadá jako chyba, a je zde popsáno bez opravy.
• Atribut config odpovědi (viz níže) je vyplněn vždy, ať test skončí úspěchem, nebo ne.
• login-method v odpovědi nabývá jedné z hodnot LOGIN, CRAM-MD5, XOAUTH2, jinak (výchozí) PLAIN. encryption nabývá STARTTLS, SSL, jinak (výchozí) NONE – hodnoty jsou velkými písmeny, ne dle dřívějšího popisu startls/tls/ssl/none.
• Je-li verbose jiné než "true", odpověď je vždy samo-uzavírací bez potomků step.

XML odpověď (syntax + popis)

  <response>
   <test-smtp
    status="ok|error"
    login="true|false"
    config="{string}"
    ip="{string}"
    port="{number}"
    login-method="LOGIN|PLAIN|CRAM-MD5|XOAUTH2"
    encryption="NONE|STARTTLS|SSL"
    detail="{string}"
    >
    <step ... /> *
   </test-smtp>
  </response>

• status - Výsledek - ok při úspěšné detekci/přihlášení, error jinak. (typ: enum; povolené hodnoty: ok, error)
• login - Výsledek přihlášení - Přítomen jen byl-li v požadavku uveden uid (test přihlášení byl vyžádán): true při úspěšném přihlášení, false při neúspěšném. (typ: bool; nepovinný)
• config - Doporučené nastavení - Textový popis zjištěných/doporučených vlastností spojení, vyplněn vždy. (typ: string)
• ip - IP adresa serveru - Zjištěná IP adresa, ve tvaru A.B.C.D. (typ: string)
• port - Použitý port - Skutečně použitý/zjištěný port. (typ: number)
• login-method - Doporučená metoda přihlášení - Viz možné hodnoty výše. (typ: enum)
• encryption - Zjištěné šifrování - Viz možné hodnoty výše. (typ: enum)
• detail - Popis chyby - Přítomen jen u dvou konkrétních chybových stavů popsaných níže (chybějící server, neplatné OAuth parametry); u chyby zjištěné až při samotném síťovém testu detail přítomen není (chyba je vyjádřena jen přes status="error" a případně login="false"). (typ: string; nepovinný)

Potomek step (0 a vícekrát, jen je-li verbose="true" v požadavku): viz sdílená struktura níže.

Uzel step

• number - Číslo zprávy - Interní číslo logovací položky. (typ: number)
• severity - Závažnost - (typ: enum; povolené hodnoty: error, warning, information, success)
• detail - Text - Znění dané diagnostické zprávy. (typ: string)

step je vždy samo-uzavírací element (<step .../>), nikoli otevírací/uzavírací dvojice.

Příklady odpovědi

(Zatím bez ověřeného příkladu.)

Chyby a reakce

• <test-smtp status="error" detail="Nebyl zadan atribut server"/> – chybí povinný atribut server.
• <test-smtp status="error" detail="OAuth parametry nebyly spravne zadany"/> – uveden oauth-profile, ale server z něj nedokázal odvodit platné ID profilu.
• <test-smtp status="error" login="false"? config="…" ip="…" port="…" login-method="…" encryption="…"> (+ <step>* je-li verbose="true") – síťová detekce nebo přihlášení selhaly; login="false" je přítomen jen byl-li vyžádán test přihlášení.
• Výraz pro identifikaci chyb v odpovědi serveru: test-smtp[@status='error'].

Související požadavky

• test-imap – obdobný test pro IMAP server.
• send-email – odeslání e-mailu přes profil, jehož SMTP nastavení lze tímto požadavkem předem otestovat.