Skip to content

Commit

Permalink
docs: update middleware documentation, removing linked list mentions
Browse files Browse the repository at this point in the history
  • Loading branch information
Amgelo563 committed Apr 13, 2024
1 parent 4b56d73 commit 64378f0
Show file tree
Hide file tree
Showing 8 changed files with 33 additions and 37 deletions.
11 changes: 5 additions & 6 deletions apps/docs/docs/features/commands/command-interception.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,9 @@ It consists of:
When being checked, a middleware is passed the command that is being checked and the arguments that would be
used to call it. The middleware then replies with a `MiddlewareResponse`, which can either:

* Allow the execution (`{ allowed: true }`), with either:
* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`).
* Forcing the chain to end (`{ allowed: true, checkNext: false }`).
* Deny the execution (`{ allowed: false, checkNext: false }`).
* Make the list check the next middleware: `{ allowed: true, checkNext: true }`.
* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`.
* Deny the execution: `{ allowed: false, checkNext: false }`.

The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`,
`this.false()` and `this.forceTrue()`.
Expand Down Expand Up @@ -62,7 +61,7 @@ You can create your own middleware by either:
import { AbstractCommandMiddleware } from '@nyx-discord/framework';

class MyCommandMiddleware extends AbstractCommandMiddleware {
public check(command: ExecutableCommand<CommandData>, args: CommandExecutionArgs): MiddlewareResponse {
public check(command: ExecutableCommand<CommandData>, ...args: CommandExecutionArgs): MiddlewareResponse {
return this.true();
}
}
Expand Down Expand Up @@ -94,7 +93,7 @@ bot.commands.getExecutor().getMiddleware().add(middleware);
</Tabs>
```

By default, the following middleware chain is used:
By default, the following middleware list is used:

