diff --git a/README.md b/README.md index 71fc7ca..1576883 100644 --- a/README.md +++ b/README.md @@ -188,7 +188,7 @@ CREATE INDEX mqtt_acl_username_idx ON mqtt_acl(username); COMMIT; ``` -**Note** that password for MQTT clients stored in PostgreSQL is stored as bcrypt hashed passwords. Therefore, to create / update new MQTT clients you can use this Python snippet: +**Note** that password for MQTT clients stored in PostgreSQL is stored as [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hashed passwords. Therefore, to create / update new MQTT clients you can use this Python snippet: ```python import bcrypt salt = bcrypt.gensalt(rounds=10) @@ -208,19 +208,19 @@ _ = server.AddHook(new(auth.AllowHook), nil) > Don't do this if you are exposing your server to the internet or untrusted networks - it should really be used for development, testing, and debugging only. #### Auth Ledger -The Auth Ledger hook provides a sophisticated mechanism for defining access rules in a struct format. Auth ledger rules come in two forms: Auth rules (connection), and ACL rules (publish subscribe). +The Auth Ledger hook provides a sophisticated mechanism for defining access rules in a struct format. Auth ledger rules come in two forms: Auth rules (connection), and ACL rules (publish subscribe). Auth rules have 4 optional criteria and an assertion flag: -| Criteria | Usage | +| Criteria | Usage | | -- | -- | | Client | client id of the connecting client | | Username | username of the connecting client | | Password | password of the connecting client | | Remote | the remote address or ip of the client | -| Allow | true (allow this user) or false (deny this user) | +| Allow | true (allow this user) or false (deny this user) | ACL rules have 3 optional criteria and an filter match: -| Criteria | Usage | +| Criteria | Usage | | -- | -- | | Client | client id of the connecting client | | Username | username of the connecting client | @@ -307,45 +307,45 @@ The function signatures for all the hooks and `mqtt.Hook` interface can be found > The most flexible event hooks are OnPacketRead, OnPacketEncode, and OnPacketSent - these hooks be used to control and modify all incoming and outgoing packets. -| Function | Usage | +| Function | Usage | |------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OnStarted | Called when the server has successfully started. | -| OnStopped | Called when the server has successfully stopped. | +| OnStopped | Called when the server has successfully stopped. | | OnConnectAuthenticate | Called when a user attempts to authenticate with the server. An implementation of this method MUST be used to allow or deny access to the server (see hooks/auth/allow_all or basic). It can be used in custom hooks to check connecting users against an existing user database. Returns true if allowed. | | OnACLCheck | Called when a user attempts to publish or subscribe to a topic filter. As above. | | OnSysInfoTick | Called when the $SYS topic values are published out. | -| OnConnect | Called when a new client connects, may return an error or packet code to halt the client connection process. | +| OnConnect | Called when a new client connects, may return an error or packet code to halt the client connection process. | | OnSessionEstablish | Called immediately after a new client connects and authenticates and immediately before the session is established and CONNACK is sent. -| OnSessionEstablished | Called when a new client successfully establishes a session (after OnConnect) | -| OnDisconnect | Called when a client is disconnected for any reason. | -| OnAuthPacket | Called when an auth packet is received. It is intended to allow developers to create their own mqtt v5 Auth Packet handling mechanisms. Allows packet modification. | -| OnPacketRead | Called when a packet is received from a client. Allows packet modification. | -| OnPacketEncode | Called immediately before a packet is encoded to be sent to a client. Allows packet modification. | -| OnPacketSent | Called when a packet has been sent to a client. | -| OnPacketProcessed | Called when a packet has been received and successfully handled by the broker. | -| OnSubscribe | Called when a client subscribes to one or more filters. Allows packet modification. | -| OnSubscribed | Called when a client successfully subscribes to one or more filters. | -| OnSelectSubscribers | Called when subscribers have been collected for a topic, but before shared subscription subscribers have been selected. Allows receipient modification. | -| OnUnsubscribe | Called when a client unsubscribes from one or more filters. Allows packet modification. | -| OnUnsubscribed | Called when a client successfully unsubscribes from one or more filters. | -| OnPublish | Called when a client publishes a message. Allows packet modification. | -| OnPublished | Called when a client has published a message to subscribers. | -| OnPublishDropped | Called when a message to a client is dropped before delivery, such as if the client is taking too long to respond. | -| OnRetainMessage | Called then a published message is retained. | -| OnRetainPublished | Called then a retained message is published to a client. | -| OnQosPublish | Called when a publish packet with Qos >= 1 is issued to a subscriber. | -| OnQosComplete | Called when the Qos flow for a message has been completed. | -| OnQosDropped | Called when an inflight message expires before completion. | -| OnPacketIDExhausted | Called when a client runs out of unused packet ids to assign. | -| OnWill | Called when a client disconnects and intends to issue a will message. Allows packet modification. | -| OnWillSent | Called when an LWT message has been issued from a disconnecting client. | -| OnClientExpired | Called when a client session has expired and should be deleted. | -| OnRetainedExpired | Called when a retained message has expired and should be deleted. | -| StoredClients | Returns clients, eg. from a persistent store. | -| StoredSubscriptions | Returns client subscriptions, eg. from a persistent store. | -| StoredInflightMessages | Returns inflight messages, eg. from a persistent store. | -| StoredRetainedMessages | Returns retained messages, eg. from a persistent store. | -| StoredSysInfo | Returns stored system info values, eg. from a persistent store. | +| OnSessionEstablished | Called when a new client successfully establishes a session (after OnConnect) | +| OnDisconnect | Called when a client is disconnected for any reason. | +| OnAuthPacket | Called when an auth packet is received. It is intended to allow developers to create their own mqtt v5 Auth Packet handling mechanisms. Allows packet modification. | +| OnPacketRead | Called when a packet is received from a client. Allows packet modification. | +| OnPacketEncode | Called immediately before a packet is encoded to be sent to a client. Allows packet modification. | +| OnPacketSent | Called when a packet has been sent to a client. | +| OnPacketProcessed | Called when a packet has been received and successfully handled by the broker. | +| OnSubscribe | Called when a client subscribes to one or more filters. Allows packet modification. | +| OnSubscribed | Called when a client successfully subscribes to one or more filters. | +| OnSelectSubscribers | Called when subscribers have been collected for a topic, but before shared subscription subscribers have been selected. Allows receipient modification. | +| OnUnsubscribe | Called when a client unsubscribes from one or more filters. Allows packet modification. | +| OnUnsubscribed | Called when a client successfully unsubscribes from one or more filters. | +| OnPublish | Called when a client publishes a message. Allows packet modification. | +| OnPublished | Called when a client has published a message to subscribers. | +| OnPublishDropped | Called when a message to a client is dropped before delivery, such as if the client is taking too long to respond. | +| OnRetainMessage | Called then a published message is retained. | +| OnRetainPublished | Called then a retained message is published to a client. | +| OnQosPublish | Called when a publish packet with Qos >= 1 is issued to a subscriber. | +| OnQosComplete | Called when the Qos flow for a message has been completed. | +| OnQosDropped | Called when an inflight message expires before completion. | +| OnPacketIDExhausted | Called when a client runs out of unused packet ids to assign. | +| OnWill | Called when a client disconnects and intends to issue a will message. Allows packet modification. | +| OnWillSent | Called when an LWT message has been issued from a disconnecting client. | +| OnClientExpired | Called when a client session has expired and should be deleted. | +| OnRetainedExpired | Called when a retained message has expired and should be deleted. | +| StoredClients | Returns clients, eg. from a persistent store. | +| StoredSubscriptions | Returns client subscriptions, eg. from a persistent store. | +| StoredInflightMessages | Returns inflight messages, eg. from a persistent store. | +| StoredRetainedMessages | Returns retained messages, eg. from a persistent store. | +| StoredSysInfo | Returns stored system info values, eg. from a persistent store. | If you are building a persistent storage hook, see the existing persistent hooks for inspiration and patterns. If you are building an auth hook, you will need `OnACLCheck` and `OnConnectAuthenticate`. @@ -359,7 +359,7 @@ err := server.Publish("direct/publish", []byte("packet scheduled message"), fals > The Qos byte in this case is only used to set the upper qos limit available for subscribers, as per MQTT v5 spec. ### Packet Injection -If you want more control, or want to set specific MQTT v5 properties and other values you can create your own publish packets from a client of your choice. This method allows you to inject MQTT packets (no just publish) directly into the runtime as though they had been received by a specific client. Most of the time you'll want to use the special client flag `inline=true`, as it has unique privileges: it bypasses all ACL and topic validation checks, meaning it can even publish to $SYS topics. +If you want more control, or want to set specific MQTT v5 properties and other values you can create your own publish packets from a client of your choice. This method allows you to inject MQTT packets (no just publish) directly into the runtime as though they had been received by a specific client. Most of the time you'll want to use the special client flag `inline=true`, as it has unique privileges: it bypasses all ACL and topic validation checks, meaning it can even publish to $SYS topics. Packet injection can be used for any MQTT packet, including ping requests, subscriptions, etc. And because the Clients structs and methods are now exported, you can even inject packets on behalf of a connected client (if you have a very custom requirements). @@ -400,7 +400,7 @@ Performance benchmarks were tested using [MQTT-Stresser](https://github.com/inov > Benchmarks are provided as a general performance expectation guideline only. Comparisons are performed using out-of-the-box default configurations. `mqtt-stresser -broker tcp://localhost:1883 -num-clients=2 -num-messages=10000` -| Broker | publish fastest | median | slowest | receive fastest | median | slowest | +| Broker | publish fastest | median | slowest | receive fastest | median | slowest | | -- | -- | -- | -- | -- | -- | -- | | Comqtt v2.0.0 | 124,772 | 125,456 | 124,614 | 314,461 | 313,186 | 311,910 | | [Mosquitto v2.0.15](https://github.com/eclipse/mosquitto) | 155,920 | 155,919 | 155,918 | 185,485 | 185,097 | 184,709 | @@ -429,6 +429,3 @@ Million Message Challenge (hit the server with 1 million messages immediately): ## Contributions Contributions and feedback are both welcomed and encouraged! Open an [issue](https://github.com/wind-c/comqtt/issues) to report a bug, ask a question, or make a feature request. - - -