Possible schema improvements

[KitFieldhouse]

I had some suggestions when looking through the GraphQL API as it exists now.

My main comment is that our API still feels a little "REST-like" due to the fact we are using DRF strings in our requests. Instead, I propose we move away from DRF strings and instead model them in GraphQL's type system.

Querying device properties

Instead of relying on the DRF string to denote what specific property of a device the request is asking for, we should instead represent a device as a GraphQL object.

This could look something like this:

type Device{

    # metadata of our device
    description: String,
    index: Int,
    alarmListName: String 
    # ... whatever other metadata we support??

    # all raw values are a byte array represented as an array of graphQL ints
    analogReadingRaw: [Int!],
    analogSettingRaw: [Int!],
    digitalStatusRaw: [Int!],

    # scaled using primary and common. 
    # array since we need to also support array devices. 
    analogReading: [Float!],
    analogSetting: [Float!],

    # only primary scaling 
    analogReadingPrimary: [Float!], 
    analogReadingSetting: [Float!]
    
    # digital reading with descriptions 
    digitalStatus: [Status!]

    
    
}

type Status {
    bitName: String, 
    status: Boolean
}

Representing a device as an object in our schema has a few main advantages:

• The schema describes exactly what data you can query for our devices. With DRF strings, users have to lookup the DRF string specification to figure out what/how to request properties of a device.

• In the current schema, the syntax of a request is not linked to the semantics of the data we are requesting. For instance, if we ask for G:AMANDA, the semantics of this request dictates we should return the scaled float analog readback for the device. However, there is nothing in our current schema structure that links the request to what type of data we would expect from the response. Instead, users have to make this link themselves. An example of the semantics of our DRF request being out of sync with the syntax of our request would be something like:

{
    acceleratorData(deviceList: ["G:AMANDA"]){
        ... on Raw {
            rawValue
        } 
    }
}

which is a syntactically correct request, but is semantically incorrect as we are requesting the scalar readback of G:AMANDA and only handling raw responses.

• This proposed schema coupled with most GraphQL clients provides clear feedback to the user about misformatted requests. Right now, if the user misformats their DRF string, they just get a network error (at least, as tested on acsys-proxy.fnal.gov:8001/acsys). Even if we did return some sort error message for misformatted DRF strings that precisely indicate where the user went wrong, this is something that we have to build and maintain ourselves and is separate from the request validation that GraphQL performs.

Supplying data source and FTD

The part of our DRF string that indicates the datasource/FTD to use for our request could also be modeled as a GraphQL object.

Here is a possible way of doing it:

input Request {
   name: String,
   source: Source,
   startTime: Int,
   endTime: Int
}

input Source  @oneof {
 dataLoggerSource: DataLoggerSource,
 liveSource: LiveSource
}


input DataLoggerSource{
    ftd: FTD!,
    node: Loggers  # if provided, will only look for the provided dl node for the device + ftd 
}

enum Loggers {
    MInj,
    Mau,
    Inst, 
    # ... and so on. Could have a build script pull this info from the db 
}

input LiveSource{
    ftd: FTD
}

input FTD @oneof {
 periodic: Periodic,
 onEvent: OnEvent
}

input Periodic {
    frequency: Int  # frequency in hz 
}

input OnEvent {
    event: Event,
    delay: Int,  # delay in milliseconds 
    forceHardware: Boolean,
}

enum Event {
 EVENT_00,
 EVENT_01
#
#     ... and so on, I think enum works well for this since then graphQL will 
#     check the user has not typed in something that is not a valid TCLK event, plus 
#     we can rip the event descriptions from https://www-bd.fnal.gov/controls/hardware_vogel/tclk.htm
#     and use this for the description of each event enum variant, which makes the schema nicely self-
#     documented.
}

Putting it all together

One downside of this approach is that we don't get as much flexibility when it comes to building a list of device requests. This becomes apparent when we try to figure out what the root Query and Subscription type should look like. Should the field only return the information for a single device, like this?

type Query {
    device(request: Request): Device
}

In this case, if the user wants to get a list of devices back they would have to do something like this:

{
    AMANDA_AN : device(request: {G:AMANDA, ...} ){
       analogReading 
    }

    AMANDA_DIG : device(request: {G:AMANDA, ... }) { 
        digitalStatus
    }


   # ...and so on and so forth 
}

which requires the user to alias the device field name.

The other option could be for the device field to return a list, like this.

type Query {
    device(request: Request): [Device!]
}

But this carries the restriction that we can't pick out a distinct field for each of these devices without again resorting to aliasing the device field.

Back end structure

The other issue with this approach is that, to my knowledge, the DPM is build around accepting a list of devices. This list can be started and stopped which starts and stops the acquisition of all of the devices the list contains.

Both of the options for Query described above run the risk of creating a bunch of lists that really should be consolidated into one list, since, as I understand it, the GraphQL server implementation will run the resolver for each query on the device field in parallel, meaning that each invocation of the resolver will create a new list in the DPM. Hence, for a request of 100 devices, we would generate 100 lists all with 1 device. This doesn't seem ideal given the current architecture of the DPMs.

I believe using Dataloaders which is supported by our GraphQL server implementation should fix this by allowing us to batch our requests together.

Please poke holes in this design!

[rneswold]

