Merge pull request #288 from fractal-analytics-platform/refactor-endpoints

Refactoring of error propagation and more

Author: tcompa

.eslintignore

@@ -6,6 +6,7 @@ node_modules
 .env
 .env.*
 !.env.example
+*.d.ts
 
 # Ignore files for PNPM, NPM and YARN
 pnpm-lock.yaml

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 # Unreleased
 
+* Added proxy endpoints and refactored error propagation (\#288).
 * Remove use of deployment-type `fractal-server` variable (\#298).
 * Add a BSD3 license (\#300).
 

docs/structure.md

@@ -62,34 +62,36 @@ But how is this interaction implemented in this client?
 
 ### Client server interoperability
 
-As said, the svelte client communicate with the fractal server through a set of REST APIs.
+As said, the svelte client communicates with the fractal server through a set of REST APIs.
 
 In this client, every request to the fractal server is sent by the *nodejs server that is serving the svelte
 application*.
-In fact, within the project structure, in `src/lib/server/api` are defined all the REST endpoint requests that
-the svelte client could make to the fractal server from within the nodejs server context (client backend).
 
 > It is important to understand that these requests are made in the server context of the svelte client.
 > No request to the fractal server is sent directly by the browser of the user.
 
 The fact that every request on behalf of a user is sent through a common backend nodejs server, implies a proxy
 architecture.
-The way this works is the following, the svelte client in the browser, sends a HTTP request to the nodejs server that
-is serving the application. This request, with the attached cookies, is then used to compose a new request to be sent to
-the fractal server.
+The way this works is the following: the svelte client in the browser sends a HTTP request to the nodejs server that
+is serving the application. This request, with the attached cookies, is then used to compose a new request to be sent to the fractal server.
 
 > Note that the authentication context is kept thanks to cookies that establish user sessions.
 
 The following image provides an overview for the reader of the described architecture.
 
 ![proxy-architecture.png](media/proxy-architecture.png)
 
-Every fractal server REST endpoint that the client application support is listed within a file in `src/server/api/v1`.
-Here requests are grouped by contexts as `auth_api`, `monitoring_api`, [...].
+To avoid duplicating the logic of each fractal-server endpoint and simplify the error handling, a special Svelte route has been setup to act like a transparent proxy: `src/routes/api/[...path]/+server.js`. This is one of the suggested way to handle a different backend [according to Svelte Kit FAQ](https://kit.svelte.dev/docs/faq#how-do-i-use-x-with-sveltekit-how-do-i-use-a-different-backend-api-server).
 
-### An example
+So, by default, the AJAX calls performed by the front-end have exactly the same path and payload of the fractal-server API, but are sent to the Node.js Svelte back-end.
 
-For instance, considering the code at `src/lib/server/api/v1/auth_api.js:5`:
+Other than the AJAX calls, there are also some calls to fractal-server API done by Svelte SSR, while generating the HTML page. These requests are defined in files under `src/lib/server/api/v1`. Here requests are grouped by contexts as `auth_api`, `monitoring_api`, [...].
+
+### An example using actions
+
+The login is still using the Svelte action approach, in which we have to extract the data from a formData object and then use it to build a JSON payload to be forwarded to fractal-server.
+
+Consider the code at `src/lib/server/api/v1/auth_api.js:5`:
 
 ```javascript
 /**
@@ -241,3 +243,37 @@ _Stores_ are modules that export svelte store objects that are used by component
 application.
 > Note that stores are currently not well-organized or used due to the youth of the client.
 
+## Error handling
+
+The errors received from fractal-server are displayed in error modals without changing the content of their messages. The `displayStandardErrorAlert()` function can be used to easily display an error message alert in a div having a specific id. This function returns a `StandardErrorAlert` object that can be stored in a variable and then used to hide previous error messages calling its `hide()` method.
+
+Here an example:
+
+```javascript
+async function myFunction() {
+  // remove previous error
+  if (errorAlert) {
+    errorAlert.hide();
+  }
+
+  const response = await fetch(`/api/v1/something`);
+  if (response.ok) {
+    // do something with the result
+  } else {
+    const error = await response.json();
+    // add error alert inside the element having 'errorElement' as id
+    errorAlert = displayStandardErrorAlert(error, 'errorElement');
+  }
+}
+```
+
+When the displaying of the error alert should be handled by the caller function it is possible to throw an `AlertError` that has to be caught by the caller in order to display the message.
+
+Errors happening during SSR should be considered fatal and propagated using the `responseError()` utility function:
+
+```javascript
+if (response.ok) {
+  return await response.json();
+}
+await responseError(response);
+```

lib/fractal-server/.gitignore

@@ -5,7 +5,7 @@ myenv
 artifacts
 LOG*
 logs
-*.db
+*.db*
 FRACTAL_TASKS_DIR
 .fractal_server.env
 tmp

lib/test_tasks/my-workflows/example-workflow.json

@@ -0,0 +1,95 @@
+{
+	"name": "Example Workflow",
+	"task_list": [
+		{
+			"meta": {
+				"cpus_per_task": 1,
+				"mem": 4000
+			},
+			"args": {
+				"num_levels": 5,
+				"coarsening_xy": 2,
+				"image_extension": "png",
+				"allowed_channels": [
+					{
+						"color": "00FFFF",
+						"wavelength_id": "A01_C01",
+						"label": "DAPI",
+						"window": {
+							"start": 110,
+							"end": 800
+						}
+					}
+				]
+			},
+			"task": {
+				"source": "pip_remote:fractal_tasks_core:0.11.0:fractal-tasks::create_ome-zarr_structure"
+			}
+		},
+		{
+			"meta": {
+				"cpus_per_task": 1,
+				"mem": 4000,
+				"parallelization_level": "image"
+			},
+			"args": null,
+			"task": {
+				"source": "pip_remote:fractal_tasks_core:0.11.0:fractal-tasks::convert_yokogawa_to_ome-zarr"
+			}
+		},
+		{
+			"meta": {
+				"cpus_per_task": 1,
+				"mem": 1000
+			},
+			"args": {
+				"project_to_2D": true,
+				"suffix": "mip",
+				"ROI_table_names": ["FOV_ROI_table", "well_ROI_table"]
+			},
+			"task": {
+				"source": "pip_remote:fractal_tasks_core:0.11.0:fractal-tasks::copy_ome-zarr_structure"
+			}
+		},
+		{
+			"meta": {
+				"cpus_per_task": 1,
+				"mem": 4000,
+				"parallelization_level": "image"
+			},
+			"args": null,
+			"task": {
+				"source": "pip_remote:fractal_tasks_core:0.11.0:fractal-tasks::maximum_intensity_projection"
+			}
+		},
+		{
+			"meta": {
+				"cpus_per_task": 4,
+				"mem": 16000,
+				"needs_gpu": true,
+				"parallelization_level": "image"
+			},
+			"args": {
+				"input_ROI_table": "well_ROI_table",
+				"use_masks": true,
+				"relabeling": true,
+				"diameter_level0": 60,
+				"model_type": "nuclei",
+				"cellprob_threshold": 0,
+				"flow_threshold": 0.4,
+				"min_size": 15,
+				"augment": false,
+				"net_avg": false,
+				"use_gpu": true,
+				"level": 2,
+				"channel": {
+					"wavelength_id": "A01_C01"
+				},
+				"output_label_name": "nuclei"
+			},
+			"task": {
+				"source": "pip_remote:fractal_tasks_core:0.11.0:fractal-tasks::cellpose_segmentation"
+			}
+		}
+	]
+}

src/lib/common/component_utilities.js

@@ -93,10 +93,15 @@ export function getOnlyModifiedProperties(oldProperties, newProperties) {
 	return modifiedProperties;
 }
 
-export function unsetEmptyStrings(inputValues) {
+/**
+ * Transform an object setting to null all the keys having empty string as value
+ * @param {object} inputValues
+ * @returns {object}
+ */
+export function nullifyEmptyStrings(inputValues) {
 	const clearedValues = {};
 	for (let key in inputValues) {
-		if (typeof(inputValues[key]) === 'string' && inputValues[key].trim() === '') {
+		if (typeof inputValues[key] === 'string' && inputValues[key].trim() === '') {
 			clearedValues[key] = null;
 		} else {
 			clearedValues[key] = inputValues[key];
@@ -105,6 +110,21 @@ export function unsetEmptyStrings(inputValues) {
 	return clearedValues;
 }
 
+/**
+ * Replacer function to ignore empty strings when using JSON.stringify().
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description}
+ * @param {string} _key 
+ * @param {any} value 
+ * @returns {any}
+ */
+export function replaceEmptyStrings(_key, value) {
+	if (typeof value === 'string' && value.trim() === '') {
+		return undefined;
+	} else {
+		return value;
+	}
+}
+
 export function formatMarkdown(markdownValue) {
 	if (!markdownValue) {
 		return '';

src/lib/common/errors.js

@@ -1,8 +1,44 @@
-import { error } from "@sveltejs/kit";
+import { error } from '@sveltejs/kit';
+import StandardErrorAlert from '$lib/components/common/StandardErrorAlert.svelte';
 
-export function PostResourceException(response) {
-	this.reason = response;
-}
+/**
+ * Propagates an error response.
+ * @param {Response} response
+ */
 export async function responseError(response) {
-	throw error(response.status, await response.json())
-}
+	throw error(response.status, await response.json());
+}
+
+/**
+ * Class that can be used by front-end to propagate an error from a component to another.
+ * Used for example to handle the displaying of the error alert when using the ConfirmActionButton.
+ */
+export class AlertError extends Error {
+	/**
+	 * @param {any} reason
+	 */
+	constructor(reason) {
+		super();
+		this.reason = reason;
+	}
+}
+
+/**
+ * Display a standard error alert on the desired HTML element.
+ * @param {any} error
+ * @param {string} targetElementId
+ * @returns {StandardErrorAlert|undefined}
+ */
+export function displayStandardErrorAlert(error, targetElementId) {
+	const errorAlert = document.getElementById(targetElementId);
+	if (errorAlert) {
+		return new StandardErrorAlert({
+			target: errorAlert,
+			props: {
+				error
+			}
+		});
+	} else {
+		console.warn(`Unable to display the error: element ${targetElementId} not found`);
+	}
+}

src/lib/components/common/ConfirmActionButton.svelte

@@ -1,19 +1,41 @@
 <script>
-	import { onMount } from 'svelte';
-	export let callbackAction = () => {}; // A default empty function
+	import { displayStandardErrorAlert } from '$lib/common/errors';
+
+	export let callbackAction = async () => {}; // A default empty function
 	export let style = 'primary';
 	export let btnStyle = 'primary';
 	export let label = '';
 	export let buttonIcon = undefined;
 	export let modalId = undefined;
 	export let message = '';
 
-	onMount(() => {});
+	const openModal = () => {
+		// Remove old errors
+		const errorAlert = document.getElementById(`errorAlert-${modalId}`);
+		if (errorAlert) {
+			errorAlert.innerHTML = '';
+		}
+	};
 
-	const handleCallbackAction = () => callbackAction();
+	/**
+	 * Executes the callback handling possible errors
+	 */
+	const handleCallbackAction = async () => {
+		try {
+			// important: retrieve the modal before executing callbackAction(), because it could remove
+			// the container element and then cause issues with the hide function
+			// @ts-ignore
+			// eslint-disable-next-line no-undef
+			const modal = bootstrap.Modal.getInstance(document.getElementById(modalId));
+			await callbackAction();
+			modal.hide();
+		} catch (/** @type {any} */ error) {
+			displayStandardErrorAlert(error, `errorAlert-${modalId}`);
+		}
+	};
 </script>
 
-<div class="modal" id={modalId}>
+<div class="modal modal-lg" id={modalId}>
 	<div class="modal-dialog">
 		<div class="modal-content">
 			<div class="modal-header">
@@ -26,16 +48,22 @@
 				<p>Do you confirm?</p>
 			</div>
 			<div class="modal-footer">
+				<div class="container">
+					<div id="errorAlert-{modalId}" />
+				</div>
 				<button class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
-				<button class="btn btn-primary" on:click={handleCallbackAction} data-bs-dismiss="modal"
-					>Confirm</button
-				>
+				<button class="btn btn-primary" on:click={handleCallbackAction}>Confirm</button>
 			</div>
 		</div>
 	</div>
 </div>
 
-<button class="btn btn-{btnStyle}" data-bs-toggle="modal" data-bs-target="#{modalId}">
+<button
+	class="btn btn-{btnStyle}"
+	data-bs-toggle="modal"
+	data-bs-target="#{modalId}"
+	on:click={openModal}
+>
 	{#if buttonIcon}
 		<i class="bi bi-{buttonIcon}" />
 	{/if}