From 8c80e66b4c5f5c6f37bee0c065c79782c1802f68 Mon Sep 17 00:00:00 2001
From: Yoji Shidara <dara@shidara.net>
Date: Thu, 7 Mar 2024 10:43:05 +0900
Subject: [PATCH] Describe plugin execution order and configs

---
 PLUGINS.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 72 insertions(+), 1 deletion(-)

diff --git a/PLUGINS.md b/PLUGINS.md
index 6c96b97..94124a1 100644
--- a/PLUGINS.md
+++ b/PLUGINS.md
@@ -320,4 +320,75 @@ export async function selectPlugin(
 
 If the query matches with `targetQuery`, then `sameAsTarget` becomes `true` and an early return is made, which results in no call to `next()`. In this case, the client will receive an `precomputedCount`; the count says `42`. No request will be made to the SPARQL endpoint.
 
-In all other cases, the query is dispatched to the SPARQL endpoint as usual.
\ No newline at end of file
+In all other cases, the query is dispatched to the SPARQL endpoint as usual.
+
+
+## Plugin execution order
+
+We have already mentioned that the order in which plug-ins are executed is controlled by the order listed in `plugins.conf`.　Here we will take a closer look at it with two illustrative plugins.
+
+Let's say we have the following two plugins, `foo` and `bar`:
+
+```typescript
+// plugins/foo/main.ts
+
+import { type Context, Response } from "../../src/plugins";
+
+export async function selectPlugin(
+  ctx: SelectContext,
+  next: () => Response,
+): Promise<Response> {
+  console.log("foo:before");
+  const res = await next();
+  console.log("foo:after");
+  return res;
+}
+```
+
+```typescript
+// plugins/bar/main.ts
+import { type Context, Response } from "../../src/plugins";
+
+export async function selectPlugin(
+  ctx: SelectContext,
+  next: () => Response,
+): Promise<Response> {
+  console.log("bar:before");
+  const res = await next();
+  console.log("bar:after");
+  return res;
+}
+```
+
+Then we list them in `plugins.conf` in the following order:
+
+```
+# files/plugins.conf
+./plugins/foo
+./plugins/bar
+```
+
+When a query is issued, the following log will be output:
+
+```
+foo:before
+bar:before
+bar:after
+foo:after
+```
+
+We can think of the plugins listed first in the list as wrapping the results of the plugins listed later.
+
+## Plugin configuration files
+
+Rewrite prefix plugin is shipped with SPARQL-proxy. See `./plugins/rewrite-prefix` for details. This plugin replaces prefixes of IRIs in the query according to the specified rules. It also replaces IRIs in the response in the reverse direction.
+
+The conversion rules are specified by a configuration file described in `mappings.tsv`. It is recommended that the configuration file be placed in the plugin directory. To locate the config file in the same directory as the plugin itself, do the following:
+
+```typescript
+  const filename = "mappings.tsv";
+  const __dirname = (import.meta as any).dirname;
+  const resolvedTsvPath = path.resolve(__dirname, filename);
+
+  // TODO open resolvedTsvPath
+```