apostrophe 3.17.0 → 3.18.0

package/.editorconfig

@@ -9,3 +9,6 @@ indent_size = 2
 indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.eslintrc

@@ -79,7 +79,8 @@
   ],
   "parser": "vue-eslint-parser",
   "parserOptions": {
-    "parser": "babel-eslint",
-    "sourceType": "module"
+    "parser": "@babel/eslint-parser",
+    "sourceType": "module",
+    "requireConfigFile": false
   }
-}
+}

package/.github/workflows/main.yml

@@ -20,8 +20,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [12, 14, 16]
-        mongodb-version: [4.2, 4.4, 5.0]
+        node-version: [14, 16, 18]
+        mongodb-version: [4.2, 5.0]
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:

package/.stylelintrc

@@ -6,7 +6,7 @@
     'color-hex-length': 'short',
     'color-named': 'never',
     'color-no-invalid-hex': true,
-    'declaration-property-unit-whitelist': { 'line-height': [] },
+    'declaration-property-unit-allowed-list': { 'line-height': [] },
     'font-family-no-duplicate-names': true,
     'number-leading-zero': 'always',
     'number-max-precision': 2,
@@ -80,5 +80,15 @@
         ]
       }
     ]
-  }
+  },
+  overrides: [
+    {
+      files: ['**/*.scss'],
+      customSyntax: 'postcss-scss'
+    },
+    {
+      files: ['**/*.vue'],
+      customSyntax: 'postcss-html'
+    }
+  ]
 }

package/CHANGELOG.md

@@ -1,6 +1,33 @@
 # Changelog
 
