api.fabaccess-api/api.capnp

# Copyright © 2020 Gregor Reitzenstein
# Licensed under the MIT License:
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


@0xfd92ce9be2369b8e;

using Rust = import "rust.capnp";
$Rust.parentModule("schema");

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

interface Machines {
    # The interface to the machines subsystem

    listMachines @0 () -> ( machines :List(Machine) );
    # List all machines that BFFH knows about the user has been granted at least read access on

    getMachine @1 ( uuid :UUID ) -> ( machine :Machine, dummy :UInt8 = 0 );
    # Access a particular machine by known UUID. This may fail for two reasons: The user
    # has not been granted access to know the machine exists or the machine does in fact
    # not exist. In both cases the `machine` result will be a NULL-pointer
}

interface Permissions {
}

struct UUID {
    # UUID type used to identify machines.
    # Since the exact value has no meaning the encoding rules are not too relevant, but it is
    # paramount that you are consistent when encoding and decoding this type.
    #
    # Consider using this algorithm for assembling the 128-bit integer:
    # (assuming ISO9899:2018 shifting & casting rules)
    #   uint128_t num = (uuid1 << 64) + uuid0;
    # And then respectively this code for deconstructing it:
    #   uint64_t uuid0 = (uint64_t) num;
    #   uint64_t uuid1 = (uint64_t) (num >> 64);

    uuid0 @0 :UInt64;
    uuid1 @1 :UInt64;
}

enum State {
    free @0;
    inUse @1;
    toCheck @2;
    blocked @3;
    disabled @4;
    reserved @5;
}

struct Machine {
    # A machine struct. This represents a machine as BFFH thinks about it which may mean
    # several machines or just part of a machine in the real world.
    # By itself this struct is completely useless since it contains only the information
    # that the machine exists the user is allowed to know about that fact. For all further
    # information the user has to call the contained capabilities which depending on the
    # access level may not be set. For example an admin will have every capability here
    # set but a simple user may only have `read` and `write` set while some users may not
    # even have `read` set and are unable to even see if the machine is currently in use.
    struct MInfo {
        state @0 :State;
        name @1 :Text;
        description @2 :Text;

        responsible @3 :User; # This field may be NULL if nobody is using the machine
    }
    
    struct PropertyMap {
        properties @0 :List(Property);
        struct Property {
            key @0 :Text;
            value @1 :Text;
        }
    }

    read @0 :Read;
    interface Read $CSharp.name("ReadInterface") {
        info @0 () -> ( minfo :MInfo, dummy :UInt8 = 0 );
        # Check the state of a machine.
        
        getProperties @1 () -> (properties :PropertyMap, dummy :UInt8 = 0 );
        # Read Machine Properties
    }

    write @1 :Write;
    interface Write $CSharp.name("WriteInterface") {
        use @0 () -> ( ret :GiveBack );
        # Try to use a machine. Returns a NULL-ptr if the user does not have the required
        # permissions to use this machine
        interface GiveBack {
            # If you are using a machine you have the capablity to give it back

            ret @0 () -> ();
            # Calling this function will return the machine and set its state as appropiate
        }
        
        reserve @1 () -> ( ret :GiveBack );
        # Try to reserve a machine. returns a NULL-ptr if the user does not have the required
        # permissions to reserve this machine
        
        setProperties @2 (properties :PropertyMap) -> ();
        # Write all Machine Properties
        
        setProperty @3 (property :PropertyMap.Property) -> ();
        # Write ONE Machine Property identified by it's key
    }


    manage @2 :Manage;
    # After a machine has been used by an user with low enough permissions it's
    # in the 'toCheck' state.  This call then allows more priviledged users to
    # "check" the machine and move it to the `free` state.
    interface Manage $CSharp.name("ManageInterface") {
        ok @0 () -> (); # The machine was clean & ok. -> free
        notOk @1 () -> ();
        # The machine was left in an unacceptable state.
        # Most likely marks the machine as `blocked` and somehow informs the previous user.
    }

    admin @3 :Admin;
    # Administrative overrides. This is only not-NULL if you have the required permissions
    # to use it.
    interface Admin $CSharp.name("AdminInterface") {
        forceSetState @0 ( state :State ) -> (); # Forcefully set a machine state
        forceSetUser @1 ( user :Text ) -> (); # Set the given user as current responsible
    }
}

struct User {
    struct UserInformation {
        id @0 :Text;
        name @1 :Text;
        originatingWorkshop @2 :Text;
    }

    read @0 :Read;
    interface Read $CSharp.name("ReadInterface") {
        info @0 () -> ( uinfo :UserInformation );
    }

    write @1 :Write;
    interface Write $CSharp.name("WriteInterface") {
        setName @0 ( name :Text ) -> ();
    }
}