Skip to content

Commit d49160f

Browse files
hhftechnologyhhftechnology
committed
Update readme.md
1 parent 0f5ef69 commit d49160f

File tree

1 file changed

+141
-60
lines changed

1 file changed

+141
-60
lines changed

‎readme.md‎

Lines changed: 141 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ The plugin uses a client identifier (cookie or IP+UserAgent hash) to track visit
2929
# Static configuration
3030
experimental:
3131
plugins:
32-
queuemanager:
32+
traefik-queue-manager:
3333
moduleName: "github.com/hhftechnology/traefik-queue-manager"
3434
version: "v1.0.0"
3535
```
@@ -52,7 +52,7 @@ experimental:
5252
# Static configuration
5353
experimental:
5454
localPlugins:
55-
queuemanager:
55+
traefik-queue-manager:
5656
moduleName: "github.com/hhftechnology/traefik-queue-manager"
5757
```
5858
@@ -99,62 +99,6 @@ You can customize the queue page by modifying the HTML template. The template su
9999
- `[[.ProgressPercentage]]` - Visual progress percentage
100100
- `[[.Message]]` - Custom message
101101

102-
Example template:
103-
104-
```html
105-
<!DOCTYPE html>
106-
<html>
107-
<head>
108-
<title>Service Queue</title>
109-
<meta http-equiv="refresh" content="[[.RefreshInterval]]">
110-
<style>
111-
body {
112-
font-family: Arial, sans-serif;
113-
text-align: center;
114-
margin-top: 50px;
115-
}
116-
.container {
117-
max-width: 600px;
118-
margin: 0 auto;
119-
padding: 20px;
120-
border: 1px solid #ddd;
121-
border-radius: 5px;
122-
}
123-
.progress {
124-
margin: 20px 0;
125-
height: 20px;
126-
background-color: #f5f5f5;
127-
border-radius: 4px;
128-
overflow: hidden;
129-
}
130-
.progress-bar {
131-
height: 100%;
132-
background-color: #4CAF50;
133-
text-align: center;
134-
line-height: 20px;
135-
color: white;
136-
}
137-
</style>
138-
</head>
139-
<body>
140-
<div class="container">
141-
<h1>You're in the queue</h1>
142-
<p>Our service is currently at capacity. Please wait and you'll be automatically redirected when space becomes available.</p>
143-
144-
<div class="progress">
145-
<div class="progress-bar" style="width: [[.ProgressPercentage]]%">
146-
[[.ProgressPercentage]]%
147-
</div>
148-
</div>
149-
150-
<p>Your position in queue: [[.Position]] of [[.QueueSize]]</p>
151-
<p>Estimated wait time: [[.EstimatedWaitTime]] minutes</p>
152-
<p>This page will refresh automatically in [[.RefreshInterval]] seconds.</p>
153-
</div>
154-
</body>
155-
</html>
156-
```
157-
158102
## Example Usage with Docker Compose
159103

