add CREATE_WS_TOKEN.md for ws token creation instructions, update README.md to reference new document, and implement getDomainUrl function in server for dynamic domain handling

Author: HananoshikaYomaru

CREATE_WS_TOKEN.md

@@ -0,0 +1,17 @@
+## How to create a ws token
+
+First you need to be an admin and create an external service. name it `openapi-server`. only allow certain authenticated users to create ws tokens.
+
+![](https://share.cleanshot.com/XnVxtRhT+)
+
+then you need to choose the authenticated users. 
+
+![](https://share.cleanshot.com/Q589YH5X+)
+
+then you need to add allowed functions to the external service. 
+
+![](https://share.cleanshot.com/4Zl6v0wz+)
+
+Then you need to create a ws token for the external service. you should turn off the `valid until` option.
+
+![](https://share.cleanshot.com/GR1DMQDB+)

README.md

@@ -42,7 +42,11 @@ USERS=admin:admin,teacher:teacher
 
 you should start your local moodle server before running the test. 
 
-you can also connect to a remote moodle server by setting the `MOODLE_BASE_URL` and `MOODLE_WSTOKEN` environment variables. 
+you can also connect to a remote moodle server by setting the `MOODLE_BASE_URL` environment variables. 
+
+> [!NOTE]
+> you need to create a ws token for the external service. see [CREATE_WS_TOKEN.md](./CREATE_WS_TOKEN.md) for more details.
+> However, you don't need to set the `MOODLE_WSTOKEN` environment variable to run the docker image.
 
 ```bash 
 git pull
@@ -58,21 +62,19 @@ pnpm run build:docker
 # run the docker image 
 docker run \
   -e MOODLE_BASE_URL=https://your.moodle.url \
-  -e MOODLE_WSTOKEN=yourtoken \
   -e USERS=admin:admin,teacher:teacher \
   -p 3000:3000 \
   moodle-openapi-server
 ```
 
 for example
 
+
 ```
 docker run \
   -e MOODLE_BASE_URL=https://learn.twu.ca \
-  -e MOODLE_WSTOKEN=0aa2a744e8ccb6c0a9453f432d3659dc \
   -e USERS=admin:admin,teacher:teacher \
   -p 3000:3000 \
-  -p 6277:6277 \
   moodle-openapi-server
 ```
 

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "moodle-openapi-server",
-	"version": "1.0.3",
+	"version": "1.0.4",
 	"description": "Moddle OpenAPI server",
 	"private": true,
 	"type": "module",

src/get-domain-url.ts

@@ -0,0 +1,30 @@
+/**
+ * get the domain url from the request
+ */
+export function getDomainUrl(
+	request: Request,
+	options?: {
+		/**
+		 * base on the env, you can provide different default host
+		 */
+		defaultHost?: string;
+		/**
+		 * if the host is localhost, by default it will be http, you can override it here
+		 */
+		protocol?: string;
+	},
+) {
+	const host =
+		request.headers.get("X-Forwarded-Host") ??
+		request.headers.get("Host") ??
+		options?.defaultHost;
+
+	if (!host) {
+		throw new Error("Host is required");
+	}
+
+	const protocol =
+		options?.protocol ?? (host.includes("localhost") ? "http" : "https");
+
+	return `${protocol}://${host}`;
+}

src/server.ts

@@ -14,9 +14,11 @@ import { HTTPException } from "hono/http-exception";
 import { basicAuth } from "hono/basic-auth";
 import { parseUsers } from "./parse-users";
 import { html } from "hono/html";
+import { getDomainUrl } from "./get-domain-url";
 
 type Variables = {
 	moodleServer: MoodleServer;
+	domainUrl: string;
 };
 
 const baseURL = process.env.MOODLE_BASE_URL;
@@ -62,6 +64,14 @@ const app = new Hono<{ Variables: Variables }>();
 app.use(cors());
 app.use(logger());
 
+app.use(async (c, next) => {
+	const domainUrl = getDomainUrl(c.req.raw, {
+		defaultHost: "localhost:3000",
+	});
+	c.set("domainUrl", domainUrl);
+	await next();
+});
+
 // Apply middleware to all /api routes
 app.use("/api/*", moodleAuth);
 
@@ -200,23 +210,36 @@ app.get("/meta", async (c) => {
 // swagger 2.0 docs
 app.get("/docs/swagger/:id", (c) => {
 	const id = c.req.param("id");
+	const domainUrl = c.get("domainUrl");
 	const swaggerDocs = swagger2.filter(Boolean);
 	const doc = swaggerDocs[Number(id)];
 	if (!doc) {
 		return c.json({ error: true, message: "Invalid id" }, { status: 400 });
 	}
+	// we need to update the basePath in the swagger doc
+	doc.host = domainUrl;
+
 	return c.json(doc, { status: 200 });
 });
 
 app.get("/docs/openapi_3_1/:id{.+\\.json}", (c) => {
 	const id = c.req.param("id");
+	const domainUrl = c.get("domainUrl");
 	// remove the .json from the id
 	const idWithoutJson = id.replace(".json", "");
 	const openapi31Docs = [openapi31, usecaseOpenapi].filter(Boolean);
 	const doc = openapi31Docs[Number(idWithoutJson)];
 	if (!doc) {
 		return c.json({ error: true, message: "Invalid id" }, { status: 400 });
 	}
+
+	// we need to update the servers in the openapi doc
+	doc.servers = [
+		{
+			url: `${domainUrl}/api`,
+			description: "Moodle webservice API",
+		},
+	];
 	return c.json(doc, { status: 200 });
 });