Požadavek rand

Účel a dopady

Vygeneruje jedno nebo více kryptograficky náhodných čísel podle zadaného rozsahu/velikosti a vrátí je v odpovědi. Požadavek nemá žádné vedlejší účinky – nic nezapisuje do databáze ani do session.

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

• Dostupné každému přihlášenému uživateli bez zvláštního oprávnění.
• Na rozdíl od požadavků jako sql-query/action není zpracování rand podmíněno stavem obálkové transakce (transactional/avoidTran); požadavek se provede vždy.

XML požadavek (syntax + popis)

  <request>
   <rand
    output="{string}"
    from="{number}"
    to="{number}"
    repeat="{number}"
    unique="{bool}"
    size="{string}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• output - Formát vrácené hodnoty - Určuje, jak je vygenerované číslo zapsáno v odpovědi. (typ: enum; nepovinný; výchozí: plain; povolené hodnoty: base64, hex, plain – jakákoli jiná/neznámá hodnota i chybějící atribut se tiše chová jako plain)
• from - Počátek rozsahu - Dolní mez rozsahu vracených čísel, včetně. (typ: number; nepovinný; výchozí: 0; hodnota, kterou se nepodaří převést na celé číslo, se chová jako neuvedená)
• to - Konec rozsahu - Horní mez rozsahu vracených čísel, včetně. (typ: number; nepovinný; výchozí: 0; hodnota, kterou se nepodaří převést na celé číslo, se chová jako neuvedená)
• repeat - Počet vygenerovaných čísel - Kolikrát se má číslo vygenerovat. (typ: number; nepovinný; výchozí: 1; neplatná hodnota se chová jako neuvedená)
• unique - Vynutit unikátnost - Vygenerovaná čísla se nesmí v rámci jednoho požadavku opakovat. Server porovnává hodnotu s doslovným řetězcem "true" (po převodu na malá písmena). (typ: bool; nepovinný; výchozí: false)
• size - Velikost čísla v bajtech - Alternativa k zadání rozsahu přes from/to. Buď jedno z předdefinovaných slov, nebo číslo bajtů. (typ: string; nepovinný; výchozí: 2 bajty při output="plain"/neuvedeném output, jinak 32 bajtů; povolené hodnoty: short, ushort, int, uint, long, ulong, nebo libovolné celé číslo bajtů)

Požadavek nemá žádné potomky.

Význam předdefinovaných slov u size

Slova jsou napojena na velikosti typů použitého překladu na serveru, nikoli na nativní velikost long/unsigned long v jazyce C na této platformě:

• short → 2 bajty (číslo je interpretováno jako znaménkové)
• ushort → 2 bajty (bez znaménka)
• int → 4 bajty (znaménkové)
• uint → 4 bajty (bez znaménka)
• long → 8 bajtů, tedy stejně jako long long (znaménkové) – ne 4 bajty, jak by odpovídalo nativnímu long na Windows
• ulong → 8 bajtů, tedy stejně jako unsigned long long (bez znaménka)

Je-li size číslo, které se nepodaří rozpoznat jako žádné z výše uvedených slov, převede se přímo na počet bajtů; nepodaří-li se ho převést na číslo, uplatní se výchozí hodnota podle output popsaná výše.

Závislosti a vedlejší chování

• Je-li from větší než to, server je před generováním prohodí.
• Je-li zadán platný rozsah (from různé od to), server tímto rozsahem přepočítá a přepíše efektivní size podle počtu bitů potřebných k zápisu rozsahu – zadání size společně s rozsahem tedy size nepoužije v původní podobě, protože ho rozsah přepíše.
• Přesáhne-li takto určená velikost čísla 8 bajtů a output je (výchozí) plain, server formát potichu přepne na base64, protože desítkový zápis takto velkého čísla by nebyl smysluplný.
• unique="true" bez zadaného rozsahu prakticky vždy skončí chybou. Kontrola kapacity porovnává repeat s to - from, je-li rozsah zadán; bez rozsahu (from rovno to, včetně výchozího stavu bez atributů) vychází kapacita nulová, takže jakýkoli repeat ≥ 1 s unique="true" bez rozsahu vede k chybě Neplatne pouziti atributu unique. Kontrola navíc vyžaduje, aby efektivní velikost čísla byla nejvýše 8 bajtů – proto unique="true" selže i s rozsahem, pokud size/output vede k číslu většímu než 8 bajtů (např. výchozí velikost 32 bajtů pro base64/hex bez explicitního size).
• Je-li požadavek zadán zcela bez atributů, vygeneruje se jedno desítkové číslo o velikosti 2 bajty, tedy z rozsahu <0; 65536).

Příklady požadavku

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

Zpracování a vedlejší účinky

• Pro každé z repeat opakování server vygeneruje náhodné bajty (randomize); je-li zadán rozsah, hodnota se do něj promítne modulem a při unique="true" se opakovaně generuje, dokud není získána dosud nepoužitá hodnota.
• Formát textové reprezentace hodnoty ve <value> odpovídá output: desítkové číslo (se znaménkem, je-li číslo záporné nebo byl použit znaménkový klíč size), base64, nebo hexadecimální zápis.

XML odpověď (syntax + popis)

  <response>
   <rand
    type="ok"
    >
    <value>{string}</value> *
   </rand>
  </response>

Uzel value nemá žádné atributy a obsahuje jen textovou hodnotu vygenerovaného čísla. Počet uzlů value odpovídá repeat.

Příklady odpovědi

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

Chyby a reakce

• <rand status="error" detail="Neplatne pouziti atributu unique"/> – nesplněna podmínka kapacity pro unique="true" popsaná výše.
• Pozor na název atributu chyby: na rozdíl od úspěšné odpovědi, která používá type="ok", chybová odpověď používá status="error" (ne type="error"). Výraz pro identifikaci chyb v odpovědi serveru je tedy rand[@status='error'], ne rand[@type='error'], jak uváděla starší dokumentace.
• Jde o jedinou chybovou větev tohoto požadavku; je vždy sebeuzavírající, bez vnořeného uzlu error.

Související požadavky

• uuid – další generátor hodnot ve stejné skupině požadavků.