mirror of
https://gitlab.com/fabinfra/fabaccess/fabaccess-api.git
synced 2025-03-12 14:51:42 +01:00
264 lines
11 KiB
Cap'n Proto
264 lines
11 KiB
Cap'n Proto
@0x8c2f829df1930cd5;
|
||
|
||
using CSharp = import "programming_language/csharp.capnp";
|
||
$CSharp.namespace("FabAccessAPI.Schema");
|
||
|
||
using Persistent = import "/capnp/persistent.capnp".Persistent;
|
||
using Value = import "/capnp/schema.capnp".Value;
|
||
|
||
using User = import "user.capnp".User;
|
||
using L10NString = import "utils.capnp".L10NString;
|
||
using UUID = import "utils.capnp".UUID;
|
||
using OID = import "utils.capnp".OID;
|
||
|
||
struct Resource {
|
||
# BFFH's smallest unit of a physical or abstract "thing".
|
||
# A resource can be as simple and physical as a table, as complex as a PCB production line or as
|
||
# abstract as "people with specific know-how are present".
|
||
|
||
uuid @0 :UUID;
|
||
# An stable, globally unique descriptor for a resource. Two resources with the same UUID are
|
||
# (almost¹) guaranteed to be the same instance, and the UUID of a resource will survive through
|
||
# server restarts, renaming, reconfiguration etc.
|
||
#
|
||
# [¹]: UUID are 128-bit integer. A collision is *possible*, just *very* unlikely. If you
|
||
# generate 1 billion UUID every second for the next 100 years you have a chance for a collision
|
||
# of about 50%.
|
||
|
||
|
||
id @1 :Text;
|
||
# Every resource in BFFH has a human-readable "name" that is locally unique, but not persistent.
|
||
# That is a resource called "hello" today may be called "bye" tomorrow and a resource called
|
||
# "hi~~" may not be the same resource as the resource called "hi~~" yesterday. This name is
|
||
# canonical and thus identifying. There is exactly *one* valid representation of this name at
|
||
# any given point in time. Thus this name can also not be translated.
|
||
|
||
name @2 :L10NString;
|
||
# A resource may also have a human-meaningful name that is designed to be shown to users. This
|
||
# name does not have to be unique or identifiable or canonical, its main use is to be
|
||
# human-meaningful. For example a "name" could be the translations:
|
||
# - (en, "Prusa SL1 SLA-Printer")
|
||
# - (de, "Prusa SL1 SLA-Drucker")
|
||
# - (es, "Impresora 3D de SLA Prusa SL1")
|
||
|
||
description @3 :L10NString;
|
||
# A resource may have a description attached to tell an user some more information on a resource
|
||
# in a free-form format.
|
||
# Similar to the human-meaningful name this description can be translated.
|
||
|
||
notifiable @4 :Notifiable;
|
||
# Readonly access to the state of a resource.
|
||
# A resource can have "state". State are values attached to a resource that describe a specific
|
||
# state that users or administrators want this resource to be in. Usually this state consists of
|
||
# a number of primitive values encoding for example "turned on" or "turned off".
|
||
# Users with the required permissions may change this state.
|
||
|
||
claimable @5 :Claimable;
|
||
# Writeable access to the state of a resource.
|
||
# Resources are semaphores. They allow writeable access for n ∈ ℕ\{0} clients, depending on the
|
||
# exact resource in question. In some cases n ≔ 1, and the only write access is exclusive.
|
||
# "Claims" model this by requiring a client to first assert a claim, thus reserving a semaphore
|
||
# slot or failing if no more are available, and then using this claim to write to a resources
|
||
# state.
|
||
|
||
interestable @6 :Interestable;
|
||
# Sometimes clients are not just interested in the state of a resource but rather want a
|
||
# resource to stay in a specific state. e.g. somebody working in a makerspace wants the space to
|
||
# stay open, even though they themselves may not have permission to keep the makerspace open.
|
||
# "Interest" represents this. Specifically right now it tells BFFH that the client wants at
|
||
# least one `Claim` to remain.
|
||
}
|
||
|
||
interface Notifiable {
|
||
|
||
}
|
||
|
||
interface Interestable {
|
||
|
||
}
|
||
|
||
interface Claimable {
|
||
# Having this capability set (i.e. not be a `nullptr`) means the user has at least writeable
|
||
# access to a resource
|
||
|
||
claim @0 () -> ClaimResponse;
|
||
# Assert a claim on a resource.
|
||
|
||
struct ClaimResponse {
|
||
enum Error {
|
||
# Error describing why a claim failed.
|
||
|
||
exhausted @0;
|
||
# There are no more free Claim slots
|
||
|
||
locked @1;
|
||
# The resource was locked
|
||
|
||
precondition @2;
|
||
# Some precondition was not met
|
||
|
||
dependencies @3;
|
||
# Resource failed to secure dependencies
|
||
}
|
||
|
||
union {
|
||
failed :group {
|
||
error @0 :Error;
|
||
reason @1 :L10NString;
|
||
}
|
||
success @2 :Claim;
|
||
}
|
||
}
|
||
}
|
||
|
||
|
||
struct Map(Key, Value) {
|
||
# A serialized key-value map represented as a list of (k,v) tuples.
|
||
|
||
entries @0 :List(Entry);
|
||
|
||
struct Entry {
|
||
key @0 :Key;
|
||
val @1 :Value;
|
||
}
|
||
}
|
||
|
||
using State = Map(Oid, Value);
|
||
# Update state provided to a resource via a claim is represented as a Map of human-readable
|
||
# identifiers to Cap'n Proto Values. These Values can be either primitive types such as Uint8,
|
||
# Float64 or more complex types such as structs, lists, or enums.
|
||
# The resulting state of a resource, which is the output of whatever internal logic the resource
|
||
# implements, is also represented in this form, but the keys and also values may be different.
|
||
#
|
||
# Later on very common cases (use, register, return, etc.) can get shortcut functions in the Claim
|
||
# interface that pre-emptively check permissions and ability (so you get the respective cap iff the
|
||
# resource supports that update and if you're allowed to do that) but these functions only serve to
|
||
# make the update more efficient than calling `update` with the string identifier and dynamic typed
|
||
# value but do the exact same serverside as an `update` call would. This way we can make future
|
||
# versions of the API more efficient and easier to use while not breaking compatibility with old
|
||
# clients.
|
||
#
|
||
# TODO: This has the potential problem that a newer client can not distinguish between a server
|
||
# using an old version of the API and a client simply not being allowed to call a specific shortcut
|
||
# method because in both cases that cap will be a nullptr. Could be solved by making `Claim` a
|
||
# struct and indicating which shortcut methods it knows of.
|
||
# Not sure if this is a big problem, we optimize for old clients and up-to-date servers.
|
||
#
|
||
# TODO: We should provide a number of sensible implementations for common complex `Value` types such
|
||
# as "colour", "temperature", etc. and define identifiers for common values.
|
||
|
||
|
||
interface Notify {
|
||
# The Notify interface allows clients to be informed about state changes asyncronously. It is
|
||
# mainly designed around the `register` function which allows a client to register a callback
|
||
# that is called every time state changes happen to the resource in question. It also allows
|
||
# syncronous read access to a resource's output state.
|
||
# Notify are ephermal. If the connection to the server is lost all `Notify` from that client are
|
||
# unregistered.
|
||
|
||
readOutput @0 State;
|
||
# TODO: There should probably be a more efficient approach for reading state than "read *all*
|
||
# state".
|
||
|
||
setNotify @1 ( cb :Callback );
|
||
# Register a given callback to be called on every state update. If this client already has a
|
||
# callback registered for this resource the old callback is replaced.
|
||
|
||
delNotify @2 () -> :Bool;
|
||
# Unregister a registered callback
|
||
|
||
interface Callback {
|
||
# This callback interface needs to be implemented on the client
|
||
|
||
newState @0 State;
|
||
# A server will call newState() with the updated output state. However a server will only
|
||
# allow one in-flight call, so as long as the previous call to newState() hasn't completed
|
||
# the server will drop intermediary updates as to not overload a client.
|
||
# Specifically, example timeline:
|
||
# 1. Update A
|
||
# 2. Server calls newState(A)
|
||
# 3. Update B
|
||
# 4. Update C
|
||
# 5. Call to newState(A) completes
|
||
# 6. Server calls newState(C)
|
||
# So Update B was never sent to the client but the client will eventually always end up with
|
||
# the latest state.
|
||
|
||
# TODO: There should probably be a more efficient approach here too, something along the
|
||
# lines of server-side filtering.
|
||
}
|
||
}
|
||
|
||
interface Interest extends(Notify) {
|
||
# "Interest" right now it tells BFFH that the client wants at least one `Claim` to remain.
|
||
|
||
register @0 ( cb :Callback ) -> ( handle :Handle );
|
||
# Register a callback that BFFH will use to send notifications back to the client asyncronously.
|
||
# This creates an "Interest" on this resource. Setting the callback to a `nullptr` will still
|
||
# register an interest but the server will not be able to inform a client about an impeding
|
||
# claim drop.
|
||
|
||
blocking @1 ();
|
||
# As an alternative to the `register`/`Callback` system you can also call `blocking` which will
|
||
# — as the name suggests — block until the last claim is being dropped. This will register an
|
||
# ephermal Interest that can not survive a disconnect.
|
||
|
||
interface Callback {
|
||
drop @0 ();
|
||
# The last claim on the resource this Interest is registered is being dropped, invalidating
|
||
# the Interest.
|
||
}
|
||
|
||
interface Handle {
|
||
# A Handle back to the server side Interest registered. Destroying this capability will also
|
||
# inform the server and remove the Interest again.
|
||
# TODO: `extends (Persistance)` so that clients can `save` this capability and thus make the
|
||
# Interest survive disconnects.
|
||
|
||
}
|
||
}
|
||
|
||
interface Claim extends(Access) {
|
||
# TODO: extend Persistance. Claims and Interests need to be able to survive a connection loss,
|
||
# which is exactly what `SturdyRef`/Persistance are designed to provide. The Persistance
|
||
# interface only provides one method, `save`, returning a `SturdyRef`. A SturdyRef is a generic
|
||
# and generally speaking opaque type that can be restored to a live capability using some sort
|
||
# of `Restorer` service.
|
||
# In this case the `Restorer` service could be `Claimable` / `Interestable` providing a
|
||
# `restore( ref: SturdyRef )` method.
|
||
|
||
readInput @0 () -> State;
|
||
# Get the current *input* state. This is not the output state that `Notify` or Actors get access
|
||
# to but instead the currently stored input state of a resource.
|
||
|
||
update @1 State -> UpdateResult;
|
||
# Update the State of the claimed resource with the given one
|
||
|
||
struct UpdateResult {
|
||
enum Error {
|
||
# Reason why the update failed
|
||
|
||
denied @0;
|
||
# Update was denied beause user is missing an required permission
|
||
|
||
precondition @1;
|
||
# Some other precondition failed, e.g. because a required field is not set
|
||
|
||
invalid @2;
|
||
# The update is invalid, e.g. because an unknown field was set.
|
||
|
||
typeError @3;
|
||
# A field in the update has a known identifier but a bad type for that identifier
|
||
}
|
||
|
||
union {
|
||
failed :group {
|
||
error @0 :Error;
|
||
field @1 :Text;
|
||
reason @2 :L10NString;
|
||
}
|
||
success @3 :Void;
|
||
}
|
||
}
|
||
}
|