@0xed0c02f41fea6b5a;

interface L10NString {
    # Any string type that is intended to be displayed to an user that is more
    # than an identifier to be used as-is must be able to be localized into the
    # users preferred language. This includes description, help messages, etc.
    # but of course does not extend to usernames.
    # TODO: Potentially make generic over the localized content (e.g. dates)?
    # Can be done after the fact without braking protocol, so no big issue.

    get @0 ( lang :Text ) -> ( lang :Text, content :Text );
    # Retrieve the string in the given locale. The input parameter MUST be a
    # RFC5646-formatted locale identifier (e.g: "en-US", "de-DE", "az-Arab-IR").
    # 
    # If a server can't find a localized version matching exactly it MUST try to
    # substitute it.  Substitution MUST always return more specific matches for
    # general queries.  e.g. if "it" is requested and the server has "it-CH"
    # available it returns this string.
    # 
    # Substitution SHOULD NOT cross language barriers, e.g. returning "en-GB"
    # for a string requested in "cy-GB". Substitution MUST NOT return a
    # localization in a different language unless server has a priori knowledge
    # that the user can read and understand said language.
    #
    # Substitution SHOULD prefer unspecified subtags over wrong subtags. If
    # "es-AR" is requested and a server has "es", and "es-VE" available, "es"
    # should be selected.
    # 
    # A server MUST set the output `lang` field to the exact tag that the
    # content it sends was written in and `content` to the localized string.
    # e.g. If a string is requested for "sr" and the server has found a string
    # that was configured as "sr-Cyrl-BA" the server sets lang to "sr-Cyrl-BA".
    #
    # If a server can't find a suitable substitute it MUST set the output
    # `content` to a NULL pointer and set the output `lang` to the input `lang`
    # it was passed.
    # If a server can't parse a given `lang` tag it MUST set the output `lang`
    # to NULL.

    available @1 () -> ( langs :List(Text) );
    # Returns the list of locales this content is available in.
}

struct UUID {
    # UUID type used to identify machines.
    #
    # Consider using this algorithm for assembling the 128-bit integer:
    # (assuming ISO9899:2018 shifting & casting rules)
    #   uint128_t num = (upper << 64) + lower;
    # And then respectively this code for deconstructing it:
    #   uint64_t lower = (uint64_t) num;
    #   uint64_t upper = (uint64_t) (num >> 64);

    lower @0 :UInt64;
    # lower 8 bytes of the uuid, containing the LSB.

    upper @1 :UInt64;
    # upper 8 bytes of the uuid, containing the MSB.
}

using OID = Data;
# An OID is encoded as a sequence of varints. In this encoding the lower 7 bits
# of each octet contain data bits while the MSB indicates if the *following*
# octet is still part of this edge.  It is the same encoding UTF-8 uses. To
# decode you simply collect octets until you find an octet <128 and then concat
# the data bits of all the octets you've accumulated, including the current one.
# This gives you the value of one node. Continue until you've exhausted the
# available data.  This is a rather efficient encoding since almost all edges of
# the OID tree are smaller than 128 and thus encode into one byte.
# X.208 does *not* limit the size of nodes! However, a reasonable size limit is
# 128 bit per node, which is the size of the UUID nodes in the `2.25` subtree.