* `CommandFilterCheckMiddleware` - See [🚧 Command Filters](#-command-filters).

Expand Down
4 changes: 2 additions & 2 deletions apps/docs/docs/features/events/event-dispatcher.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ They are used by the `EventBus`, which passes to the dispatcher the subscribers

The dispatcher is then responsible that for each subscriber:

* The `EventSubscriberMiddlewareLinkedList` passes the execution.
* The `SubscriberMiddlewareList` passes the execution.
* The subscriber is executed with its respective arguments.
* Any errors thrown by the subscriber or middleware are caught, wrapped if needed, and redirected to the `ErrorHandler`.

Expand Down Expand Up @@ -88,7 +88,7 @@ This functionality can be turned off by setting it to `null` via `#setConcurrenc

## 🚦 Middleware

The dispatcher stores an `EventSubscriberMiddlewareLinkedList` that will either allow or deny the call of a given subscriber.
The dispatcher stores an `SubscriberMiddlewareList` that will either allow or deny the call of a given subscriber.
This list can be obtained via `EventDispatcher#getMiddleware()`.

For information about how to use it, check the [️🛡️ Event Interception](./event-interception) documentation.
Expand Down
15 changes: 7 additions & 8 deletions apps/docs/docs/features/events/event-interception.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ import TabItem from '@theme/TabItem';

Event interception refers to blocking a subscriber from receiving an event. In nyx, there are two ways to do this:

1. Add an `EventSubscriberMiddleware` to the `EventSubscriberMiddlewareLinkedList` in the `EventDispatcher` that handles
1. Add an `EventSubscriberMiddleware` to the `SubscriberMiddlewareList` in the `EventDispatcher` that handles
the event execution.
2. Provide an `EventSubscriberFilter` in the `EventSubscriber` that receives the event.

Let's explore when and how to use each of these methods.

## 🚦 Subscriber Middlewares

`EventSubscriberMiddlewares` are objects stored on a `EventSubscriberMiddlewareLinkedList`, which is held and called by
`EventSubscriberMiddlewares` are objects stored on a `SubscriberMiddlewareList`, which is held and called by
the event dispatcher every time an event is about to be notified to a subscriber.

It consists of:
Expand All @@ -27,10 +27,9 @@ It consists of:
When being checked, a middleware is passed the subscriber that is being checked and the arguments that would be
used to call it. The middleware then replies with a `MiddlewareResponse`, which can either:

* Allow the execution (`{ allowed: true }`), with either:
* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`).
* Forcing the chain to end (`{ allowed: true, checkNext: false }`).
* Deny the execution (`{ allowed: false, checkNext: false }`).
* Make the list check the next middleware: `{ allowed: true, checkNext: true }`.
* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`.
* Deny the execution: `{ allowed: false, checkNext: false }`.

The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`,
`this.false()` and `this.forceTrue()`.
Expand Down Expand Up @@ -77,7 +76,7 @@ import type {
import { AbstractEventSubscriberMiddleware } from '@nyx-discord/framework';

class MyFrameworkEventSubscriberMiddleware extends AbstractEventSubscriberMiddleware {
public check(subscriber: EventSubscriber, args: EventDispatchArgs): MiddlewareResponse {
public check(subscriber: EventSubscriber, ...args: EventDispatchArgs): MiddlewareResponse {
return this.true();
}
}
Expand Down Expand Up @@ -109,7 +108,7 @@ myBus.getDispatcher().getMiddleware().add(interfaceMiddleware);
</Tabs>
```

By default, the following middleware chain is used:
By default, the following middleware list is used:

* `HandleCheckEventMiddleware` - See [✅ Event handling marking](event-subscriber#-event-handling-marking) on the
`EventSubscriber` guide.
Expand Down
4 changes: 2 additions & 2 deletions apps/docs/docs/features/events/event-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Specifically, the event related objects are:
of these objects.
* `EventBuses`: Store and notify their subscribers when an event happens, using its `EventDispatcher`.
* `EventDispatcher`: Stored by a bus, dispatches an event to the subscribers its passed, checking its
`EventSubscriberMiddlewareLinkedList` and passing any errors to its `ErrorHandler`.
`SubscriberMiddlewareList` and passing any errors to its `ErrorHandler`.
* `EventSubscribers`: Objects that subscribe to an event emitted by an `EventBus`.

<details>
Expand All @@ -30,7 +30,7 @@ of these objects.
1. An object executes the `EventBus#emit()` method on an event bus, passing the emitted event and its arguments.
2. The bus gets the currently registered subscribers to said event.
3. The subscribers list and arguments are passed to the bus' `EventDispatcher`.
4. For every subscriber, the dispatcher checks its `EventSubscriberMiddlewareLinkedList` which will allow or deny its
4. For every subscriber, the dispatcher checks its `SubscriberMiddlewareList` which will allow or deny its
notification to that subscriber. This includes checking the filter on `EventSubscriber#getFilter()`.
5. If allowed, the dispatcher will notify the subscriber, routing any errors to its `EventSubscriberErrorHandler`.

Expand Down
11 changes: 5 additions & 6 deletions apps/docs/docs/features/schedules/schedule-interception.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,9 @@ It consists of:
When being checked, a middleware is passed the schedule that is being checked and the tick metadata. The schedule then
replies with a `MiddlewareResponse`, which can either:

* Allow the execution (`{ allowed: true }`), with either:
* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`).
* Forcing the chain to end (`{ allowed: true, checkNext: false }`).
* Deny the execution (`{ allowed: false, checkNext: false }`).
* Make the list check the next middleware: `{ allowed: true, checkNext: true }`.
* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`.
* Deny the execution: `{ allowed: false, checkNext: false }`.

The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`,
`this.false()` and `this.forceTrue()`.
Expand Down Expand Up @@ -62,7 +61,7 @@ You can create your own middleware by either:
import { AbstractScheduleMiddleware } from '@nyx-discord/framework';

class MyScheduleMiddleware extends AbstractScheduleMiddleware {
public check(schedule: Schedule, args: ScheduleTickArgs): MiddlewareResponse {
public check(schedule: Schedule, ...args: ScheduleTickArgs): MiddlewareResponse {
return this.true();
}
}
Expand Down Expand Up @@ -94,7 +93,7 @@ bot.schedules.getExecutor().getMiddleware().add(middleware);
</Tabs>
```

By default, the following middleware chain is used:
By default, the following middleware list is used:

* `ScheduleFilterCheckMiddleware` - See [🚧 Schedule Filters](#-Schedule-filters).

Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/features/sessions/session-executor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The `SessionExecutor` is the object responsible for executing sessions. It's sto
get it via `SessionManager#getExecutor()`.

The executor manages that:
* The respective `SessionMiddlewareLinkedList` passes the execution.
* The respective `SessionMiddlewareList` passes the execution.
* The session is executed with its respective arguments.
* Any errors thrown by the session or middleware are caught, wrapped if needed, and redirected to the `ErrorHandler`.

Expand Down
17 changes: 8 additions & 9 deletions apps/docs/docs/features/sessions/session-interception.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,15 @@ import TabItem from '@theme/TabItem';

Session interception refers to blocking a session from being executed. In nyx, there are two ways to do this:

1. Add a `SessionMiddleware` to the respective `SessionMiddlewareLinkedList` in the `SessionExecutor` that handles
1. Add a `SessionMiddleware` to the respective `SessionMiddlewareList` in the `SessionExecutor` that handles
the session execution.
2. Provide the respective `SessionFilter` in the `Session`.

Let's explore when and how to use each of these methods.

## 🚦 Session Middlewares

`SessionMiddlewares` are objects stored on a `SessionMiddlewareLinkedList`, which is held and called by
`SessionMiddlewares` are objects stored on a `SessionMiddlewareList`, which is held and called by
the session executor when a session is about to be executed.

Specifically, there are two types of session middlewares:
Expand All @@ -29,10 +29,9 @@ Each consist of:
When being checked, a middleware is passed the session that is being checked and the execution metadata. The session then
replies with a `MiddlewareResponse`, which can either:

* Allow the execution (`{ allowed: true }`), with either:
* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`).
* Forcing the chain to end (`{ allowed: true, checkNext: false }`).
* Deny the execution (`{ allowed: false, checkNext: false }`).
* Make the list check the next middleware: `{ allowed: true, checkNext: true }`.
* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`.
* Deny the execution: `{ allowed: false, checkNext: false }`.

The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`,
`this.false()` and `this.forceTrue()`.
Expand Down Expand Up @@ -68,7 +67,7 @@ import {
} from '@nyx-discord/framework';

class MySessionStartMiddleware extends AbstractSessionStartMiddleware {
public check(session: Session, args: SessionStartArgs): MiddlewareResponse {
public check(session: Session, ...args: SessionStartArgs): MiddlewareResponse {
return this.true();
}
}
Expand All @@ -77,7 +76,7 @@ const startMiddleware = new MySessionStartMiddleware();
bot.sessions.getExecutor().getStartMiddleware().add(startMiddleware);

class MySessionUpdateMiddleware extends AbstractSessionUpdateMiddleware {
public check(session: Session, args: SessionUpdateArgs): MiddlewareResponse {
public check(session: Session, ...args: SessionUpdateArgs): MiddlewareResponse {
return this.true();
}
}
Expand Down Expand Up @@ -114,7 +113,7 @@ bot.sessions.getExecutor().getUpdateMiddleware().add(updateMiddleware);
</Tabs>
```

By default, the following middleware chain is used:
By default, the following middleware list is used:

* `SessionFilterCheckMiddleware` - See [🚧 Session Filters](#-Session-filters).

Expand Down
6 changes: 3 additions & 3 deletions apps/docs/docs/features/sessions/session-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Specifically, the session related objects are:
* `SessionCustomIdCodec`: De/serializes session ids to/from customId strings, to create session components. This component allows you to create and manipulate `customIds` programatically, with no "magic values".
* `SessionRepository`: Temporarily stores sessions until their TTL is over, and notifies the manager when that happens.
* `SessionPromiseRepository`: Stores session promises that will be resolved once a given session ends.
* `SessionExecutor`: Executes sessions, checking its `SessionMiddlewareLinkedList` and passing any errors to its `ErrorHandler`.
* `SessionExecutor`: Executes sessions, checking its `SessionMiddlewareList` and passing any errors to its `ErrorHandler`.
* `SessionUpdateSubscriber`: An [📩 Event Subscriber](../events/event-subscriber) that listens for interactions that can refer to sessions.
* `EventBus`: An [📣 Event Bus](../events/event-bus) that emits session related events.

Expand Down Expand Up @@ -68,7 +68,7 @@ There are three utility session types that derive from the main `Session` interf
`SessionExecutor#handleMissing()`, which will handle the interaction referring to a missing (probably expired)
session. If it does exist, it continues.
4. The `SessionManager` calls `SessionExecutor#update()` to handle the update, passing the interaction and session.
5. The `SessionExecutor` checks its `SessionMiddlewareLinkedList` which will allow or deny the execution.
5. The `SessionExecutor` checks its `SessionMiddlewareList` which will allow or deny the execution.
This includes checking the filter on `Session#getUpdateFilter()`.
6. If the execution is allowed, the session is updated via `Session#update()`, passing any errors to its
`SessionUpdateErrorHandler`, and returning what `Session#update()` returns.
Expand Down Expand Up @@ -141,7 +141,7 @@ participant "SessionCustomIdCodec" as codec
participant "SessionRepository" as repository
participant "SessionExecutor" as executor
participant "Session" as session
participant "SessionMiddlewareLinkedList" as middleware
participant "SessionMiddlewareList" as middleware
participant "EventBus" as eventBus
component -> subscriber : Emit interactionCreate
Expand Down

0 comments on commit 64378f0

Please sign in to comment.