From 1869fc37927e7eede3f9429517ffe7b4708f0375 Mon Sep 17 00:00:00 2001 From: Sven Slootweg Date: Thu, 15 Sep 2022 03:39:00 +0200 Subject: [PATCH] WIP --- notes.txt | 2 ++ src/api/index.js | 7 ++++-- src/packages/dlayer/cursor.js | 27 ++++++++++++++++++++ src/packages/dlayer/docs.md | 46 +++++++++++++++++++++++++++++++++++ src/packages/dlayer/index.js | 32 ++++++++++++------------ 5 files changed, 96 insertions(+), 18 deletions(-) create mode 100644 src/packages/dlayer/cursor.js create mode 100644 src/packages/dlayer/docs.md diff --git a/notes.txt b/notes.txt index a24e7a0..3a51939 100644 --- a/notes.txt +++ b/notes.txt @@ -204,3 +204,5 @@ volume_id is_primary MARKER: Implement storage pool setup + network pools + VM spawn + +FIXME: disconnecting the SMART-broken drive during a slow storage-devices overview load causes *all* storage devices to show as unknown diff --git a/src/api/index.js b/src/api/index.js index 0c24fc2..6fa7b8a 100644 --- a/src/api/index.js +++ b/src/api/index.js @@ -36,8 +36,11 @@ module.exports = function () { return typeFromSource(sources.lsblk, names, (device) => types.BlockDevice({ name: device.name })); }, lvm: { - physicalVolumes: ({ paths }, { sources }) => { - return typeFromSource(sources.lvmPhysicalVolumes, paths, (volume) => types.LVMPhysicalVolume({ path: volume.path })); + physicalVolumes: { + $get: ({ paths }, { sources }) => { + return typeFromSource(sources.lvmPhysicalVolumes, paths, (volume) => types.LVMPhysicalVolume({ path: volume.path })); + }, + $methods: {} }, volumeGroups: ({ names }, { sources }) => { return typeFromSource(sources.lvmVolumeGroups, names, (group) => types.LVMVolumeGroup({ name: group.name })); diff --git a/src/packages/dlayer/cursor.js b/src/packages/dlayer/cursor.js new file mode 100644 index 0000000..e260b34 --- /dev/null +++ b/src/packages/dlayer/cursor.js @@ -0,0 +1,27 @@ +"use strict"; + +// Simple data type to represent a query path and corresponding schema path tied together, because these are basically always used together, and it would bloat up the implementation code otherwise + +function createInstance({ queryPath, schemaPath, queryObject, schemaObject }) { + return { + query: queryPath, + schema: schemaPath, + child: function (property, { queryOverride, schemaOverride } = {}) { + return createInstance({ + queryPath: queryPath.concat([ property ]), + schemaPath: schemaPath.concat([ property ]), + queryObject: queryOverride ?? queryObject[property], + schemaObject: schemaOverride ?? schemaObject[property] + }); + } + }; +} + +module.exports = function createCursor({ query, schema }) { + return createInstance({ + queryPath: [], + schemaPath: [], + queryObject: query, + schemaObject: schema + }); +}; diff --git a/src/packages/dlayer/docs.md b/src/packages/dlayer/docs.md new file mode 100644 index 0000000..a939ca6 --- /dev/null +++ b/src/packages/dlayer/docs.md @@ -0,0 +1,46 @@ +```js +{ + system: { + metrics: { + loadAverage: true + }, + hardware: { + drives: { + path: true, + size: true + } + }, + lvm: { + physicalVolumes: { + $collection: { + $$create: { path: "/dev/sda1" } + }, + path: true + $$update: { enabled: true } + } + } + } +} +``` + +# Special schema keys + +- `$anyKey`: specifies a wildcard/fallback handler, that will handle *any* property specified in the query that isn't explicitly specified in the schema. Use sparingly, as it poses API design/maintenance hazards; it will be difficult to add new explicit keys later on without breaking existing queries. +- `$mutations`: used to specify mutation methods that the user can call on objects. Specified as an object that maps mutation names to their corresponding functions. +- `{ $get, $mutations }`: specified as an object in place of where normally a function or literal value would be expected to be returned; specifically meant for collections where you want to both allow the collection to be fetched, *and* for the user to specify collection-related mutations (eg. "create new item") within it in a query. This special syntax exists because collections/lists are "transparent" in dlayer and there is no way to specify collection-level behaviour otherwise. `$mutations` works the same as in its standalone version. + +# Special query keys + +- `$recurse`: set to `true` if you want the query to recursively traverse nested objects; eg. `... children: { $recurse: true } ...`. The recursive query will be for all the keys of the *parent* object, as well as any additional properties specified adjacent to the `$recurse` key. The key under which this special object is specified, determines what key will be assumed to contain the recursive children. +- `$recurseLimit` (default `10`): how many levels of depth the recursion may continue for until being cut off. reaching the limit does not fail the query; it merely stops recursing any further. +- `$allowErrors`: this property may yield an error upon evaluation *without* failing the query as a whole. instead of returning the value for the property directly, a Result object will be produced that represents either the success value or the error that was encountered. Your code still needs to handle the error case in some way. Typically useful when components of the query are expected to fail due to external circumstances that the requesting user cannot control (eg. a dependency on another network service). +- `$arguments`: used to specify an object of named arguments for either a property or a mutation. Optional for properties; required for mutations (even if left empty). +- `$key`: used to override what schema key to fetch; it will attempt to access the specified key, instead of assuming that the schema key equals the key in the query. Typically used to either alias properties (using a different name in the response than how it is defined in the schema), or to access the same property multiple times with different arguments (eg. filters) and expose the results as different keys. +- `$collection`: used to invoke mutations on a (transparent) collection instead of its members + +# Special context keys + +These keys can be used within property handlers. + +- `$getProperty(object, property)`: evaluate/fetch a different property on the object, and return it (in a Promise). You can reference `this` within the property handler as the `object` to evaluate a property of the object you're currently working with. +- `$getPropertyPath(object, propertyPath)`: the same as above, but for a property *path* represented as an array of property names (or a dotpath string). diff --git a/src/packages/dlayer/index.js b/src/packages/dlayer/index.js index ae703e8..88a0e68 100644 --- a/src/packages/dlayer/index.js +++ b/src/packages/dlayer/index.js @@ -35,10 +35,15 @@ function stringifyPath(queryPath, schemaPath) { function maybeCall(value, args, thisContext) { return Promise.try(() => { - if (typeof value === "function") { - return value.call(thisContext, ...args); + // FIXME: Only do this for actual fetch requests + let getter = (typeof value === "object" && value != null && value.$get != null) + ? value.$get + : value; + + if (typeof getter === "function") { + return getter.call(thisContext, ...args); } else { - return value; + return getter; } }); } @@ -119,8 +124,8 @@ function evaluate(schemaObject, queryObject, context, queryPath, schemaPath) { let { schemaKey, handler, args, isRecursive, allowErrors, isLeaf } = analyzeQueryKey(schemaObject, queryObject, queryKey); if (handler != null) { - let nextQueryPath = queryPath.concat([ queryKey ]); - let nextSchemaPath = schemaPath.concat([ schemaKey ]); + let handlingQueryPath = queryPath.concat([ queryKey ]); + let handlingSchemaPath = schemaPath.concat([ schemaKey ]); let promise = Promise.try(() => { // This calls the data provider in the schema @@ -137,17 +142,12 @@ function evaluate(schemaObject, queryObject, context, queryPath, schemaPath) { return mapMaybeArray(value, (item, i) => { if (i != null) { - let elementQueryPath = nextQueryPath.concat([i]); - let elementSchemaPath = nextSchemaPath.concat([i]); - - return Promise.try(() => { - return evaluate(item, effectiveSubquery, context, elementQueryPath, elementSchemaPath); - }).tapCatch((error) => { - // FIXME: Verify that this is no longer needed, since moving the path-assigning logic - // assignErrorPath(error, elementQueryPath, elementSchemaPath); - }); + let elementQueryPath = handlingQueryPath.concat([i]); + let elementSchemaPath = handlingSchemaPath.concat([i]); + + return evaluate(item, effectiveSubquery, context, elementQueryPath, elementSchemaPath); } else { - return evaluate(item, effectiveSubquery, context, nextQueryPath, nextSchemaPath); + return evaluate(item, effectiveSubquery, context, handlingQueryPath, handlingSchemaPath); } }); } else { @@ -177,7 +177,7 @@ function evaluate(schemaObject, queryObject, context, queryPath, schemaPath) { } }).tapCatch((error) => { // FIXME: Chain properly - assignErrorPath(error, nextQueryPath, nextSchemaPath); + assignErrorPath(error, handlingQueryPath, handlingSchemaPath); }); return [ queryKey, promise ];