137 lines
6.5 KiB
Markdown
137 lines
6.5 KiB
Markdown
# AccessQueueService
|
|
|
|
AccessQueueService is a microservice API designed to control access to a resource with a limited number of concurrent users. It ensures fair access by:
|
|
|
|
- Granting immediate access if capacity is available.
|
|
- Placing users in a queue when the resource is full.
|
|
- Automatically managing the queue in a first-in, first-out (FIFO) order.
|
|
- Allowing users to revoke their access, freeing up capacity for others.
|
|
|
|
This service is ideal for scenarios where you need to limit the number of users accessing a resource at the same time, such as online ticket sale platforms that control how many users can purchase tickets concurrently.
|
|
|
|
Note: This service is not intended to be called directly from end-user client applications, as it could be easily bypassed. Instead, it should be integrated as middleware within your own APIs or backend services.
|
|
|
|
## How the Service Works
|
|
|
|
1. **Requesting Access:**
|
|
- When a user requests access, the service checks if the current number of active users is below `CapacityLimit`.
|
|
- If there is capacity, the user is granted access immediately and receives an expiration date set by `ExpirationSeconds`.
|
|
- If not, the user is added to a queue and receives their position in the queue.
|
|
|
|
2. **Queueing:**
|
|
- If a user is placed in the queue, subsequent access requests will return the number of users ahead.
|
|
- Users must continually re-request access to remain active in the queue; inactivity may result in losing their spot.
|
|
|
|
3. **Dequeuing:**
|
|
- Users in the queue are managed in a FIFO (first-in, first-out) order.
|
|
- Whenever an access request is made, if there is capacity, the service attempts to dequeue users until capacity is met.
|
|
- If a user is dequeued but the time since their last activity is greater than `ActivitySeconds`, they are not granted access and lose their spot in the queue.
|
|
|
|
4. **Maintaining Access:**
|
|
- Users should continually re-request access while they are active to avoid being considered inactive.
|
|
- If `RollingExpiration` is enabled, the expiration is reset whenever access is re-requested.
|
|
|
|
5. **Revoking Access:**
|
|
- If a user requests access after their expiration date, they must restart the process and re-join the queue if there isn't capacity.
|
|
- When a user revokes access (or their access times out), their access expires immediately.
|
|
|
|
### Note on inactivity vs expiration
|
|
|
|
It is possible for the number of users with access to temporarily exceed the `CapacityLimit` if `ActivitySeconds` is less than `ExpirationSeconds`. This happens because:
|
|
|
|
- The number of available slots is determined by the time since a user's last activity (`ActivitySeconds`), not by their access expiration (`ExpirationSeconds`).
|
|
- If a user is inactive for longer than `ActivitySeconds`, they no longer count toward the capacity, allowing another user to gain access.
|
|
- However, the original user still technically has access until their `ExpirationSeconds` elapses.
|
|
|
|
**To ensure the number of users with access never exceeds `CapacityLimit`, set `ActivitySeconds` equal to `ExpirationSeconds`.**
|
|
|
|
## API Routes
|
|
|
|
### Request Access
|
|
- **GET /access/{id}**
|
|
- **Description:** Request access for a user with the specified `id`.
|
|
- **Response:** Returns an `AccessResponse` object indicating whether access was granted or the user's position in the queue.
|
|
|
|
### Revoke Access
|
|
- **DELETE /access/{id}**
|
|
- **Description:** Revoke access for a user with the specified `id`. This will remove the user from the active list or queue and may allow the next user in the queue to gain access.
|
|
- **Response:** Returns a boolean indicating success.
|
|
|
|
## Configuration Variables
|
|
|
|
Configuration is set in `appsettings.json` or via environment variables. The main configuration section is `AccessQueue`:
|
|
|
|
- **CapacityLimit**: The maximum number of users that can have access at the same time (default: 100).
|
|
- **ActivitySeconds**: How long (in seconds) a user can remain active before being considered inactive (default: 900).
|
|
- **ExpirationSeconds**: How long (in seconds) before an access ticket expires (default: 43200).
|
|
- **RollingExpiration**: If true, the expiration timer resets on activity (default: true).
|
|
- **CleanupIntervalSeconds**: How often (in seconds) the background cleanup runs to remove expired/inactive users (default: 60).
|
|
|
|
Example `appsettings.json`:
|
|
```json
|
|
{
|
|
"AccessQueue": {
|
|
"CapacityLimit": 100,
|
|
"ActivitySeconds": 900,
|
|
"ExpirationSeconds": 43200,
|
|
"RollingExpiration": true,
|
|
"CleanupIntervalSeconds": 60
|
|
}
|
|
}
|
|
```
|
|
|
|
## AccessResponse Object
|
|
|
|
The `AccessResponse` object returned by the API contains the following properties:
|
|
|
|
- **ExpiresOn** (`DateTime?`): The UTC timestamp when the user's access will expire. `null` if the user does not have access.
|
|
- **RequestsAhead** (`int`): The number of requests ahead of the user in the queue. `0` if the user has access.
|
|
- **HasAccess** (`bool`): Indicates whether the user currently has access (true if `ExpiresOn` is set and in the future).
|
|
|
|
## Running the Service
|
|
|
|
1. Build and run the project using .NET 8.0 or later:
|
|
```powershell
|
|
dotnet run --project AccessQueueService/AccessQueueService.csproj
|
|
```
|
|
2. By default, the API will be available at:
|
|
- HTTP: http://localhost:5199
|
|
- HTTPS: https://localhost:7291
|
|
(See `AccessQueueService/Properties/launchSettings.json` for details.)
|
|
|
|
## Running the Tests
|
|
|
|
Unit tests for the service are located in the `AccessQueueServiceTests` project. To run all tests, use the following command from the root of the repository:
|
|
|
|
```powershell
|
|
# Run all tests in the solution
|
|
dotnet test
|
|
```
|
|
|
|
Test results will be displayed in the terminal. You can also use Visual Studio's Test Explorer for a graphical interface.
|
|
|
|
## AccessQueuePlayground (Demo UI)
|
|
|
|
The `AccessQueuePlayground` project provides a simple web-based UI for interacting with the AccessQueueService API. This is useful for testing and demonstration purposes.
|
|
|
|
### Running the Playground
|
|
|
|
1. Build and run the playground project:
|
|
```powershell
|
|
dotnet run --project AccessQueuePlayground/AccessQueuePlayground.csproj
|
|
```
|
|
2. By default, the playground will be available at:
|
|
- HTTP: http://localhost:5108
|
|
- HTTPS: https://localhost:7211
|
|
(See `AccessQueuePlayground/Properties/launchSettings.json` for details.)
|
|
|
|
### Using the Playground
|
|
|
|
- Open the provided URL in your browser.
|
|
- Use the UI to request and revoke access for different user IDs.
|
|
- The UI will display your access status, queue position, and expiration time.
|
|
|
|
This playground is intended only for local development and demonstration.
|
|
|
|
## License
|
|
See [LICENSE.txt](./LICENSE.txt) for license information. |