Migration

Once a new major of Trifid is released, the process to migrate from the previous major version will be documented here.

Migrate from 4.x to 5.x

The v5 version of Trifid is big breaking change.

Say goodbye to the notions of middleware and handlers, as everything is now a plugin. This will be more easier to understand for users.

Trifid is now using Fastify under the hood instead of Express.

Changes in the configuration file

Express -> Fastify

The server.express field is now removed, as Trifid is now using Fastify. Instead, to customize some server options, you can use the server.options field, and configure some fields like trustProxy or logger. You can find more information here: https://fastify.dev/docs/latest/Reference/Server/

Middlewares -> Plugins

The middlewares field is renamed into plugins, to be consistent with the new terms.

All plugins coming from trifid-core should be imported using trifid-core/plugins/X.js instead of trifid-core/middlewares/X.js.

Removals

Plugins from trifid-core

The rewrite and iri plugins that were part of trifid-core are removed. To allow rewriting, you can take a look to the following options from the @zazuko/trifid-plugin-sparql-proxy Trifid plugin:

• allowRewriteToggle
• rewrite
• rewriteQuery
• rewriteResults

Handle redirects

The @zazuko/trifid-handle-redirects plugin is removed. To handle redirects, you can add this followRedirects: true option to the @zazuko/trifid-entity-renderer plugin.

SPARQL handler

The trifid-handler-sparql plugin is removed. Use the @zazuko/trifid-plugin-sparql-proxy plugin instead. It is common to expose it at the /query path.

You can use this configuration:

plugins:
  sparql-proxy:
    module: "@zazuko/trifid-plugin-sparql-proxy"
    config:
      endpointUrl: env:SPARQL_ENDPOINT_URL
      username: env:SPARQL_ENDPOINT_USER
      password: env:SPARQL_ENDPOINT_PASSWORD

This will expose a /query endpoint that will proxy the SPARQL queries to the SPARQL endpoint.

Endpoint configuration

Here was the standard globals configuration part:

globals:
  datasetBaseUrl: https://ld.zazuko.com/
  sparqlEndpoint:
    url: env:SPARQL_ENDPOINT_URL
    username: env:SPARQL_ENDPOINT_USER
    password: env:SPARQL_ENDPOINT_PASSWORD

It was used to configure the SPARQL endpoint.

Since we want to go in a direction that will allow the use of multiple endpoints, we have removed the sparqlEndpoint field from the globals configuration part, and created a new endpoints field.

Here is the new configuration:

globals:
  datasetBaseUrl: https://ld.zazuko.com/
  endpoints:
    default:
      url: /query

Plugins expect to have a default endpoint, so you will need to provide it. This is the endpoint that will be used by plugins. In this example, you can see that it is set to /query, which is the default path for the @zazuko/trifid-plugin-sparql-proxy plugin.

Fetch handler

The trifid-handler-fetch plugin was completely rewritten. It is now able to expose a SPARQL endpoint, like the SPARQL proxy.

Here is an example of how to configure it:

plugins:
  # […]
  handler-fetch:
    module: "trifid-handler-fetch"
    paths: /query
    config:
      url: https://raw.githubusercontent.com/zazuko/tbbt-ld/master/dist/tbbt.nt
      contentType: application/n-triples
      baseIRI: http://example.com
      graphName: http://example.com/graph

This is useful if your data is not coming from a SPARQL endpoint, but from a file or a URL.

Changes in the plugins

The middlewares are now called plugins.

The factory looked like this:

const factory = (trifid) => {
  const { config, logger } = trifid;

  // access a configuration property:
  const { particularField } = config;

  // …do things

  return (req, res, next) => {
    // …so some things

    // use the logger for example
    logger.debug("the middleware was called!");
  };
};

And now it looks like this:

const factory = async (trifid) => {
  const { config, logger } = trifid;

  // access a configuration property:
  const { particularField } = config;

  // …do things

  return {
    // Register default paths and methods, in case none was provided in the configuration file
    defaultConfiguration: async () => {
      return {
        paths: ["/plugin/path"],
        methods: ["GET"],
      };
    },
    routeHandler: async () => {
      // …do some things

      const handler = async (_request, reply) => {
        logger.debug("reached my custom plugin");
        // …do some things
        return reply.type("text/plain").send("Hello, world!\n");
      };
      return handler;
    },
  };
};

Previously, a plugin was forced to return an Express middleware. If the plugin was just doing something that was not requiring to return a middleware, it was forced to return a dummy middleware that was doing nothing. This is why it is now optional to return a routeHandler.

Instead of providing an Express middleware, the routeHandler should return a Fastify route handler.

The new defaultConfiguration field is optional, and can be used to provide default paths and methods in case none was provided in the configuration file. It is an async function, so that you can write some custom logic to generate the default configuration if needed.

Every plugin should be a async.

You will need to specify the mime type when you are sending a response, like this:

reply.type("text/html").send("<p>Hello, world!</p>\n");

Migrate from 3.x to 4.x

The v4 version of Trifid is a simple breaking change with the name of the entity renderer plugin.

If you are using a custom configuration file, you will need to update the name of the entity renderer plugin.

Use @zazuko/trifid-entity-renderer instead of @zazuko/trifid-renderer-entity.

You will need to do the change in your configuration file:

 middlewares:
   # …

   entity-renderer:
-    module: "@zazuko/trifid-renderer-entity"
+    module: "@zazuko/trifid-entity-renderer"

Migrate from older versions

We do not cover the migration process from older versions, as the changes are too big and the process is not straightforward.

We recommand instead to start from scratch.

Trifid version 3 came with those major changes:

• The configuration file format has changed ; it is a lot easier to understand and to use, and supports YAML also.
• The plugin system has been reworked to be more flexible and easier to use.
• Each middleware should return an Express middleware.
• A real template engine is now available (which uses Handlebars) ; previously it was just a simple string replacement, which lead to a lot of limitations, big issues and it was hard to debug them. Code editors were not able to provide proper syntax highlighting and error checking.