160104
```yaml
@@ -189,8 +133,145 @@ services:
189133
- traefik.http.routers.myservice.entrypoints=web
190134
- traefik.http.routers.myservice.middlewares=queuemanager
191135
```
192-
193-
## Performance Considerations
136+
```yaml
137+
# This is an example of how to configure the Queue Manager middleware
138+
# in your Traefik dynamic configuration.
139+
#
140+
# If using Docker labels, you would prefix these with:
141+
# "traefik.http.middlewares.my-queue-middleware.plugin.queuemanager."
142+
#
143+
# Example for a middleware named "my-queue-middleware":
144+
#
145+
# http:
146+
# middlewares:
147+
# my-queue-middleware:
148+
# plugin:
149+
# queuemanager:
150+
# # --- Basic Settings ---
151+
# enabled: true
152+
# # Description: Globally enables or disables the queue manager middleware.
153+
# # Default: true
154+
# # Tuning: Set to `false` to bypass queueing entirely without removing the middleware configuration.
155+
#
156+
# maxEntries: 50
157+
# # Description: The maximum number of concurrent users allowed to access the target service
158+
# # before new users are placed into the queue.
159+
# # Default: 100 (from CreateConfig in Go code)
160+
# # Tuning: This is the most critical value. Set it based on your backend service's actual capacity
161+
# # to handle concurrent requests without performance degradation. Start conservatively and monitor.
162+
#
163+
# # --- Session Timeouts ---
164+
# inactivityTimeoutSeconds: 300
165+
# # Description: Defines how long an *active* user's session remains valid if they are inactive
166+
# # (i.e., make no further requests to the service). After this period, their slot may be freed up.
167+
# # Default: 60 (from CreateConfig in Go code)
168+
# # Tuning:
169+
# # - Too short: Users reading a page or briefly idle might get requeued.
170+
# # - Too long: Idle users occupy slots longer, slowing queue progression.
171+
# # - Consider average user interaction time. 5-10 minutes (300-600s) is often reasonable.
172+
#
173+
# hardSessionLimitSeconds: 3600
174+
# # Description: (Optional) An absolute maximum duration (in seconds) for any active session,
175+
# # regardless of user activity. If set to 0, this feature is disabled.
176+
# # Default: 0 (disabled, from CreateConfig in Go code)
177+
# # Tuning: Use this to ensure fair access over very long periods or to prevent indefinitely held slots.
178+
# # For example, 3600 (1 hour) ensures a slot is freed at least hourly.
179+
#
180+
# # --- Queue Mechanics ---
181+
# cleanupIntervalSeconds: 60
182+
# # Description: How frequently the plugin's internal cleanup process runs. This process evicts
183+
# # expired (inactive or hard-limited) sessions and promotes users from the queue.
184+
# # Default: 30 (from CreateConfig in Go code, previously 300 in older versions)
185+
# # Tuning: Should be responsive. A good value is often `inactivityTimeoutSeconds / 2` or at least
186+
# # no more than `inactivityTimeoutSeconds`. A value like 30-60 seconds ensures timely promotions.
187+
#
188+
# queueStrategy: "fifo"
189+
# # Description: The strategy for processing the queue. Currently, only "fifo" (First-In, First-Out)
190+
# # is implemented and supported.
191+
# # Default: "fifo" (from CreateConfig in Go code)
192+
# # Tuning: Stick with "fifo" for fairness.
193+
#
194+
# # --- Queue Page Customization ---
195+
# queuePageFile: "/etc/traefik/queue-templates/my-custom-queue-page.html"
196+
# # Description: Absolute path to your custom HTML template file for the queue page.
197+
# # The plugin needs read access to this file from where Traefik is running (e.g., inside the Traefik container).
198+
# # If not provided or the file is not found, a built-in default template is used.
199+
# # Default: "queue-page.html" (relative path, from CreateConfig in Go code, ensure it's accessible)
200+
# # Tuning: Customize this page for branding and user experience. Ensure it uses the placeholders
201+
# # like `[[.RefreshInterval]]`, `[[.Position]]`, `[[.QueueSize]]`, etc.
202+
#
203+
# refreshIntervalSeconds: 20
204+
# # Description: How often the queue page (served to waiting users) automatically refreshes
205+
# # to update their position and estimated wait time. This value is passed to the `[[.RefreshInterval]]`
206+
# # placeholder in your `queuePageFile`.
207+
# # Default: 20 (from CreateConfig in Go code, previously 30 in older versions)
208+
# # Tuning: 15-30 seconds is a good range. Too short can be distracting; too long makes users feel uninformed.
209+
#
210+
# minWaitTimeMinutes: 1
211+
# # Description: The minimum estimated wait time (in minutes) that will be displayed to users,
212+
# # even if the calculated wait time is less (but not zero). Prevents showing "0 minutes" if they are still queued.
213+
# # Default: 1 (from CreateConfig in Go code)
214+
# # Tuning: 1-2 minutes is usually a good minimum to manage expectations.
215+
#
216+
# httpResponseCode: 429
217+
# # Description: The HTTP status code returned when serving the queue page.
218+
# # `429 Too Many Requests` is semantically appropriate.
219+
# # Default: 429 (from CreateConfig in Go code)
220+
# # Tuning: Usually no need to change. `503 Service Unavailable` is an alternative.
221+
#
222+
# httpContentType: "text/html; charset=utf-8"
223+
# # Description: The Content-Type header for the queue page.
224+
# # Default: "text/html; charset=utf-8" (from CreateConfig in Go code)
225+
# # Tuning: Keep as is for standard HTML pages.
226+
#
227+
# # --- Client Identification (Cookies) ---
228+
# useCookies: true
229+
# # Description: Whether to use cookies (`true`) or an IP Address + User-Agent hash (`false`)
230+
# # to identify and track users.
231+
# # Default: true (from CreateConfig in Go code)
232+
# # Tuning: `true` (cookies) is generally recommended for better accuracy and fairness, especially
233+
# # if users might share IPs or have dynamic IPs.
234+
#
235+
# cookieName: "my_app_queue_id"
236+
# # Description: The name of the cookie used for tracking if `useCookies` is `true`.
237+
# # Default: "queue-manager-id" (from CreateConfig in Go code)
238+
# # Tuning: Change if the default name conflicts with other cookies used by your applications.
239+
#
240+
# cookieMaxAgeSeconds: 7200
241+
# # Description: The maximum age of the tracking cookie in the user's browser (in seconds).
242+
# # This determines how long a user might be remembered if they close and reopen their browser.
243+
# # It's different from server-side session timeouts.
244+
# # Default: 3600 (1 hour, from CreateConfig in Go code)
245+
# # Tuning: 1-2 hours (3600-7200s) is common. Longer might be convenient for users in very long queues.
246+
#
247+
# # --- Logging & Debugging ---
248+
# debug: false
249+
# # Description: Enables verbose debug logging for the plugin. This will override `logLevel` to "debug".
250+
# # Default: false (from CreateConfig in Go code)
251+
# # Tuning: Set to `true` ONLY for troubleshooting. Disable in production as it's very verbose.
252+
#
253+
# logLevel: "info"
254+
# # Description: Sets the logging level for the plugin. Options: "debug", "info", "warn", "error".
255+
# # If `debug` is `true`, this is effectively "debug".
256+
# # Default: "info" (from CreateConfig in Go code)
257+
# # Tuning: "info" is good for production. "warn" or "error" for less verbosity if "info" is too much.
258+
#
259+
# logFile: ""
260+
# # Description: (Optional) Path to a file where plugin logs should be written.
261+
# # If empty or not specified, logs go to Traefik's standard output (stderr).
262+
# # Ensure Traefik has write permissions to this path if specified.
263+
# # Default: "" (stderr, from CreateConfig in Go code)
264+
# # Tuning: Use if you want to separate queue manager logs from main Traefik logs.
265+
#
266+
# Example of applying this middleware to a router (e.g., in Docker labels):
267+
# labels:
268+
# - "traefik.http.routers.my-service.middlewares=my-queue-middleware@file" # If defined in a file provider
269+
# # or if defining the middleware directly on the router:
270+
# - "traefik.http.routers.my-service.middlewares=my-queue"
271+
# - "traefik.http.middlewares.my-queue.plugin.queuemanager.maxEntries=50"
272+
# - "traefik.http.middlewares.my-queue.plugin.queuemanager.inactivityTimeoutSeconds=300"
273+
# # ... and so on for other parameters ...
274+
```
194275

195276
The plugin uses an in-memory cache to track active sessions, which provides excellent performance but means:
196277

0 commit comments

Comments
 (0)