Skip to content

Commit

Permalink
feat(bus): update README
Browse files Browse the repository at this point in the history 
BREAKING CHANGE: The `sectester/bus` package, which was intended
to provide support of communication via the AMQP transport is removed.
This change simplifies the codebase by removing deprecated options and
encourages the use of more modern and supported transport methods.

closes #196
  • Loading branch information
@ostridm
ostridm committed Jun 11, 2024
1 parent 8366b76 commit b9fcf75
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 114 deletions.
75 changes: 1 addition & 74 deletions packages/core/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,8 +164,6 @@ await new Ping({ status: 'connected' }).execute(dispatcher);
await dispatcher.execute(new Ping({ status: 'disconnected' }));
```

The same is applicable for the `Event`. You just need to use the `EventDispatcher` instead of `CommandDispatcher`.

Each message have a correlation ID to ensure atomicity. The regular UUID is used, but you might also want to consider other options.

### Request-response
Expand Down Expand Up @@ -200,80 +198,9 @@ To adjust its behavior you can use next options:
| `expectReply` | Indicates whether to wait for a reply. By default `true`. |
| `ttl` | Period of time that command should be handled before being discarded. By default `10000` ms. |
| `type` | The name of a command. By default, it is the name of specific class. |
| `corelationId` | Used to ensure atomicity while working with EventBus. By default, random UUID. |
| `corelationId` | Used to ensure atomicity. By default, random UUID. |
| `createdAt` | The exact date and time the command was created. |

### Publish-subscribe

When you just want to publish events without waiting for a response, it is better to use the `Event`.
The ideal use case for the publish-subscribe model is when you want to simply notify another service that a certain condition has occurred.

To create an instance of `Event` use the abstract class as follows:

```ts
import { Event } from '@sectester/core';

interface Issue {
name: string;
details: string;
type: string;
cvss?: string;
cwe?: string;
}

class IssueDetected extends Event<Issue> {
constructor(payload: Issue) {
super(payload);
}
}
```

To adjust its behavior you can use next options:

| Option | Description |
| :------------- | ------------------------------------------------------------------------------ |
| `payload` | Message that we want to transmit to the remote service. |
| `type` | The name of a command. By default, it is the name of specific class. |
| `corelationId` | Used to ensure atomicity while working with EventBus. By default, random UUID. |
| `createdAt` | The exact date and time the event was created. |

To create an event handler, you should implement the `Handler` interface and use the `@bind()` decorator to subscribe a handler to an event:

```ts
@bind(IssueDetected)
class IssueDetectedHandler implements EventHandler<Issue> {
public handle(payload: Issue): Promise<void> {
// implementation
}
}
```

You can register multiple event handlers for a single event pattern and all of them will be automatically triggered in parallel.

```ts
@bind(IssueDetected, IssueReopened)
class IssueDetectedHandler implements EventHandler<Issue> {
public handle(payload: Issue): Promise<void> {
// implementation
}
}
```

You can also use a string and symbol to subscribe a handler to events:

```ts
const IssueReopened = Symbol('IssueReopened');

@bind('IssueDetected', IssueReopened)
class IssueDetectedHandler implements EventHandler<Issue> {
public handle(payload: Issue): Promise<void> {
// implementation
}
}
```

As soon as the `IssueDetected` event appears, the event handler takes a single argument, the data passed from the client (in this case, an event payload which has been sent over the network).

## License

Copyright © 2022 [Bright Security](https://brightsec.com/).
Expand Down
50 changes: 10 additions & 40 deletions packages/repeater/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,24 +37,21 @@ The factory exposes the `createRepeater` method that returns a new `Repeater` in
const repeater = await repeaterFactory.createRepeater();
```

You can customize some properties, e.g. name prefix or description, passing options as follows:
You can customize some properties, e.g. request runner capabilities, passing options as follows:

```ts
const repeater = await repeaterFactory.createRepeater({
namePrefix: 'my-repeater',
description: 'My repeater'
requestRunnerOptions: {...},
requestRunners: {...}
});
```

The `createRepeater` method accepts the options described below:

| Option | Description |
| :---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `namePrefix` | Enter a name prefix that will be used as a constant part of the unique name. By default, `sectester`. |
| `description` | Set a short description of the Repeater. |
| `requestRunnerOptions` | Custom the request runner settings that will be used to execute requests to your application. |
| `projectId` | Specify the project ID to associate the Repeater with. |
| `disableRandomNameGeneration` | Disable random name generation for the Repeater's name. |
| Option | Description |
| :--------------------- | ---------------------------------------------------------------------------------- |
| `requestRunnerOptions` | Request runner settings that will be used to execute requests to your application. |
| `requestRunners` | Custom request runner implementation to override the standard runners set. |

The default `requestRunnerOptions` is as follows:

Expand Down Expand Up @@ -95,33 +92,6 @@ export interface RequestRunnerOptions {
}
```

The `RepeaterFactory` also provides a method to create a `Repeater` instance using an existing repeater ID. You can use the `createRepeaterFromExisting` method to accomplish this:

```ts
const existingRepeaterId = '<your repater ID>';
const repeater = await repeaterFactory.createRepeaterFromExisting(
existingRepeaterId
);
```

This method retrieves the existing repeater's details from the cloud using its ID and returns a `Repeater` instance associated with the specified ID.

You can also customize the request runner options for the existing repeater by passing them as options:

```ts
const existingRepeaterId = '<your repater ID>';
const repeater = await repeaterFactory.createRepeaterFromExisting(
existingRepeaterId,
{
requestRunnerOptions: {
timeout: 10000,
maxContentLength: 200,
allowedMimes: ['text/html']
}
}
);
```

The `Repeater` instance provides the `start` method. This method is required to establish a connection with the Bright cloud engine and interact with other services.

```ts
Expand Down Expand Up @@ -169,8 +139,8 @@ describe('Scan', () => {

### Implementation details

Under the hood `Repeater` register `ExecuteRequestEventHandler` in bus,
which in turn uses the `RequestRunner` to proceed with request:
Under the hood `Repeater` connects to the Bright engine using web socket protocol, then listens for incoming commands from the engine.
Which in turn get executed with the `RequestRunner` to proceed with the request coming from the engine:

```ts
export interface RequestRunner {
Expand All @@ -179,7 +149,7 @@ export interface RequestRunner {
}
```

Package contains `RequestRunner` implementations for both HTTP and WS protocols.
Package contains `RequestRunner` implementations for HTTP protocol only.
To support other protocol new class implementation of `RequestRunner` should be registered in global IoC container:

```ts
Expand Down

0 comments on commit b9fcf75

Please sign in to comment.