Fossil SCM
Fixed some Markdown formatting problems in www/emaildesign.md. Made a few minor grammar tweaks while in there.
Commit
30716e3c7dcdb4c194da43420e1e09b1b564ce28a1f871863e05d48d284868a8
Parent
c09b2512b3f86e5…
1 file changed
+34
-31
+34
-31
| --- www/emaildesign.md | ||
| +++ www/emaildesign.md | ||
| @@ -22,11 +22,11 @@ | ||
| 22 | 22 | |
| 23 | 23 | |
| 24 | 24 | * <b>SUBSCRIBER</b> → |
| 25 | 25 | The subscriber table records the email address for people who |
| 26 | 26 | want to receive email notifications. Each subscriber has a |
| 27 | - "subscriberCode" which is a random 32-byte blob that uniquely | |
| 27 | + `subscriberCode` which is a random 32-byte blob that uniquely | |
| 28 | 28 | identifies the subscriber. There are also fields to indicate |
| 29 | 29 | what kinds of notifications the subscriber wishes to receive, |
| 30 | 30 | whether or not the email address of the subscriber has been |
| 31 | 31 | verified, etc. |
| 32 | 32 | |
| @@ -55,11 +55,11 @@ | ||
| 55 | 55 | being a user. |
| 56 | 56 | |
| 57 | 57 | Sending Email Messages |
| 58 | 58 | ---------------------- |
| 59 | 59 | |
| 60 | -Fossil expects to interact with an external mail agent. | |
| 60 | +Fossil expects to interact with an external [mail transfer agent][MTA]. | |
| 61 | 61 | There are currently three different methods for sending outbound |
| 62 | 62 | email messages from Fossil to the external mail agent: |
| 63 | 63 | |
| 64 | 64 | 1. <b>"pipe"</b> → Invoke an external command that accepts |
| 65 | 65 | the email message on standard input. This is useful if the |
| @@ -101,10 +101,13 @@ | ||
| 101 | 101 | There is a utility command-line program named |
| 102 | 102 | ["tools/decode-email.c"](/file/tools/decode-email.c) in |
| 103 | 103 | the Fossil source tree. If you compile this program, you can use it |
| 104 | 104 | to convert the base64 transfer-encoding into human-readable output for |
| 105 | 105 | testing and debugging. |
| 106 | + | |
| 107 | +[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent | |
| 108 | + | |
| 106 | 109 | |
| 107 | 110 | Receiving Email Messages |
| 108 | 111 | ------------------------ |
| 109 | 112 | |
| 110 | 113 | Inbound email messages (for example bounces from failed notification |
| @@ -140,30 +143,30 @@ | ||
| 140 | 143 | -------------------------- |
| 141 | 144 | |
| 142 | 145 | When anonymous passers-by on the internet sign up for email notifications, |
| 143 | 146 | their email address must first be verified. An email message is sent to |
| 144 | 147 | the address supplied inviting the user to click on a link. The link includes |
| 145 | -the random 32-byte subscriberCode in hex. If anyone visits the link, the | |
| 148 | +the random 32-byte `subscriberCode` in hex. If anyone visits the link, the | |
| 146 | 149 | email address is verified. |
| 147 | 150 | |
| 148 | -There is no password. Knowledge of the subscriberCode is sufficient to | |
| 151 | +There is no password. Knowledge of the `subscriberCode` is sufficient to | |
| 149 | 152 | control the subscription. This is not a secure as a separate password, |
| 150 | 153 | but on the other hand it is easier for the average subscriber to deal |
| 151 | 154 | with in that they don't have to come up with yet another password. Also, |
| 152 | -even if the subscriberCode is stolen, the worst that can happens is that | |
| 155 | +even if the `subscriberCode` is stolen, the worst that can happens is that | |
| 153 | 156 | the thief can change your subscription settings. No PII (other than |
| 154 | 157 | the subscriber's email address) is available to an attacker with the |
| 155 | -subscriberCode. Nor can knowledge of the subscriberCode lead to a | |
| 158 | +`subscriberCode`. Nor can knowledge of the `subscriberCode` lead to a | |
| 156 | 159 | email flood or other annoyance attack, as far as I can see. |
| 157 | 160 | |
| 158 | 161 | If subscriberCodes are ever compromised, new ones can be generated |
| 159 | 162 | as follows: |
| 160 | 163 | |
| 161 | -> UPDATE subscriber SET subscriberCode=randomblob(32); | |
| 164 | + UPDATE subscriber SET subscriberCode=randomblob(32); | |
| 162 | 165 | |
| 163 | 166 | Perhaps the system be enhanced to randomize the |
| 164 | -subscriberCodes periodically - say just before each daily digest | |
| 167 | +`subscriberCodes` periodically - say just before each daily digest | |
| 165 | 168 | is sent out? |
| 166 | 169 | |
| 167 | 170 | User Control Of Their Subscription |
| 168 | 171 | ---------------------------------- |
| 169 | 172 | |
| @@ -170,51 +173,51 @@ | ||
| 170 | 173 | If a user has a separate account with a login and password for |
| 171 | 174 | the repository, then their subscription is linked to their account. |
| 172 | 175 | On the /login page is a link to a page to control their subscription. |
| 173 | 176 | |
| 174 | 177 | For users without logins, they can request a link to a page for |
| 175 | -controling their subscription on the /alerts or /unsubscribe page. | |
| 176 | -The link is sent via email, and includes the subscriberCode. | |
| 178 | +controling their subscription on the `/alerts` or `/unsubscribe` page. | |
| 179 | +The link is sent via email, and includes the `subscriberCode`. | |
| 177 | 180 | |
| 178 | 181 | Internal Processing Flow |
| 179 | 182 | ------------------------ |
| 180 | 183 | |
| 181 | -Almost all of the email notification code is found in the "src/email.c" | |
| 184 | +Almost all of the email notification code is found in the `src/email.c` | |
| 182 | 185 | source file. |
| 183 | 186 | |
| 184 | 187 | When email notifications are enabled, a trigger is created in the schema |
| 185 | -(the "email_trigger1" trigger) that adds a new entry to the | |
| 186 | -PENDING_ALERT table every time a row is added to the EVENT table. | |
| 187 | -During a "rebuild", the EVENT table is rebuilt from scratch, and we | |
| 188 | -do not want users to get notifications for every historical check-in, | |
| 189 | -so the trigger is disabled during "rebuild". | |
| 190 | - | |
| 191 | -Email notifications are sent out by the email_send_alerts() function. | |
| 192 | -This function is can be called by having a cron job invoke the | |
| 193 | -"fossil email exec" command. Or, if the email-autoexec setting is | |
| 194 | -enabled, then email_send_alerts() is invoked automatically after each | |
| 195 | -successful webpage is generated. The latter approach is used on the | |
| 196 | -Fossil self-hosting repository. The email_send_alerts() function is | |
| 188 | +(the `email_trigger1` trigger) that adds a new entry to the | |
| 189 | +`PENDING_ALERT` table every time a row is added to the `EVENT` table. | |
| 190 | +During a `fossil rebuild`, the `EVENT` table is rebuilt from scratch; since we | |
| 191 | +do not want users to get notifications for every historical check-in, | |
| 192 | +the trigger is disabled during `rebuild`. | |
| 193 | + | |
| 194 | +Email notifications are sent out by the `email_send_alerts()` function. | |
| 195 | +This function is can be called by having a cron job invoke the | |
| 196 | +`fossil email exec` command. Or, if the email-autoexec setting is | |
| 197 | +enabled, then `email_send_alerts()` is invoked automatically after each | |
| 198 | +successful webpage is generated. The latter approach is used on the | |
| 199 | +Fossil self-hosting repository. The `email_send_alerts()` function is | |
| 197 | 200 | a no-op (obviously) if there are no pending events to be sent. |
| 198 | 201 | |
| 199 | 202 | Digests are handled by recording the time of the last digest in the |
| 200 | -"email-last-digest" setting, and only sending a new digest if the | |
| 203 | +`email-last-digest` setting, and only sending a new digest if the | |
| 201 | 204 | current time is one day or later after the last digest. |
| 202 | 205 | |
| 203 | 206 | Individual emails are sent to each subscriber. I ran tests and found |
| 204 | -that I could send about 1200 emails/second, which is fast enough so that | |
| 207 | +that I could send about 1200 emails/second, which is fast enough that | |
| 205 | 208 | I do not need to resort to trying to notify multiple subscribers with |
| 206 | 209 | a single email. Because each subscriber gets a separate email, the |
| 207 | 210 | system can include information in the email that is unique to the |
| 208 | 211 | subscriber, such as a link to the page to edit their subscription. That |
| 209 | -link includes the subscriberCode. | |
| 212 | +link includes the `subscriberCode`., | |
| 210 | 213 | |
| 211 | 214 | Other Notes |
| 212 | 215 | ----------- |
| 213 | 216 | |
| 214 | -The "fossil configuration pull subscriber" command pulls down the content | |
| 215 | -of the SUBSCRIBER table. This is intended to as a backup-only. It | |
| 217 | +The `fossil configuration pull subscriber` command pulls down the content | |
| 218 | +of the `SUBSCRIBER` table. This is intended to as a backup-only. It | |
| 216 | 219 | is not desirable to have two or more systems sending emails to the |
| 217 | 220 | same people for the same repository, as that would mean users would |
| 218 | -receive duplicate emails. Hence the settings that control email | |
| 219 | -notifications are not transmitted with the pull. The "push", "export", | |
| 220 | -and "import" commands all work similarly | |
| 221 | +receive duplicate emails. Hence, the settings that control email | |
| 222 | +notifications are not transmitted with the pull. The `push`, `export`, | |
| 223 | +and `import` commands all work similarly. | |
| 221 | 224 |
| --- www/emaildesign.md | |
| +++ www/emaildesign.md | |
| @@ -22,11 +22,11 @@ | |
| 22 | |
| 23 | |
| 24 | * <b>SUBSCRIBER</b> → |
| 25 | The subscriber table records the email address for people who |
| 26 | want to receive email notifications. Each subscriber has a |
| 27 | "subscriberCode" which is a random 32-byte blob that uniquely |
| 28 | identifies the subscriber. There are also fields to indicate |
| 29 | what kinds of notifications the subscriber wishes to receive, |
| 30 | whether or not the email address of the subscriber has been |
| 31 | verified, etc. |
| 32 | |
| @@ -55,11 +55,11 @@ | |
| 55 | being a user. |
| 56 | |
| 57 | Sending Email Messages |
| 58 | ---------------------- |
| 59 | |
| 60 | Fossil expects to interact with an external mail agent. |
| 61 | There are currently three different methods for sending outbound |
| 62 | email messages from Fossil to the external mail agent: |
| 63 | |
| 64 | 1. <b>"pipe"</b> → Invoke an external command that accepts |
| 65 | the email message on standard input. This is useful if the |
| @@ -101,10 +101,13 @@ | |
| 101 | There is a utility command-line program named |
| 102 | ["tools/decode-email.c"](/file/tools/decode-email.c) in |
| 103 | the Fossil source tree. If you compile this program, you can use it |
| 104 | to convert the base64 transfer-encoding into human-readable output for |
| 105 | testing and debugging. |
| 106 | |
| 107 | Receiving Email Messages |
| 108 | ------------------------ |
| 109 | |
| 110 | Inbound email messages (for example bounces from failed notification |
| @@ -140,30 +143,30 @@ | |
| 140 | -------------------------- |
| 141 | |
| 142 | When anonymous passers-by on the internet sign up for email notifications, |
| 143 | their email address must first be verified. An email message is sent to |
| 144 | the address supplied inviting the user to click on a link. The link includes |
| 145 | the random 32-byte subscriberCode in hex. If anyone visits the link, the |
| 146 | email address is verified. |
| 147 | |
| 148 | There is no password. Knowledge of the subscriberCode is sufficient to |
| 149 | control the subscription. This is not a secure as a separate password, |
| 150 | but on the other hand it is easier for the average subscriber to deal |
| 151 | with in that they don't have to come up with yet another password. Also, |
| 152 | even if the subscriberCode is stolen, the worst that can happens is that |
| 153 | the thief can change your subscription settings. No PII (other than |
| 154 | the subscriber's email address) is available to an attacker with the |
| 155 | subscriberCode. Nor can knowledge of the subscriberCode lead to a |
| 156 | email flood or other annoyance attack, as far as I can see. |
| 157 | |
| 158 | If subscriberCodes are ever compromised, new ones can be generated |
| 159 | as follows: |
| 160 | |
| 161 | > UPDATE subscriber SET subscriberCode=randomblob(32); |
| 162 | |
| 163 | Perhaps the system be enhanced to randomize the |
| 164 | subscriberCodes periodically - say just before each daily digest |
| 165 | is sent out? |
| 166 | |
| 167 | User Control Of Their Subscription |
| 168 | ---------------------------------- |
| 169 | |
| @@ -170,51 +173,51 @@ | |
| 170 | If a user has a separate account with a login and password for |
| 171 | the repository, then their subscription is linked to their account. |
| 172 | On the /login page is a link to a page to control their subscription. |
| 173 | |
| 174 | For users without logins, they can request a link to a page for |
| 175 | controling their subscription on the /alerts or /unsubscribe page. |
| 176 | The link is sent via email, and includes the subscriberCode. |
| 177 | |
| 178 | Internal Processing Flow |
| 179 | ------------------------ |
| 180 | |
| 181 | Almost all of the email notification code is found in the "src/email.c" |
| 182 | source file. |
| 183 | |
| 184 | When email notifications are enabled, a trigger is created in the schema |
| 185 | (the "email_trigger1" trigger) that adds a new entry to the |
| 186 | PENDING_ALERT table every time a row is added to the EVENT table. |
| 187 | During a "rebuild", the EVENT table is rebuilt from scratch, and we |
| 188 | do not want users to get notifications for every historical check-in, |
| 189 | so the trigger is disabled during "rebuild". |
| 190 | |
| 191 | Email notifications are sent out by the email_send_alerts() function. |
| 192 | This function is can be called by having a cron job invoke the |
| 193 | "fossil email exec" command. Or, if the email-autoexec setting is |
| 194 | enabled, then email_send_alerts() is invoked automatically after each |
| 195 | successful webpage is generated. The latter approach is used on the |
| 196 | Fossil self-hosting repository. The email_send_alerts() function is |
| 197 | a no-op (obviously) if there are no pending events to be sent. |
| 198 | |
| 199 | Digests are handled by recording the time of the last digest in the |
| 200 | "email-last-digest" setting, and only sending a new digest if the |
| 201 | current time is one day or later after the last digest. |
| 202 | |
| 203 | Individual emails are sent to each subscriber. I ran tests and found |
| 204 | that I could send about 1200 emails/second, which is fast enough so that |
| 205 | I do not need to resort to trying to notify multiple subscribers with |
| 206 | a single email. Because each subscriber gets a separate email, the |
| 207 | system can include information in the email that is unique to the |
| 208 | subscriber, such as a link to the page to edit their subscription. That |
| 209 | link includes the subscriberCode. |
| 210 | |
| 211 | Other Notes |
| 212 | ----------- |
| 213 | |
| 214 | The "fossil configuration pull subscriber" command pulls down the content |
| 215 | of the SUBSCRIBER table. This is intended to as a backup-only. It |
| 216 | is not desirable to have two or more systems sending emails to the |
| 217 | same people for the same repository, as that would mean users would |
| 218 | receive duplicate emails. Hence the settings that control email |
| 219 | notifications are not transmitted with the pull. The "push", "export", |
| 220 | and "import" commands all work similarly |
| 221 |
| --- www/emaildesign.md | |
| +++ www/emaildesign.md | |
| @@ -22,11 +22,11 @@ | |
| 22 | |
| 23 | |
| 24 | * <b>SUBSCRIBER</b> → |
| 25 | The subscriber table records the email address for people who |
| 26 | want to receive email notifications. Each subscriber has a |
| 27 | `subscriberCode` which is a random 32-byte blob that uniquely |
| 28 | identifies the subscriber. There are also fields to indicate |
| 29 | what kinds of notifications the subscriber wishes to receive, |
| 30 | whether or not the email address of the subscriber has been |
| 31 | verified, etc. |
| 32 | |
| @@ -55,11 +55,11 @@ | |
| 55 | being a user. |
| 56 | |
| 57 | Sending Email Messages |
| 58 | ---------------------- |
| 59 | |
| 60 | Fossil expects to interact with an external [mail transfer agent][MTA]. |
| 61 | There are currently three different methods for sending outbound |
| 62 | email messages from Fossil to the external mail agent: |
| 63 | |
| 64 | 1. <b>"pipe"</b> → Invoke an external command that accepts |
| 65 | the email message on standard input. This is useful if the |
| @@ -101,10 +101,13 @@ | |
| 101 | There is a utility command-line program named |
| 102 | ["tools/decode-email.c"](/file/tools/decode-email.c) in |
| 103 | the Fossil source tree. If you compile this program, you can use it |
| 104 | to convert the base64 transfer-encoding into human-readable output for |
| 105 | testing and debugging. |
| 106 | |
| 107 | [MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent |
| 108 | |
| 109 | |
| 110 | Receiving Email Messages |
| 111 | ------------------------ |
| 112 | |
| 113 | Inbound email messages (for example bounces from failed notification |
| @@ -140,30 +143,30 @@ | |
| 143 | -------------------------- |
| 144 | |
| 145 | When anonymous passers-by on the internet sign up for email notifications, |
| 146 | their email address must first be verified. An email message is sent to |
| 147 | the address supplied inviting the user to click on a link. The link includes |
| 148 | the random 32-byte `subscriberCode` in hex. If anyone visits the link, the |
| 149 | email address is verified. |
| 150 | |
| 151 | There is no password. Knowledge of the `subscriberCode` is sufficient to |
| 152 | control the subscription. This is not a secure as a separate password, |
| 153 | but on the other hand it is easier for the average subscriber to deal |
| 154 | with in that they don't have to come up with yet another password. Also, |
| 155 | even if the `subscriberCode` is stolen, the worst that can happens is that |
| 156 | the thief can change your subscription settings. No PII (other than |
| 157 | the subscriber's email address) is available to an attacker with the |
| 158 | `subscriberCode`. Nor can knowledge of the `subscriberCode` lead to a |
| 159 | email flood or other annoyance attack, as far as I can see. |
| 160 | |
| 161 | If subscriberCodes are ever compromised, new ones can be generated |
| 162 | as follows: |
| 163 | |
| 164 | UPDATE subscriber SET subscriberCode=randomblob(32); |
| 165 | |
| 166 | Perhaps the system be enhanced to randomize the |
| 167 | `subscriberCodes` periodically - say just before each daily digest |
| 168 | is sent out? |
| 169 | |
| 170 | User Control Of Their Subscription |
| 171 | ---------------------------------- |
| 172 | |
| @@ -170,51 +173,51 @@ | |
| 173 | If a user has a separate account with a login and password for |
| 174 | the repository, then their subscription is linked to their account. |
| 175 | On the /login page is a link to a page to control their subscription. |
| 176 | |
| 177 | For users without logins, they can request a link to a page for |
| 178 | controling their subscription on the `/alerts` or `/unsubscribe` page. |
| 179 | The link is sent via email, and includes the `subscriberCode`. |
| 180 | |
| 181 | Internal Processing Flow |
| 182 | ------------------------ |
| 183 | |
| 184 | Almost all of the email notification code is found in the `src/email.c` |
| 185 | source file. |
| 186 | |
| 187 | When email notifications are enabled, a trigger is created in the schema |
| 188 | (the `email_trigger1` trigger) that adds a new entry to the |
| 189 | `PENDING_ALERT` table every time a row is added to the `EVENT` table. |
| 190 | During a `fossil rebuild`, the `EVENT` table is rebuilt from scratch; since we |
| 191 | do not want users to get notifications for every historical check-in, |
| 192 | the trigger is disabled during `rebuild`. |
| 193 | |
| 194 | Email notifications are sent out by the `email_send_alerts()` function. |
| 195 | This function is can be called by having a cron job invoke the |
| 196 | `fossil email exec` command. Or, if the email-autoexec setting is |
| 197 | enabled, then `email_send_alerts()` is invoked automatically after each |
| 198 | successful webpage is generated. The latter approach is used on the |
| 199 | Fossil self-hosting repository. The `email_send_alerts()` function is |
| 200 | a no-op (obviously) if there are no pending events to be sent. |
| 201 | |
| 202 | Digests are handled by recording the time of the last digest in the |
| 203 | `email-last-digest` setting, and only sending a new digest if the |
| 204 | current time is one day or later after the last digest. |
| 205 | |
| 206 | Individual emails are sent to each subscriber. I ran tests and found |
| 207 | that I could send about 1200 emails/second, which is fast enough that |
| 208 | I do not need to resort to trying to notify multiple subscribers with |
| 209 | a single email. Because each subscriber gets a separate email, the |
| 210 | system can include information in the email that is unique to the |
| 211 | subscriber, such as a link to the page to edit their subscription. That |
| 212 | link includes the `subscriberCode`., |
| 213 | |
| 214 | Other Notes |
| 215 | ----------- |
| 216 | |
| 217 | The `fossil configuration pull subscriber` command pulls down the content |
| 218 | of the `SUBSCRIBER` table. This is intended to as a backup-only. It |
| 219 | is not desirable to have two or more systems sending emails to the |
| 220 | same people for the same repository, as that would mean users would |
| 221 | receive duplicate emails. Hence, the settings that control email |
| 222 | notifications are not transmitted with the pull. The `push`, `export`, |
| 223 | and `import` commands all work similarly. |
| 224 |