From b1de3915a8449e695ffe923379df1403e62d2036 Mon Sep 17 00:00:00 2001 From: Marco Miller Date: Tue, 15 Mar 2022 15:12:59 -0400 Subject: [PATCH] GraphQL ADR: Add example for TSP Query Parameters Document a code example directly in ADR's text, answering its previously related question this way. This example cannot be added as actual code in the existing ADR prototype, as it requires manually provisioned test data. This would otherwise make the prototype more complex than what ADR scope prescribes. Assume usage of [1] as a mean to provision that data. Still, document how one may reproduce this example as working code, which is what was done while preparing this change anyway. Should one be willing to implement this beyond ADR scope, [2] (below) can be used as a legacy schema reference. ADR actual decisions might lead to implementing this further, for real ([2]) as opposed to this hereby trivial approach. Breakpoints are required if manually provisioning test data using [1], which otherwise deletes that data once done with steps. Unlike this added example which is GraphQL, [1]'s way of testing remains REST based. To further clarify, this example is "GraphQL" towards TSP REST client as previously prototyped. ADR scope focuses on first wrapping REST TSP with GraphQL queries from clients such as that ADR prototype: any such TSP GraphQL client may in turn rely on existing TSP REST clients, per ADR. Now, this example is barely about real GraphQL, but more about how to naively start implementing Resolvers towards more advanced GraphQL types (and variable parameters); [2] was an initial example of such types. [1] https://github.com/theia-ide/tsp-python-client/blob/master/test_tsp.py#L324 [2] https://github.com/theia-ide/trace-server-protocol/pull/44 Signed-off-by: Marco Miller --- doc/adr/0002-GraphQL.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/doc/adr/0002-GraphQL.md b/doc/adr/0002-GraphQL.md index 04da9f7b4..7f89668b3 100644 --- a/doc/adr/0002-GraphQL.md +++ b/doc/adr/0002-GraphQL.md @@ -1,6 +1,6 @@ # 2. GraphQL -Date: 2022-03-14 +Date: 2022-03-15 ## Status @@ -70,7 +70,38 @@ From the [Pluralsight course][course]: 1. ***Fragments*** can remove fields list(s) duplication in request. 1. Query (or mutation) operations can be named and support input [variables][var] (parameters). -Can we fit TSP's POST solution above with this GraphQL way of factoring requests? +TSP's aforementioned POST solution fits with this GraphQL way of factoring requests, depending. + +* An extensive GraphQL queries schema such as [this legacy one][pr] could be eventually considered. +* Such a schema, although extensively detailed and split or itemized, would still require Resolvers. +* This ADR [describes what GraphQL resolvers are](#apollo-server-trial) further on. +* Or, an initial schema could be simpler, like [this ADR's prototype](#apollo-server-prototype-tsp). +* In such a more trivial (naive) case, resolver(s) logic gets closer to current TSP clients; e.g.: + +```javascript +const { Query } = require('tsp-typescript-client/lib/models/query/query'); + +const response = await tspClient.fetchTimeGraphTree( + '50484c19-f1af-3af3-841a-0d821ed393d2', + 'org.eclipse.tracecompass.analysis.os.linux.core.cpuusage.CpuUsageDataProvider', + new Query({'parameters': { + 'requested_items': [1846, 1980], + 'requested_times': [1332170683462577664, 1332170684485022208] + }}) +); +``` + +The above example assumes this ADR's own [prototype](#apollo-server-prototype-tsp) `tspClient`, + +* along with the related and already existing TSP (REST) [TypeScript client][client-ts]. +* Values hardcoded above are a local subset of TSP's [Python client][client-py] test data. +* This example is shown above for illustration purposes, but was confirmed as working prior. +* That code can be made into a `resolver` with its name added to prototype's `type Query` schema. +* Resolver is built using prototype's existing ones as template but requires [test data][client-py]. +* For example, such a resolver may return `response.getModel().model.entries.length` or the like. +* Prototype's `./test` script can be amended accordingly and used to run the resulting query. + +This example of course remains trivial and shall benefit from [GraphQL types][pr] and parameters. #### Compression