Fossil SCM
More random and slightly incoherient notes on the www/emaildesign.md document.
Commit
6f0e0598ce5db256b191be601573cb67e8af177dd4ccd17694e08b2957de4ea6
Parent
f5eb03f5e585cdd…
1 file changed
+84
-1
+84
-1
| --- www/emaildesign.md | ||
| +++ www/emaildesign.md | ||
| @@ -9,11 +9,11 @@ | ||
| 9 | 9 | This document assumes expert-level systems knowledge. A separate |
| 10 | 10 | tutorial for setting up email notification by non-experts will be |
| 11 | 11 | generated once the email notification system stabilizes. |
| 12 | 12 | |
| 13 | 13 | Email notification is under active development as of this writing |
| 14 | -(2018-06-23). Check back frequently for updates. | |
| 14 | +(2018-06-25). Check back frequently for updates. | |
| 15 | 15 | |
| 16 | 16 | Data Design |
| 17 | 17 | ----------- |
| 18 | 18 | |
| 19 | 19 | There are three new tables in the repository database. These tables |
| @@ -133,5 +133,88 @@ | ||
| 133 | 133 | |
| 134 | 134 | Test command: |
| 135 | 135 | |
| 136 | 136 | * The [test-alert](/help?cmd=test-alert) command |
| 137 | 137 | * The [test-add-alerts](/help?cmd=test-add-alerts) command |
| 138 | + | |
| 139 | +Email Address Verification | |
| 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 | +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 | |
| 138 | 221 |
| --- www/emaildesign.md | |
| +++ www/emaildesign.md | |
| @@ -9,11 +9,11 @@ | |
| 9 | This document assumes expert-level systems knowledge. A separate |
| 10 | tutorial for setting up email notification by non-experts will be |
| 11 | generated once the email notification system stabilizes. |
| 12 | |
| 13 | Email notification is under active development as of this writing |
| 14 | (2018-06-23). Check back frequently for updates. |
| 15 | |
| 16 | Data Design |
| 17 | ----------- |
| 18 | |
| 19 | There are three new tables in the repository database. These tables |
| @@ -133,5 +133,88 @@ | |
| 133 | |
| 134 | Test command: |
| 135 | |
| 136 | * The [test-alert](/help?cmd=test-alert) command |
| 137 | * The [test-add-alerts](/help?cmd=test-add-alerts) command |
| 138 |
| --- www/emaildesign.md | |
| +++ www/emaildesign.md | |
| @@ -9,11 +9,11 @@ | |
| 9 | This document assumes expert-level systems knowledge. A separate |
| 10 | tutorial for setting up email notification by non-experts will be |
| 11 | generated once the email notification system stabilizes. |
| 12 | |
| 13 | Email notification is under active development as of this writing |
| 14 | (2018-06-25). Check back frequently for updates. |
| 15 | |
| 16 | Data Design |
| 17 | ----------- |
| 18 | |
| 19 | There are three new tables in the repository database. These tables |
| @@ -133,5 +133,88 @@ | |
| 133 | |
| 134 | Test command: |
| 135 | |
| 136 | * The [test-alert](/help?cmd=test-alert) command |
| 137 | * The [test-add-alerts](/help?cmd=test-add-alerts) command |
| 138 | |
| 139 | Email Address Verification |
| 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 | 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 |