Changelog¶
All notable changes to this project are documented in this file.
[4.0.0] - unreleased¶
Security¶
- Path traversal: queue names are validated against a strict pattern before they are used.
- Allowed: lowercase letters, digits,
_,-, and.(a period must be followed by another character). - Names must start with a letter or digit and are limited to 128 characters.
- The filesystem persistence additionally verifies that every path stays inside
Persist:RootPath. - Authentication runs first: the basic authentication middleware now runs before OpenAPI/Scalar, routing, long polling (hash code middleware) and the controllers.
- Anonymous requests can no longer create queues or hold long-polling connections.
- When authentication is enabled,
/info, the OpenAPI document and the Scalar UI also require credentials. Only/healthand/alivestay anonymous. - Roles: clients can have the roles
read,writeoradmin(hierarchical). - Clients without roles get
admin(backward compatible). - Insufficient roles return
403. - Hardened basic authentication:
- Invalid Base64/UTF-8 headers return
401instead of500. - Secrets are compared in constant time.
- Clients are loaded once at startup.
- Secrets can be stored as SHA-256 hash (
"Secret": "sha256:<hex>"). - Invalid client configurations stop the startup.
- Mutating endpoints no longer accept
GET: dequeueandconfirmdequeueusePOST.removeanddeletemessageuseDELETE.registerusesPUT.- Limits (
MessageQueue:Limits): MaxQueues(10000)MaxMessageBytes(1 MB)MaxDequeueCount(1000)MaxQueueLength(unlimited)- Error messages: only expected errors return their message. Unexpected exceptions return
Internal server errorand are logged. - Startup warnings if authentication is disabled,
Authorization:Typeis unknown, or no HTTPS URL is configured. - Regex DoS: queue patterns collapse multiple wildcards and use a match timeout.
- Long polling:
- Polling no longer creates queues; a non-existent queue has hash code
0. - Polling stops when the client disconnects.
- Invalid
MaxRequestPollingSecondsvalues no longer crash requests. - Confirm bound to user: with authentication enabled, only the user that dequeued a message can confirm it (
confirmdequeue). Without authentication nothing changes.
Breaking Changes¶
- HTTP methods changed:
dequeueandconfirmdequeue:POSTremoveanddeletemessage:DELETEregister:PUT- Clients older than 4.0 (
MessageQueueNET.Client) cannot use these endpoints anymore. Update the client library together with the server. - Queue names starting with
_or-, or containing.., or ending with.are invalid. Persisted queues with such names are skipped on startup (a warning is logged, the files are not deleted). confirmdequeueanddeletemessageno longer create missing queues; they return an error instead.- With authentication enabled,
/info,/openapi/v1.jsonand/scalarrequire credentials. - Swagger UI replaced by Scalar: the API description is generated by
Microsoft.AspNetCore.OpenApiand is available at/openapi/v1.json; the UI is at/scalar(formerly/swagger). - The setting is now
openApiUI(environment variableOPENAPIUI).swaggerUIstill works as a fallback. - Docker images moved to GitHub Container Registry:
ghcr.io/jugstalt/messagequeue-net(formerlygstalt/messagequeue_neton Docker Hub)ghcr.io/jugstalt/messagequeue-net-dashboard(formerlygstalt/messagequeue_net_dashboard)- The images
aspnet:10.0-alpineand run as the non-root userappon port8080. Persisted data belongs in/home/app/messagequeue. MessageQueueNET.Aspire.Hostinguses the new images.MessageQueueNET.Aspireis no longer published as a NuGet package (deprecated).
Build & Deployment¶
- Build, test, pack and publish with Nuke (
./build.ps1,./build.sh); see the build & release documentation. - One version for all packages and images, taken from the git tag
v*(MinVer). - Central package management (
Directory.Packages.props), shared metadata inDirectory.Build.props(SourceLink, symbol packages, README in the packages). - One solution file
MessageQueueNET.slnx(replacesMessageQueueNET.slnandMessageQueueNET.Clients.sln). - GitHub Actions: CI for
master,v4and pull requests; tagsv*publish the NuGet packages (trusted publishing), the Docker images and a GitHub release. - Release assets: ZIP packages for
win-x64and (new)linux-x64with start scripts. - The command line client is also available as .NET tool:
dotnet tool install -g MessageQueueNET.Cmd(commandmqnet).
Fixes¶
ItemLifetimeSecondsis calculated from the original creation date, also for messages that were re-enqueued after a missing confirmation.- The confirmation period starts at dequeue time; persisted unconfirmed items get a new
DequeuedUTCfield. - Items persisted by older versions fall back to the creation date.
- Thread safety of the queue operations (enqueue, dequeue, delete, clear).
- Expired messages are no longer returned or moved to the unconfirmed list on dequeue.
MaxQueueLengthis checked before messages are persisted.registerwaits until the queue properties are persisted and reports errors.all,lengthandremovereport errors instead of returning an empty success result.- The hash code of a single queue is calculated the same way as for queue lists (
LastModifiedUTC). - The background maintenance service no longer blocks threads (
.Result) and stops immediately on shutdown; errors are logged instead of swallowed. - Queues are restored asynchronously before the application starts; invalid queues are logged and skipped instead of stopping the restore.
- Removed the unused
Program_old.cs. - No lost messages:
dequeue: if the dequeue state cannot be persisted, the message is put back into the queue (and removed from the unconfirmed items) instead of being dropped. Messages already collected are still returned.enqueueis all or nothing: if one message cannot be persisted, the already persisted ones are removed again and nothing is enqueued.- A queue removed by its
LifetimeSecondsno longer swallows messages enqueued at the same moment (the queue is created again). QueuePersistNone.RemoveQueueItemreturnedfalse; withPersist:Typenoneno message could be dequeued.dequeueon a queue with items that are removed in parallel no longer fails with anInvalidOperationException.MaxQueuesis also enforced for parallel requests.- Queue pattern matching: regexes are cached, queue names are collected without quadratic lookups.
QueuesServicelogs errors instead of swallowing them.RemoveQueuereturns whether the queue existed.DequeuingClientsCountandDequeuingClientsreturn0/empty (instead ofnull) for queues with confirmation but no unconfirmed items;nullonly means that confirmation is not used.- Client library (
MessageQueueNET.Client): - Basic authentication credentials are encoded as UTF-8 (umlauts in passwords).
- Queue names/patterns are URL-escaped.
- Non-success responses throw
MessageQueueClientException(derives fromException) with theStatusCode. - All
IQueueClientmethods accept an optionalCancellationToken. - Removed the dead certificate validation bypass in the
QueueClientconstructor.
Documentation¶
dequeuealways creates a missing queue; the parameterregisterhas no effect (documentation said the opposite).
Tests¶
- New test project
test/MessageQueueNET.Tests(xUnit +WebApplicationFactory). It covers queue name validation, path traversal, authentication, roles, HTTP methods, limits, and the enqueue/dequeue/confirm roundtrip.