This is great stuff, @KitFieldhouse! I started a similar line of thought with @beauremus a few months ago (https://fermicontrols.slack.com/archives/CHEFFG5S9/p1752176187736169?thread_ts=1752175737.020729&cid=CHEFFG5S9) but didn't have all the detail you described.

I think some of this design, though, needs to incorporate EPICS' device features.

The other issue with this approach is that, to my knowledge, the DPM is build around accepting a list of devices. This list can be started and stopped which starts and stops the acquisition of all of the devices the list contains.

The starting and stopping of lists is only through the old, ACNET interface. For GraphQL, we're "constrained" by the protocol. Queries are request/reply so all the data needs to be accumulated (in the resolver) and returned as one, big reply. For subscriptions, you get a stream of replies. If you want a new set of devices, you cancel the old subscription and start the new one.

[rneswold]

It should be mentioned that this super flexible schema won't be used directly by many developers. Dart is strictly-typed, so we expose a general, opinionated API. Flutter developers aren't expected to be GraphQL experts (in our current vision) and build their own queries.

Maybe we should revisit that vision...?

[beauremus]

Awesome work! Thanks for taking the time to put together a thoughtful proposal.

• I really like the flat model. It's simpler to reason about.
• I'm pretty sure that the resolver already addresses your concerns about building requests into a list

  extapi-acsys/src/graphql/acsys/mod.rs

  Lines 391 to 429 in 96961ba

  	async fn live_data(
  	ctxt: &Context<'ctx>, drfs: &[String], start_time: f64,
  	) -> Result<DataStream> {
  	use tokio_stream::StreamExt;
  	// Strip any source designation and append the once-immediate.
  	let processed_drfs: Vec<_> =
  	drfs.iter().map(|v| strip_source(v).into()).collect();
  	// Make the gRPC data request to DPM.
  	match dpm::acquire_devices(
  	ctxt.data::<Connection>().unwrap(),
  	ctxt.data::<global::AuthInfo>()
  	.ok()
  	.and_then(global::AuthInfo::token)
  	.as_ref(),
  	processed_drfs,
  	)
  	.await
  	{
  	Ok(s) => {
  	Ok(Box::pin(StreamExt::filter_map(s.into_inner(), move |v| {
  	let mut reply = xlat_reply(v);
  	let idx = reply.data[..]
  	.partition_point(|info| info.timestamp < start_time);
  	reply.data.drain(..idx);
  	if reply.data.is_empty() {
  	None
  	} else {
  	Some(reply)
  	}
  	})) as DataStream)
  	}
  	Err(e) => Err(Error::new(format!("{}", e).as_str())),
  	}
  	}

  . (I may be wrong. @rneswold is the implementer and authority)
• While I have conflated GraphQL API and DRF for some time. This is helping realize that they have different use cases. So, that only further justifies your more GraphQL-native approach to this.
  • We still need DRF in apps, Parameter Page.
• We're trying to move away from the data source in the sense that you laid out. For example, the accelerator data subscription includes optional start and end arguments that imply the use of the data logger. For other distinct data, there may be different queries. (The core motivation here is to not expose the implementation of the control system at this level.)
• As @rneswold mentioned, we need to ensure that our approach moving forward at least supports EPICS functionality, but also is extensible for the future.

Let's pull this into a PR so we can have a more detailed conversation about the implementation.

[KitFieldhouse]

Sounds good all! I created the api-dev branch for noodling around with these ideas.

I might be missing something here, but what are the arguments for keeping DRF around in new apps? GraphQL queries can be represented as a string, so why not use that as our format for user entered data requests?

To play devil's advocate, I can see an argument that not only should the controls Flutter core not provide an API over the GraphQL API, but also that for applications that take a user-entered DRFs, we should instead take user-entered GraphQL queries.

A few arguments for this approach:

• In my mind, DRF is a relatively simple query language over a fixed set of types. Any extension to its syntax requires us to not only figure out how to extend the syntax in a backwards compatible way, but also keep the DRF parser code up to date. In the future, if we wanted to build a UI widget that would perform real-time feedback/code completion on user DRF string input, this is another parser and tool that would have to be built and maintained. With GraphQL, we get this "for free" in the sense that the syntax of a request is fully described by the schema and parsing/validation is done automatically by the server implementation, all without us writing a single line of code! Unfortunately, it doesn't look like there is a good GraphQL query IDE widget in Flutter yet, so we don't get real-time validation/code completion UI widgets out of the box.
• In the future, I could imagine a situation where we have grown the GraphQL API such that it provides more metadata on a device than what DRF supports (stuff like what node the device is on, what loggers the device is on etc..). I think a natural question from users and implementers would be "hey, why can't I get this data via DRF/Dart API if the GraphQL API supports it!". I think we then risk getting into the business of chasing the GraphQL API functionality with DRF and/or our handbuilt opinionated API eating development time without adding any new functionality.

However, I am unsure if GraphQL queries give the best user/developer experience. GraphQL queries are certainly more verbose than DRF strings. I think this is mitigated somewhat by the fact that there exists a lot of great tutorials/documentation for GraphQL. In addition, I think LLM's will have an easier time understanding/generating code with GraphQL queries versus DRF strings.

One argument for having an opinionated API over GraphQL is that it makes the Flutter controls core feel more "batteries included".

I also don't know how EPICS would fit into a pure GraphQL approach, but I don't know much about the data model of EPICS PV's. I don't think a pure GraphQL approach makes sense if the schema is so general that developers end up having to build an opinionated API over it anyway.