Unverified Commit f6206240 authored by Hong Minhee's avatar Hong Minhee
Browse files

Non-blocking inbox listener 

https://github.com/dahlia/fedify/issues/70
parent 4096bb70

CHANGES.md

+20 −0
Original line number Diff line number Diff line
@@ -8,6 +8,15 @@ Version 0.12.0 


To be released.



 -  Incoming activities are now queued before being dispatched to the inbox

    listener if the `queue` option is provided to the `createFederation()`

    function.  [[#70]]



     -  The type of `InboxListener` callback type's first parameter became

        `Context` (was `RequestContext`).

     -  The type of `InboxErrorHandler` callback type's first parameter became

        `Context` (was `RequestContext`).



 -  Added `ChatMessage` class to Activity Vocabulary API.  [[#85]]



 -  Improved multitenancy (virtual hosting) support.  [[#66]]
@@ -18,7 +27,18 @@ To be released. 
     -  The type of `ActorKeyPairsDispatcher<TContextData>`'s first parameter

        became `Context` (was `TContextData`).



 -  Deprecated `Federation.sendActivity()` method.



 -  The last parameter of `Federation.sendActivity()` method is no longer

    optional.  Also, it now takes the required `contextData` option.



 -  Added more log messages using the [LogTape] library.  Currently the below

    logger categories are used:



     -  `["fedify", "federation", "queue"]`



[#66]: https://github.com/dahlia/fedify/issues/66

[#70]: https://github.com/dahlia/fedify/issues/70

[#85]: https://github.com/dahlia/fedify/issues/85

docs/manual/federation.md

+6 −6
Original line number Diff line number Diff line
@@ -43,7 +43,7 @@ properties. Some of them are required: 


### `kv`



*Required.*  The `~FederationParameters.kv` property is a `KvStore` instance

*Required.*  The `~FederationOptions.kv` property is a `KvStore` instance

that the `Federation` object uses to store several kinds of cache data and

to maintain the queue of outgoing activities.
@@ -68,7 +68,7 @@ key-value store.[^1] 


### `kvPrefixes`



The `~FederationParameters.kvPrefixes` property is an object that contains

The `~FederationOptions.kvPrefixes` property is an object that contains

the key prefixes for the cache data.  The following are the key prefixes

that the `Federation` object uses:
@@ -84,10 +84,10 @@ that the `Federation` object uses: 


*This API is available since Fedify 0.5.0.*



The `~FederationParameters.queue` property is a `MessageQueue` instance that

the `Federation` object uses to maintain the queue of outgoing activities.

If you don't provide this option, activities will not be queued and will

be sent immediately.

The `~FederationOptions.queue` property is a `MessageQueue` instance that

the `Federation` object uses to maintain the queue of incoming and outgoing

activities.  If you don't provide this option, activities will not be queued

and will be processed immediately.



`MessageQueue` is an abstract interface that represents a message queue.

For now, Fedify provides two built-in implementations of `MessageQueue`, which

docs/manual/inbox.md

+22 −2
Original line number Diff line number Diff line
@@ -173,6 +173,26 @@ federation 
[instance actor]: https://seb.jambor.dev/posts/understanding-activitypub-part-4-threads/#the-instance-actor





Making inbox listeners non-blocking

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



*This API is available since Fedify 0.12.0.*



Usually, processes inside an inbox listener should be non-blocking because

they may involve long-running tasks.  Fortunately, you can easily turn inbox

listeners into non-blocking by providing a [`queue`](./federation.md#queue)

option to `createFederation()` function.  If it is not present, incoming

activities are processed immediately and block the response to the sender until

the processing is done.



While the [`queue`](./federation.md#queue) option is not mandatory,

it is highly recommended to use it in production environments to prevent

the server from being overwhelmed by incoming activities.



> [!NOTE]

> Activities with invalid signatures/proofs are silently ignored and not queued.





Error handling

--------------
@@ -194,5 +214,5 @@ federation 
~~~~



> [!NOTE]

> Activities with invalid signatures are silently ignored and not passed to

> the error handler.
 
> Activities with invalid signatures/proofs are silently ignored and not passed

> to the error handler.

docs/manual/log.md

+8 −0
Original line number Diff line number Diff line
@@ -157,6 +157,14 @@ The `["fedify", "federation", "outbox"]` category is used for logging messages 
related to outgoing activities.  When you cannot send an activity, you can

check the log messages in this category with the `"debug"` level.



### `["fedify", "federation", "queue"]`



*This category is available since Fedify 0.12.0.*



The `["fedify", "federation", "queue"]` category is used for logging messages

related to the task queue.  When you are curious about the task queue, you can

check the log messages in this category with the `"debug"` level.



### `["fedify", "httpsig", "verify"]`



*This category is available since Fedify 0.8.0.*

federation/callback.ts

+2 −2
Original line number Diff line number Diff line
@@ -114,7 +114,7 @@ export type CollectionCursor<TContextData, TFilter> = ( 
 * @typeParam TActivity The type of activity to listen for.

 */

export type InboxListener<TContextData, TActivity extends Activity> = (

  context: RequestContext<TContextData>,

  context: Context<TContextData>,

  activity: TActivity,

) => void | Promise<void>;
@@ -124,7 +124,7 @@ export type InboxListener<TContextData, TActivity extends Activity> = ( 
 * @typeParam TContextData The context data to pass to the {@link Context}.

 */

export type InboxErrorHandler<TContextData> = (

  context: RequestContext<TContextData>,

  context: Context<TContextData>,

  error: Error,

) => void | Promise<void>;