-# 3.17.0 (2022-03-31)
+# 3.18.0 (2022-05-03)
+
+### Adds
+
+* Images may now be cropped to suit a particular placement after selecting them. SVG files may not be cropped as it is not possible in the general case.
+* Editors may also select a "focal point" for the image after selecting it. This ensures that this particular point remains visible even if CSS would otherwise crop it, which is a common issue in responsive design. See the `@apostrophecms/image` widget for a sample implementation of the necessary styles.
+* Adds the `aspectRatio` option for image widgets. When set to `[ w, h ]` (a ratio of width to height), images are automatically cropped to this aspect ratio when chosen for that particular widget. If the user does not crop manually, then cropping happens automatically.
+* Adds the `minSize` option for image widgets. This ensures that the images chosen are at least the given size `[ width, height ]`, and also ensures the user cannot choose something smaller than that when cropping.
+* Implements OpenTelemetry instrumentation.
+* Developers may now specify an alternate Vue component to be used for editing the subfields of relationships, either at the field level or as a default for all relationships with a particular piece type.
+* The widget type base module now always passes on the `components` option as browser data, so that individual widget type modules that support contextual editing can be implemented more conveniently.
+* In-context widget editor components now receive a `focused` prop which is helpful in deciding when to display additional UI.
+* Adds new configuration option - `beforeExit` async handler.
+* Handlers listening for the `apostrophe:run` event are now able to send an exit code to the Apostrophe bootstrap routine.
+* Support for Node.js 17 and 18. MongoDB connections to `localhost` will now successfully find a typical dev MongoDB server bound only to `127.0.0.1`, Apostrophe can generate valid ipv6 URLs pointing back to itself, and `webpack` and `vue-loader` have been updated to address incompatibilities.
+* Adds support for custom context menus provided by any module (see `apos.doc.addContextOperation()`).
+* The `AposSchema` component now supports an optional `generation` prop which may be used to force a refresh when the value of the object changes externally. This is a compromise to avoid the performance hit of checking numerous subfields for possible changes every time the `value` prop changes in response to an `input` event.
+* Adds new event `@apostrophecms/doc:afterAllModesDeleted` fired after all modes of a given document are purged.
+
+### Fixes
+
+* Documentation of obsolete options has been removed.
+* Dead code relating to activating in-context widget editors have been removed. They are always active and have been for some time. In the future they might be swapped in on scroll, but there will never be a need to swap them in "on click."
+* The `self.email` method of modules now correctly accepts a default `from` address configured for a specific module via the `from` subproperty of the `email` option to that module. Thanks to `chmdebeer` for pointing out the issue and the fix.
+* Fixes `_urls` not added on attachment fields when pieces API index is requested (#3643)
+* Fixes float field UI bug that transforms the value to integer when there is no field error and the first number after the decimal is `0`.
+
+## 3.17.0 (2022-03-31)
 
 ### Adds
 
@@ -9,13 +36,18 @@
 * Adds possibility for modules to [extend the webpack configuration](https://v3.docs.apostrophecms.org/guide/webpack.html).
 * Adds possibility for modules to [add extra frontend bundles for scss and js](https://v3.docs.apostrophecms.org/guide/webpack.html). This is useful when the `ui/src` build would otherwise be very large due to code used on rarely accessed pages.
 * Loads the right bundles on the right pages depending on the page template and the loaded widgets. Logged-in users have all the bundles on every page, because they might introduce widgets at any time.
+* Fixes deprecation warnings displayed after running `npm install`, for dependencies that are directly included by this package.
+* Implement custom ETags emission when `etags` cache option is enabled. [See the documentation for more information](https://v3.docs.apostrophecms.org/guide/caching.html).  
+It allows caching of pages and pieces, using a cache invalidation mechanism that takes into account related (and reverse related) document updates, thanks to backlinks mentioned above.  
+Note that for now, only single pages and pieces benefit from the ETags caching system (pages' and pieces' `getOne` REST API route, and regular served pages).  
+The cache of an index page corresponding to the type of a piece that was just saved will automatically be invalidated. However, please consider that it won't be effective when a related piece is saved, therefore the cache will automatically be invalidated _after_ the cache lifetime set in `maxAge` cache option.
 
 ### Fixes
 
 * Apostrophe's webpack build now works properly when developing code that imports module-specific npm dependencies from `ui/src` or `ui/apos` when using `npm link` to develop the module in question.
 * The `es5: true` option to `@apostrophecms/asset` works again.
 
-# 3.16.1 (2022-03-21)
+## 3.16.1 (2022-03-21)
 
 ### Fixes
 

package/defaults.js

@@ -7,6 +7,7 @@ module.exports = {
     '@apostrophecms/schema': {},
     '@apostrophecms/uploadfs': {},
     '@apostrophecms/asset': {},
+    '@apostrophecms/busy': {},
     '@apostrophecms/launder': {},
     '@apostrophecms/http': {},
     '@apostrophecms/db': {},
@@ -50,7 +51,6 @@ module.exports = {
     '@apostrophecms/file': {},
     '@apostrophecms/file-tag': {},
     '@apostrophecms/soft-redirect': {},
-    '@apostrophecms/submitted-draft': {},
-    '@apostrophecms/busy': {}
+    '@apostrophecms/submitted-draft': {}
   }
 };

package/index.js

@@ -1,3 +1,5 @@
+// this should be loaded first
+const opentelemetry = require('./lib/opentelemetry');
 const path = require('path');
 const _ = require('lodash');
 const argv = require('boring')({ end: true });
@@ -39,6 +41,20 @@ let defaults = require('./defaults.js');
 // can be set to a number, which will effectively set the cluster
 // option to `cluster: { processes: n }`.
 //
+// `openTelemetryProvider`
+//
+// If set, Apostrophe will register it as a global OpenTelemetry tracer provider.
+// The expected value is an object, an instance of TracerProvider.
+// If the Node SDK is used in the application instead of manual configuration,
+// the provider instance is only available as a
+// private property: `sdkInstance._tracerProvider`. An issue can be opened
+// to discuss the exposure of a public getter with the OpenTelemetry developers.
+//
+// `beforeExit`
+//
+// If set, Apostrophe will invoke it (await) before invoking process.exit.
+// `beforeExit` may be an async function, will be awaited, and takes no arguments.
+//
 // ## Awaiting the Apostrophe function
 //
 // The apos function is async, but in typical cases you do not
@@ -59,8 +75,14 @@ let defaults = require('./defaults.js');
 // `null` in the primary process. In the child process it resolves as
 // documented above.
 
+// The actual entry point, a wrapper that enables the telemetry and starts the
+// root span
 module.exports = async function(options) {
+  const telemetry = opentelemetry(options);
+  let spanName = 'apostrophe:boot';
   const guardTime = 20000;
+
+  // Detect cluster options
   if (process.env.APOS_CLUSTER_PROCESSES) {
     options.cluster = {
       processes: parseInt(process.env.APOS_CLUSTER_PROCESSES)
@@ -70,48 +92,72 @@ module.exports = async function(options) {
     console.log('NODE_ENV is not set to production, disabling cluster mode');
     options.cluster = false;
   }
+
+  // Execute if cluster enabled
   if (options.cluster && !argv._.length) {
     // For bc with node 14 and below we need to check both
     if (cluster.isPrimary || cluster.isMaster) {
-      let processes = options.cluster.processes || cpus().length;
-      if (processes <= 0) {
-        processes = cpus().length + processes;
-      }
-      let capped = '';
-      if (processes > cpus().length) {
-        processes = cpus().length;
-        capped = ' (capped to number of CPU cores)';
-      }
-      if (processes < 2) {
-        processes = 2;
-        if (capped) {
-          capped = ' (less than 2 cores, capped to minimum of 2)';
-        } else {
-          capped = ' (using minimum of 2)';
+      // Activate and return the callback return value
+      return telemetry.startActiveSpan(`${spanName}:primary`, async (span) => {
+        let processes = options.cluster.processes || cpus().length;
+        if (processes <= 0) {
+          processes = cpus().length + processes;
         }
-      }
-      console.log(`Starting ${processes} cluster child processes${capped}`);
-      for (let i = 0; i < processes; i++) {
-        clusterFork();
-      }
-      cluster.on('exit', (worker, code, signal) => {
-        if (code !== 0) {
-          if ((Date.now() - worker.bornAt) < guardTime) {
-            console.error(`Worker process ${worker.process.pid} failed in ${seconds(Date.now() - worker.bornAt)}, waiting ${seconds(guardTime)} before restart`);
-            setTimeout(() => {
-              respawn(worker);
-            }, guardTime);
+        let capped = '';
+        if (processes > cpus().length) {
+          processes = cpus().length;
+          capped = ' (capped to number of CPU cores)';
+        }
+        if (processes < 2) {
+          processes = 2;
+          if (capped) {
+            capped = ' (less than 2 cores, capped to minimum of 2)';
           } else {
-            respawn(worker);
+            capped = ' (using minimum of 2)';
+          }
+        }
+        console.log(`Starting ${processes} cluster child processes${capped}`);
+        for (let i = 0; i < processes; i++) {
+          clusterFork();
+        }
+        cluster.on('exit', (worker, code, signal) => {
+          if (code !== 0) {
+            if ((Date.now() - worker.bornAt) < guardTime) {
+              console.error(`Worker process ${worker.process.pid} failed in ${seconds(Date.now() - worker.bornAt)}, waiting ${seconds(guardTime)} before restart`);
+              setTimeout(() => {
+                respawn(worker);
+              }, guardTime);
+            } else {
+              respawn(worker);
+            }
           }
+        });
+        span.end();
+        if (typeof options.beforeExit === 'function') {
+          await options.beforeExit();
         }
+        return null;
       });
-      return null;
     } else {
+      // continue as a worker operation, the pid should be recorded by the auto instrumentation
+      spanName += ':worker';
       console.log(`Cluster worker ${process.pid} started`);
     }
   }
 
+  // Create and activate the root span for the boot tracer
+  const self = await telemetry.startActiveSpan(spanName, async (span) => {
+    const res = await apostrophe(options, telemetry, span);
+    span.setStatus(telemetry.api.SpanStatusCode.OK);
+    span.end();
+    return res;
+  });
+
+  return self;
+};
+
+// The actual apostrophe bootstrap
+async function apostrophe(options, telemetry, rootSpan) {
   // The core is not a true moog object but it must look enough like one
   // to participate as an async event emitter
   const self = {
@@ -120,6 +166,43 @@ module.exports = async function(options) {
     }
   };
 
+  // Terminates the process. Emits the `apostrophe:beforeExit` async event;
+  // use this mechanism to invoke any pre-exit application level tasks. Any
+  // `beforeExit` handler errors will be ignored.
+  // Invokes and awaits `options.beforeExit` function if available,
+  // passing as arguments the exit code and message (if any).
+  self._exit = async function(code = 0, message) {
+    try {
+      if (self.emit) {
+        await self.emit('beforeExit');
+      }
+    } catch (e) {
+      // we are at the point where errors are ignored,
+      // if emitter is already registered, all handler errors
+      // are already recorded by the event module instrumentation
+      console.error('beforeExit emit error', e);
+    }
+
+    if (code !== 0) {
+      telemetry.handleError(rootSpan, message);
+    } else {
+      rootSpan.setStatus({
+        code: telemetry.api.SpanStatusCode.OK,
+        message
+      });
+    }
+    rootSpan.end();
+
+    if (typeof options.beforeExit === 'function') {
+      try {
+        await options.beforeExit(code, message);
+      } catch (e) {
+        console.error('beforeExit handler error', e);
+      }
+    }
+    process.exit(code);
+  };
+
   try {
     const matches = process.version.match(/^v(\d+)/);
     const version = parseInt(matches[1]);
@@ -130,6 +213,9 @@ module.exports = async function(options) {
     // promise event emitter code
     self.apos = self;
 
+    // Register the telemetry API as a pseudo module
+    self.apos.telemetry = telemetry;
+
     Object.assign(self, require('./modules/@apostrophecms/module/lib/events.js')(self));
 
     // Determine root module and root directory
@@ -212,17 +298,22 @@ module.exports = async function(options) {
       await self.apos.page.implementParkAllInOtherLocales();
     });
     await self.emit('ready'); // formerly afterInit
+
     if (self.taskRan) {
-      process.exit(0);
+      await self._exit();
     } else {
-      await self.emit('run', self.isTask());
+      const after = { exit: null };
+      await self.emit('run', self.isTask(), after);
+      if (after.exit !== null) {
+        await self._exit(after.exit);
+      }
     }
+
     return self;
   } catch (e) {
     if (options.exit !== false) {
-      /* eslint-disable-next-line no-console */
       console.error(e);
-      process.exit(1);
+      await self._exit(1, e);
     }
   }
 

package/lib/escape-host.js

@@ -0,0 +1,8 @@
+module.exports = host => {
+  if (host.includes(':')) {
+    // ipv6
+    return `[${host}]`;
+  } else {
+    return host;
+  }
+};

package/lib/mongodb-connect.js

@@ -0,0 +1,55 @@
+const mongo = require('mongodb');
+const dns = require('dns');
+
+// Connect to MongoDB, using the modern topology and parser, and
+// a tolerant policy to successfully connect to "localhost" even if
+// the first record returned by the resolver doesn't reach mongodb's
+// bind address because localhost resolves first to ::1 (ipv6) and
+// mongodb lists only on 127.0.0.1 (ipv4) by default. For broadest
+// compatibility we don't assume we know this will happen, we try all the
+// addresses that localhost actually resolves to and succeed with the
+// first one that works.
+
+module.exports = async (uri, options) => {
+  const connectOptions = {
+    useUnifiedTopology: true,
+    useNewUrlParser: true,
+    ...options
+  };
+  const parsed = new URL(uri);
+  if ((parsed.protocol !== 'mongodb:') || (parsed.hostname !== 'localhost')) {
+    return mongo.MongoClient.connect(parsed.toString(), connectOptions);
+  }
+  const records = await dns.promises.lookup('localhost', { all: true });
+  if (!records.length) {
+    // The computer that reaches this point has bigger problems 😅
+    throw new Error('Unable to resolve localhost to an IP address.');
+  }
+  return new Promise((resolve, reject) => {
+    let failed = 0;
+    let succeeded = false;
+    records.forEach(attempt);
+    async function attempt(record) {
+      try {
+        const parsed = new URL(uri);
+        parsed.hostname = record.address;
+        const result = await mongo.MongoClient.connect(parsed.toString(), connectOptions);
+        if (!succeeded) {
+          succeeded = true;
+          resolve(result);
+        } else {
+          // We succeeded in reaching localhost at both ip4 and ip6,
+          // but we only need one of them to succeed
+          await result.close();
+        }
+      } catch (e) {
+        failed++;
+        if (failed === records.length) {
+          // None succeeded, so reject with the last error
+          // (which one we reject with doesn't really matter)
+          reject(e);
+        }
+      }
+    }
+  });
+};

package/lib/opentelemetry.js

@@ -0,0 +1,144 @@
+// Initialize OpenTelemetry tracer singleton and export
+// the most useful API members, the tracer and some helper functions.
+//
+// The library shouldn't be used directly (although it's not fatal),
+// it is registered as self.apos.telemetry pseudo module (see index.js).
+const api = require('@opentelemetry/api');
+const util = require('util');
+const version = require('../package.json').version;
+
+/** @type {api.Tracer} */
+let tracer;
+
+const Attributes = {
+  SCENE: 'apos.scene',
+  TEMPLATE: 'apos.template',
+  EVENT_MODULE: 'apos.event.module',
+  EVENT_NAME: 'apos.event.name',
+  // The module and method targeted by the current operation (see doc module)
+  TARGET_NAMESPACE: 'apos.target.namespace',
+  TARGET_FUNCTION: 'apos.target.function',
+  ARGV: 'apos.argv'
+};
+
+module.exports = function (options = {}) {
+  if (!tracer) {
+    tracer = api.trace.getTracer('apostrophe', version);
+
+    // This shouldn't be needed, but having it doesn't hurt
+    if (options.openTelemetryProvider) {
+      api.trace.setGlobalTracerProvider(options.openTelemetryProvider);
+    }
+  }
+
+  /**
+   * Start and return a new span. Optionally provide a parent span or allow the parent
+   * span to be auto-detected.
+   * Use this when the current code block does the tracing and it doesn't expect
+   * more tracing to happen down the line.
+   *
+   * @param {String} name span name
+   * @param {api.Span|Boolean} [parentSpan] optional parent span
+   * @param {api.SpanOptions} [options] span options
+   * @returns {api.Span}
+   * @example
+   * // Auto-merge with the currently active span context
+   * const span = self.apos.telemetry.startSpan('event:someEvent');
+   * // Provide a parent span
+   * const span = self.apos.telemetry.startSpan('event:someEvent', parent);
+   * // Do not merge with any parent, start as a root
+   * const span = self.apos.telemetry.startSpan('event:someEvent', false);
+   * // Provide options for the newly created span
+   * const span = self.apos.telemetry.startSpan('event:someEvent', true, {
+   *   attributes: [
+   *     [SemanticAttributes.HTTP_METHOD]: "GET",
+   *     [SemanticAttributes.HTTP_FLAVOR]: "1.1",
+   *     [SemanticAttributes.HTTP_URL]: req.url
+   *   ]
+   * });
+   */
+  function startSpan(name, parentSpan, options) {
+    if ((!parentSpan || parentSpan === true) && parentSpan !== false) {
+      parentSpan = api.trace.getSpan(api.context.active());
+    }
+
+    if (parentSpan) {
+      const ctx = api.trace.setSpan(api.context.active(), parentSpan);
+      return tracer.startSpan(name, options || undefined, ctx);
+    }
+
+    return tracer.startSpan(name, options || undefined);
+  }
+
+  /**
+   * Start span and make it active for all the nested spans.
+   * Use this when the current code block does the tracing, but it also expects
+   * more tracing to happen down the line (async calls).
+   *
+   * @param {String} name span name
+   * @param {Function} fn handler function
+   * @param {api.Span|Boolean} [parentSpan] optional parent span
+   * @param {api.SpanOptions} [options] span options
+   * @returns {api.Span|any} the return value of the handler or the newly created span
+   * @example
+   * // Activate span, return some value
+   * const value = await self.apos.telemetry.startActiveSpan(spanName, async (span) => {
+   *   // Use the span, do work, end span, return any value
+   *   span.end();
+   *   return value;
+   * });
+   * // Activate span, using the context of parent span, return the active span
+   * const span = self.apos.telemetry.startActiveSpan(spanName, async (span) => {
+   *   // Use the span, do work, return the span
+   *   return span;
+   * });
+   */
+  function startActiveSpan(name, fn, parentSpan, options) {
+    if (parentSpan) {
+      const ctx = api.trace.setSpan(api.context.active(), parentSpan);
+      return tracer.startActiveSpan(name, options || undefined, ctx, fn);
+    }
+
+    return tracer.startActiveSpan(name, options || undefined, fn);
+  }
+
+  /**
+   * Handle errors helper (catch block).
+   *
+   * @param {api.Span} span
+   * @param {Error|String} err
+   */
+  function handleError(span, err) {
+    span.recordException(err);
+    span.setStatus({
+      code: api.SpanStatusCode.ERROR,
+      message: err
+        ? typeof err === 'string' ? err : err.message
+        : undefined
+    });
+  }
+
+  /**
+   * Stringify object - helper to properly set
+   * object as a span attribute value.
+   *
+   * @param {Object} obj
+   * @returns {String}
+   */
+  function stringify(obj) {
+    return util.inspect(obj, {
+      depth: 20,
+      compact: false
+    });
+  }
+
+  return {
+    api,
+    tracer,
+    Attributes,
+    stringify,
+    handleError,
+    startSpan,
+    startActiveSpan
+  };
+};

package/modules/@apostrophecms/area/ui/apos/apps/AposAreas.js

@@ -5,6 +5,8 @@ export default function() {
 
   let widgetsRendering = 0;
 
+  apos.area.widgetOptions = [];
+
   createWidgetClipboardApp();
 
   createAreaApps();

package/modules/@apostrophecms/area/ui/apos/components/AposAreaEditor.vue

@@ -38,6 +38,7 @@
         :area-id="areaId"
         :key="widget._id"
         :widget="widget"
+        :generation="generation"
         :i="i"
         :options="options"
         :next="next"
@@ -115,23 +116,23 @@ export default {
       default() {
         return {};
       }
+    },
+    generation: {
+      type: Number,
+      required: false,
+      default() {
+        return null;
+      }
     }
   },
   emits: [ 'changed' ],
   data() {
-    const validItems = this.items.filter(item => {
-      if (!window.apos.modules[`${item.type}-widget`]) {
-        console.warn(`The widget type ${item.type} exists in the content but is not configured.`);
-      }
-      return window.apos.modules[`${item.type}-widget`];
-    });
-
     return {
       addWidgetEditor: null,
       addWidgetOptions: null,
       addWidgetType: null,
       areaId: cuid(),
-      next: validItems,
+      next: this.getValidItems(),
       hoveredWidget: null,
       focusedWidget: null,
       contextMenuOptions: {
@@ -189,6 +190,9 @@ export default {
         _id: this.id,
         items: this.next
       });
+    },
+    generation() {
+      this.next = this.getValidItems();
     }
   },
   mounted() {
@@ -506,6 +510,14 @@ export default {
       } else {
         return this.renderings[widget._id];
       }
+    },
+    getValidItems() {
+      return this.items.filter(item => {
+        if (!window.apos.modules[`${item.type}-widget`]) {
+          console.warn(`The widget type ${item.type} exists in the content but is not configured.`);
+        }
+        return window.apos.modules[`${item.type}-widget`];
+      });
     }
   }
 };

package/modules/@apostrophecms/area/ui/apos/components/AposAreaWidget.vue

@@ -101,6 +101,8 @@
         :options="options.widgets[widget.type]"
         :type="widget.type"
         :doc-id="docId"
+        :focused="focused"
+        :key="generation"
       />
       <component
         v-else
@@ -114,6 +116,7 @@
         @edit="$emit('edit', i);"
         :doc-id="docId"
         :rendering="rendering"
+        :key="generation"
       />
       <div
         class="apos-area-widget-controls apos-area-widget-controls--add apos-area-widget-controls--add--bottom"
@@ -199,6 +202,13 @@ export default {
     disabled: {
       type: Boolean,
       default: false
+    },
+    generation: {
+      type: Number,
+      required: false,
+      default() {
+        return null;
+      }
     }
   },
   emits: [ 'clone', 'up', 'down', 'remove', 'edit', 'cut', 'copy', 'update', 'add', 'changed' ],

package/modules/@apostrophecms/asset/lib/globalIcons.js

@@ -53,6 +53,7 @@ module.exports = {
   'help-circle-icon': 'HelpCircle',
   'information-outline-icon': 'InformationOutline',
   'information-icon': 'Information',
+  'image-edit-outline': 'ImageEditOutline',
   'image-icon': 'Image',
   'image-size-select-actual-icon': 'ImageSizeSelectActual',
   'play-box-icon': 'PlayBox',