@0xed0c02f41fea6b5a;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

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, following ITU-T Rec. X.690 Section 8.19.
# Consider that X.208 does *not* limit the size of arc identifiers! However, a
# reasonable size limit is 128 bit per arc, which is the size of the UUID nodes
# in the `2.25` subtree.

struct Map(Key, Value) {
    # Generic Key-Value-Map

    entries @0 :List(Entry);
    struct Entry {
        key @0 :Key;
        value @1 :Value;
    }
}

struct Fallible(Ok, Error) {
    union {
        ok @0 :Ok;
        err :group {
            error @1 :Error;
            description @2 :L10NString;
            # May be NULL if `Error` is :Void
        }
    }
}

struct Duration {
    seconds @0 :UInt64;
    nanoseconds @1 :UInt64;
}

struct Timestamp {
    # An UNIX timestamp in the UTC timezone
    seconds @0 :Int64;
    nanoseconds @1 :UInt64;
}

using SturdyRef = Data;

struct When {
    start @0 :Timestamp;
    end @1 :Timestamp;
}

struct TreeNode(Value) {
    value @0 :Value;
    children @1 :List(TreeNode(Value));
}