Reserve Name Specification
==========================

Signature:

    NetDB_Name.reserve (
                         p_op_uid  int,       -- user reserving name
                         p_name    varchar,   -- name (unqualified) to reserve
                         p_domain  varchar,   -- domain part of the name
                         p_type    varchar    -- address alias domain interface mx network node txt
                       )
        returns (new name id, reservation timestamp)

Implementation:

    -- ORDER of TESTS MATTERS!!!

    -- validate type parameter and convert it to a NetDB DNS label
    case p_type in ("address","interface", "node", "network") dns_label = "A"
                 =  "mx"                                      dns_label = "MX"
                 =  "alias"                                   dns_label = "CNAME"
                 =  "domain"                                  dns_label = "SOA"
                 =  "text"                                    dns_label = "TXT"
                 otherwise error

    -- make sure the name is composed of valid characters and is not too long
    if (not DNS.check_name(p_name,p_type)) error

    -- make sure the domain exists
    NetDB_Domain.verify_or_die(p_domain_id);

    -- disallow adding top-level names/domains, i.e., names with parent domain '.'
    if (p_domain_id == 1) error

    -- if the new name doesn't match an existing domain name, make
    --   sure the user has rights to assign names in the name's domain
    if ((p_name,p_domain_id,dns_type="SOA") does not exist and
        not NetDB_Domain.can_use (p_op_uid, p_domain_id)) error

    -- make sure the name is not globally reserved (restricted)
    if (NetDB_ResName.reserved(p_op_uid,p_name,p_domain_id)) error

    -- if the domain is limited, make sure the name is allowed
    if (CheckForLimitedDomain from GlobalDefault is set and
        p_domain_id is flagged 'limited' and
        p_name is not in the LimitedNames table) error

    -- nuke expired name reservations so they don't get in the way
    delete from Name
     where reserved is not null  -- very important/necessary for speed!
       and Util.datediff('seconds',reserved) > GlobalDefault.LockTimeOut

    -- if the new name matches an existing domain name, see if the
    --   user can use that domain name as other name types
    if ((p_name,p_domain_id,dns_type="SOA") exists and
        not NetDB_Domain.can_use_as_name (p_op_uid, p_domain_id)) error

    -- if the user already has this name reserved, refresh the reservation and return it
    if ((p_name,p_domain_id,reserved_by=p_op_uid,reserved!=null) exists) or
        update row, refreshing the reservation and return the new reservation

    -- make sure the name doesn't already exist, unless it's an MX
    if ((p_name,p_domain_id,dns_label) exists and dns_label != "mx")
        -- if the name is reserved, say who reserved it and for how long
        if   (v_reserved_by is not null) error - name is reserved by <netid> until <time>
        else                             error - name exists with type <type>

    -- alias names cannot coexist with other types [DNS rule]
    --   note that non-delegated domains don't have DNS records,
    --   so alias names *can* exist with non-delegated domains.
    if ((p_name,p_domain_id) exists with dns_label "CNAME" and
        (the dns_label of the new name is not "SOA")) error
    if ((p_name,p_domain_id) exists as anything but a non-delegated domain and
        (the dns_label of the new name is "CNAME")) error

    -- if a name is of type (A, MX, TXT) and the name already exists as one or more of
    -- those types, allow it to be reserved if the user has access to any of the entries
    -- with the name.

    -- if the new name is an "A" name and the name already exists as an MX or TXT record
    --     if the user has access to any record associated with the MX received_by names
    --       or the TXT record
    --         ok
    --     else
    --         error
    --
    if name is of type A
        if NetDB_Owner.check_access (p_op_uid, existing_mx_id, 'MX') or
           NetDB_Owner.check_access (p_op_uid, existing_txt_id, 'TXT')
            ok
        else
            NetDB_Owner.has_access_or_die (p_op_uid, existing_id, existing_type);

    -- given the way check_access(...,'MX') works, checking for access to any "A" name
    -- and any MX received_by names, the checks above and below are the same, and could
    -- be combined. but there may be more name types in the future, with different
    -- conditions, so we're keeping them separate.

    -- else if the name is an MX and the name exists as an "A" name, MX, or TXT record
    --     if the user has access to an existing record with the "A" name or to any
    --       record associated with the MX received_by names or the TXT record
    --         ok
    --     else
    --         error
    --
    elsif name is of type MX
        if NetDB_Owner.check_access (p_op_uid, existing_A_or_MX_name_id, 'MX') or
           NetDB_Owner.check_access (p_op_uid, existing_mx_id, 'TXT')
            ok
        else
            NetDB_Owner.has_access_or_die (p_op_uid, existing_id, existing_type);

    -- else if the name is a TXT record and the name exists as an "A" name or MX
    --     if the user has access to the existing record with the "A" name or to
    --       any record associated with the MX received_by names
    --         ok
    --     else
    --         error
    --
    elsif name is of type TXT
        if NetDB_Owner.has_access_or_die (p_op_uid, existing_A_or_MX_name_id, 'MX')
            ok
        else
            NetDB_Owner.has_access_or_die (p_op_uid, existing_id, existing_type);

    -- reserve the name by inserting it with the reservation (user,timestamp)
    -- unless the DNS type is "mx" and that name already exists
    insert (p_name,p_domain_id,dns_type) into the name table
      with the reserved_by and reserved columns set to the p_op_uid and "now"
     where not exists (p_name,p_domain_id,dns_type="mx")