Unverified Commit 4e58573c authored by Hong Minhee's avatar Hong Minhee
Browse files

Add Koa framework integration package 

Implements @fedify/koa package to integrate Fedify with Koa v2.x and v3.x.

- Add packages/koa with createMiddleware() function
- Support both Koa 2.x and 3.x via peer dependencies
- Convert between Koa context and Web Standards Request/Response
- Handle onNotFound/onNotAcceptable callbacks for routing
- Build for both npm (ESM/CJS) and JSR distribution
- Add examples/koa with basic integration demo
- Update documentation with Koa integration guide
- Update catalog to use Koa 2.16.0 (latest 2.x)

Closes https://github.com/fedify-dev/fedify/issues/454



Co-Authored-By: default avatarClaude <noreply@anthropic.com>
parent 3c0cb932

deno.json

+1 −0
Original line number Diff line number Diff line
@@ -8,6 +8,7 @@ 
    "./packages/express",

    "./packages/h3",

    "./packages/hono",

    "./packages/koa",

    "./packages/postgres",

    "./packages/redis",

    "./packages/sqlite",

docs/.vitepress/config.mts

+1 −0
Original line number Diff line number Diff line
@@ -90,6 +90,7 @@ const REFERENCES = { 
    { text: "@fedify/amqp", link: "https://jsr.io/@fedify/amqp/doc" },

    { text: "@fedify/express", link: "https://jsr.io/@fedify/express/doc" },

    { text: "@fedify/h3", link: "https://jsr.io/@fedify/h3/doc" },

    { text: "@fedify/koa", link: "https://jsr.io/@fedify/koa/doc" },

    { text: "@fedify/postgres", link: "https://jsr.io/@fedify/postgres/doc" },

    { text: "@fedify/redis", link: "https://jsr.io/@fedify/redis/doc" },

    { text: "@fedify/sqlite", link: "https://jsr.io/@fedify/sqlite/doc" },

docs/manual/integration.md

+61 −3
Original line number Diff line number Diff line
@@ -17,7 +17,7 @@ How it works 
Usually, Fedify behaves as a middleware that wraps around the web framework's

request handler.  The middleware intercepts the incoming HTTP requests and

dispatches them to the appropriate handler based on the request path and

the `Accept` header (i.e., [content negotiation]).  Basically, this architecture

the [`Accept`] header (i.e., [content negotiation]).  Basically, this architecture

allows Fedify and your web framework to coexist in the same domain and port.



For example, if you make a request to */.well-known/webfinger* Fedify will
@@ -66,6 +66,7 @@ sequenceDiagram 
> the communication between the two services (using a message queue or RPC,

> for example), which is non-trivial.



[`Accept`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept

[content negotiation]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation
@@ -120,6 +121,63 @@ app.use(integrateFederation(federation, (req) => "context data goes here")); // 
[Express]: https://expressjs.com/





Koa

---



*This API is available since Fedify 1.9.0.*



[Koa] is a lightweight, expressive, and modern web framework for Node.js,

designed by the team behind Express.  It uses async functions and provides

a more elegant middleware architecture.  The *@fedify/koa* package provides

a middleware to integrate Fedify with Koa:



::: code-group



~~~~ sh [Deno]

deno add jsr:@fedify/koa

~~~~



~~~~ sh [npm]

npm add @fedify/koa

~~~~



~~~~ sh [pnpm]

pnpm add @fedify/koa

~~~~



~~~~ sh [Yarn]

yarn add @fedify/koa

~~~~



~~~~ sh [Bun]

bun add @fedify/koa

~~~~



:::



~~~~ typescript twoslash

// @noErrors: 2345

import Koa from "koa";

import { createMiddleware } from "@fedify/koa";

import { createFederation } from "@fedify/fedify";



export const federation = createFederation<string>({

  // Omitted for brevity; see the related section for details.

});



export const app = new Koa();



app.proxy = true;  // trust proxy headers



app.use(createMiddleware(federation, (ctx) => "context data goes here"));  // [!code highlight]

~~~~



> [!NOTE]

> The `@fedify/koa` package supports both Koa v2.x and v3.x.



[Koa]: https://koajs.com/





Hono

----
@@ -673,9 +731,9 @@ As you can see in the comment, you can handle other requests besides 
federation requests in the middleware.  If you handle only federation requests

in the middleware, you can omit the function argument of `fedifyWith()`.

The `config` object is necessary to let Next.js know that the middleware

should process requests with the `Accept` header matching the federation

should process requests with the [`Accept`] header matching the federation

accept regex.  This is because Next.js middleware processes only requests

with the `Accept` header matching the regex by default.  More details can be

with the [`Accept`] header matching the regex by default.  More details can be

found in the Next.js official documentation [`config` in `middleware.js`].



[Next.js]: https://nextjs.org/

docs/package.json

+3 −0
Original line number Diff line number Diff line
@@ -9,6 +9,7 @@ 
    "@fedify/fedify": "workspace:",

    "@fedify/h3": "workspace:",

    "@fedify/hono": "workspace:",

    "@fedify/koa": "workspace:",

    "@fedify/nestjs": "workspace:",

    "@fedify/next": "workspace:",

    "@fedify/postgres": "workspace:",
@@ -30,6 +31,7 @@ 
    "@types/better-sqlite3": "^7.6.12",

    "@types/bun": "^1.1.14",

    "@types/express": "catalog:",

    "@types/koa": "catalog:",

    "@types/node": "catalog:",

    "amqplib": "catalog:",

    "dayjs": "^1.11.13",
@@ -38,6 +40,7 @@ 
    "h3": "catalog:",

    "hono": "^4.6.14",

    "ioredis": "catalog:",

    "koa": "catalog:",

    "markdown-it-abbr": "^2.0.0",

    "markdown-it-deflist": "^3.0.0",

    "markdown-it-footnote": "^4.0.0",

examples/koa/README.md

0 → 100644
+42 −0
Original line number Diff line number Diff line 
Fedify–Koa integration example

==============================



This is a simple example of how to integrate Fedify into a [Koa] application.



[Koa]: https://koajs.com/





Running the example

-------------------



 1. Clone the repository:



    ~~~~ sh

    git clone https://github.com/fedify-dev/fedify.git

    cd fedify/examples/koa

    ~~~~



 2. Install dependencies:



    ~~~~ sh

    pnpm install

    ~~~~



 3. Start the server:



    ~~~~ sh

    pnpm start & pnpx @fedify/cli tunnel 3000

    ~~~~



 4. Open your browser tunneled URL and start interacting with the app.

    You can see your handle such as

    `@demo@6c10b40c63d9e1ce7da55667ef0ef8b4.serveo.net`.



 5. Access <https://activitypub.academy/> and search your handle and follow.



 6. You can see following list like:



    ~~~~

    This account has the below 1 followers:

    https://activitypub.academy/users/beboes_bedoshs

    ~~~~