Emoji reference and such

2024-11-25 04:40:02 +01:00 · 2021-12-02 12:04:22 -05:00 · 2021-12-02 12:04:22 -05:00 · 29f2196376
commit 29f2196376
parent 62f4d9963e
8 changed files with 2049 additions and 29 deletions
--- a/docs/config.md
+++ b/docs/config.md
@ -24,6 +24,9 @@ variable before running the `ntfy` command (e.g. `export NTFY_LISTEN_HTTP=:80`).
 | Config option | Env variable | Format | Default | Description |
 |---|---|---|---|---|
 | `listen-http` | `NTFY_LISTEN_HTTP` | `[host]:port` | `:80` | Listen address for the HTTP web server |
+| `listen-https` | `NTFY_LISTEN_HTTPS` | `[host]:port` | - | Listen address for the HTTPS web server. If set, you also need to set `key-file` and `cert-file`. |
+| `key-file` | `NTFY_KEY_FILE` | *filename* | - | HTTPS/TLS private key file, only used if `listen-https` is set. |
+| `cert-file` | `NTFY_CERT_FILE` | *filename* | - | HTTPS/TLS certificate file, only used if `listen-https` is set. |
 | `firebase-key-file` | `NTFY_FIREBASE_KEY_FILE` | *filename* | - | If set, also publish messages to a Firebase Cloud Messaging (FCM) topic for your app. This is optional and only required to save battery when using the Android app. |
 | `cache-file` | `NTFY_CACHE_FILE` | *filename* | - | If set, messages are cached in a local SQLite database instead of only in-memory. This allows for service restarts without losing messages in support of the since= parameter. |
 | `cache-duration` | `NTFY_CACHE_DURATION` | *duration* | 12h | Duration for which messages will be buffered before they are deleted. This is required to support the `since=...` and `poll=1` parameter. |
@ -67,20 +70,43 @@ firebase-key-file: "/etc/ntfy/ntfy-sh-firebase-adminsdk-ahnce-9f4d6f14b5.json"
 ## Behind a proxy (TLS, etc.)

 !!! warning
-    If you are behind a proxy, you must set the `behind-proxy` flag. Otherwise all visitors are rate limited
+    If you are running ntfy behind a proxy, you must set the `behind-proxy` flag. Otherwise all visitors are rate limited
    as if they are one.

-**TLS/SSL*: ntfy does not support TLS at this time. 
-
-If you are running ntfy behind a proxy (e.g. nginx, HAproxy or Apache), you should set the `behind-proxy` flag. This will
-instruct the [rate limiting](#rate-limiting) logic to use the `X-Forwarded-For` header as the primary identifier 
+**Rate limiting:** If you are running ntfy behind a proxy (e.g. nginx, HAproxy or Apache), you should set the `behind-proxy` 
+flag. This will instruct the [rate limiting](#rate-limiting) logic to use the `X-Forwarded-For` header as the primary 
+identifier for a visitor, as opposed to the remote IP address. If the `behing-proxy` flag is not set, all visitors will
+be counted as one, because from the perspective of the ntfy server, they all share the proxy's IP address.

+**TLS/SSL:** ntfy supports HTTPS/TLS by setting the `listen-https` config option. However, if you are behind a proxy, it is
+recommended that TLS/SSL termination is done by the proxy itself.

 ## Rate limiting
-Rate limiting: Allowed GET/PUT/POST requests per second, per visitor:
- visitor-request-limit-burst is the initial bucket of requests each visitor has
- visitor-request-limit-replenish is the rate at which the bucket is refilled
+!!! info
+    Be aware that if you are running ntfy behind a proxy, you must set the `behind-proxy` flag. 
+    Otherwise all visitors are rate limited as if they are one.

+By default, ntfy runs without authentication, so it is vitally important that we protect the server from abuse or overload.
+There are various limits and rate limits in place that you can use to configure the server. Let's do the easy ones first:
+
+* `global-topic-limit` defines the total number of topics before the server rejects new topics. It defaults to 5000.
+* `visitor-subscription-limit` is the number of subscriptions (open connections) per visitor. This value defaults to 30.
+
+A **visitor** is identified by its IP address (or the `X-Forwarded-For` header if `behind-proxy` is set). All config 
+options that start with the word `visitor` apply only on a per-visitor basis.   
+
+In addition to the limits above, there is a requests/second limit per visitor for all sensitive GET/PUT/POST requests.
+This limit uses a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) (using Go's [rate package](https://pkg.go.dev/golang.org/x/time/rate)):
+
+Each visitor has a bucket of 60 requests they can fire against the server (defined by `visitor-request-limit-burst`). 
+After the 60, new requests will encounter a `429 Too Many Requests` response. The visitor request bucket is refilled at a rate of one
+request every 10s (defined by `visitor-request-limit-replenish`)
+
+* `visitor-request-limit-burst` is the initial bucket of requests each visitor has. This defaults to 60.
+* `visitor-request-limit-replenish` is the rate at which the bucket is refilled (one request per x). Defaults to 10s.
+
+During normal usage, you shouldn't encounter this limit at all, and even if you burst a few requests shortly (e.g. when you 
+reconnect after a connection drop), it shouldn't have any effect.

 ## Command line options
 ```
--- a/docs/emojis.md
+++ b/docs/emojis.md
--- a/docs/publish/index.md
+++ b/docs/publish/index.md
@ -115,6 +115,60 @@ a [title](#message-title), and [tag messages](#tags-emojis) 🥳 🎉. Here's an
  <figcaption>Urgent notification with tags and title</figcaption>
 </figure>

+## Message title
+The notification title is typically set to the topic short URL (e.g. `ntfy.sh/mytopic`). To override the title, 
+you can set the `X-Title` header (or any of its aliases: `Title`, `ti`, or `t`).
+
+=== "Command line (curl)"
+    ```
+    curl -H "X-Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
+    curl -H "Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
+    curl -H "t: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
+    ```
+
+=== "HTTP"
+    ``` http
+    POST /controversial HTTP/1.1
+    Host: ntfy.sh
+    Title: Dogs are better than cats
+    
+    Oh my ...
+    ```
+
+=== "JavaScript"
+    ``` javascript
+    fetch('https://ntfy.sh/controversial', {
+        method: 'POST',
+        body: 'Oh my ...',
+        headers: { 'Title': 'Dogs are better than cats' }
+    })
+    ```
+
+=== "Go"
+    ``` go
+    req, _ := http.NewRequest("POST", "https://ntfy.sh/controversial", strings.NewReader("Oh my ..."))
+    req.Header.Set("Title", "Dogs are better than cats")
+    http.DefaultClient.Do(req)
+    ```
+
+=== "PHP"
+    ``` php
+    file_get_contents('https://ntfy.sh/controversial', false, stream_context_create([
+        'http' => [
+            'method' => 'POST',
+            'header' =>
+                "Content-Type: text/plain\r\n" .
+                "Title: Dogs are better than cats",
+            'content' => 'Oh my ...'
+        ]
+    ]));
+    ```
+
+<figure markdown>
+  ![notification with title](../static/img/notification-with-title.png){ width=500 }
+  <figcaption>Detail view of notification with title</figcaption>
+</figure>
+
 ## Message priority
 All messages have a priority, which defines how urgently your phone notifies you. You can set custom
 notification sounds and vibration patterns on your phone to map to these priorities (see [Android config](../subscribe/phone.md)).
@ -182,26 +236,99 @@ You can set the priority with the header `X-Priority` (or any of its aliases: `P
 </figure>

 ## Tags & emojis 🥳 🎉
-You can tag messages with emojis (or other relevant strings). If a tag matches a <a href="https://raw.githubusercontent.com/github/gemoji/master/db/emoji.json">known emoji short code</a>,
-it will be converted to an emoji. If it doesn't match, it will be listed below the notification. This is useful
-for things like warnings and such (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. which script the
-message came from, ...).
+You can tag messages with emojis and other relevant strings:

-You can set tags with the `X-Tags` header (or any of its aliases: `Tags`, or `ta`).
-Use <a href="https://raw.githubusercontent.com/github/gemoji/master/db/emoji.json">this reference</a>
-to figure out what tags can be converted to emojis. In the example below, the tag "warning" matches the emoji ⚠️,
-the tag "ssh-login" doesn't match and will be displayed below the message.
+* **Emojis**: If a tag matches an [emoji short code](../emojis.md), it'll be converted to an emoji and prepended 
+  to title or message.
+* **Other tags:** If a tag doesn't match, it will be listed below the notification. 

-```
-$ curl -H "Tags: warning,ssh-login" -d "Unauthorized SSH access" ntfy.sh/mytopic
-{"id":"ZEIwjfHlSS",...,"tags":["warning","ssh-login"],"message":"Unauthorized SSH access"}
-```
+This feature is useful for things like warnings (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. script 
+names, hostnames, etc.). Use [the emoji short code list](../emojis.md) to figure out what tags can be converted to emojis. 
+Here's an **excerpt of emojis** I've found very useful in alert messages:

-## Message title
-The notification title is typically set to the topic short URL (e.g. `ntfy.sh/mytopic`.
-To override it, you can set the `X-Title` header (or any of its aliases: `Title`, `ti`, or `t`).
+<table class="remove-md-box"><tr>
+<td>
+    <table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
+    <tr><td><code>+1</code></td><td>👍️</td></tr>
+    <tr><td><code>partying_face</code></td><td>🥳</td></tr>
+    <tr><td><code>tada</code></td><td>🎉</td></tr>
+    <tr><td><code>heavy_check_mark</code></td><td>✔️</td></tr>
+    <tr><td><code>loudspeaker</code></td><td>📢</td></tr>
+    <tr><td>...</td><td>...</td></tr>
+    </tbody></table>
+</td>
+<td>
+    <table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody> 
+    <tr><td><code>-1</code></td><td>👎️</td></tr>
+    <tr><td><code>warning</code></td><td>⚠️</td></tr>
+    <tr><td><code>rotating_light</code></td><td>️🚨</td></tr>
+    <tr><td><code>triangular_flag_on_post</code></td><td>🚩</td></tr>
+    <tr><td><code>skull</code></td><td>💀</td></tr>
+    <tr><td>...</td><td>...</td></tr>
+    </tbody></table>
+</td>
+<td>
+    <table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>
+    <tr><td><code>facepalm</code></td><td>🤦</td></tr>
+    <tr><td><code>no_entry</code></td><td>⛔</td></tr>
+    <tr><td><code>no_entry_sign</code></td><td>🚫</td></tr>
+    <tr><td><code>cd</code></td><td>💿</td></tr> 
+    <tr><td><code>computer</code></td><td>💻</td></tr>
+    <tr><td>...</td><td>...</td></tr>
+    </tbody></table>
+</td>
+</tr></table>
+
+You can set tags with the `X-Tags` header (or any of its aliases: `Tags`, or `ta`). Specify multiple tags by separating
+them with a comma, e.g. `tag1,tag2,tag3`.
+
+=== "Command line (curl)"
+    ```
+    curl -H "X-Tags: warning,mailsrv13,daily-backup" -d "Backup of mailsrv13 failed" ntfy.sh/backups
+    curl -H "Tags: horse,unicorn" -d "Unicorns are just horses with unique horns" ntfy.sh/backups
+    curl -H ta:dog -d "Dogs are awesome" ntfy.sh/backups
+    ```
+
+=== "HTTP"
+    ``` http
+    POST /backups HTTP/1.1
+    Host: ntfy.sh
+    Tags: warning,mailsrv13,daily-backup
+    
+    Backup of mailsrv13 failed
+    ```
+
+=== "JavaScript"
+    ``` javascript
+    fetch('https://ntfy.sh/backups', {
+        method: 'POST',
+        body: 'Backup of mailsrv13 failed',
+        headers: { 'Tags': 'warning,mailsrv13,daily-backup' }
+    })
+    ```
+
+=== "Go"
+    ``` go
+    req, _ := http.NewRequest("POST", "https://ntfy.sh/backups", strings.NewReader("Backup of mailsrv13 failed"))
+    req.Header.Set("Tags", "warning,mailsrv13,daily-backup")
+    http.DefaultClient.Do(req)
+    ```
+
+=== "PHP"
+    ``` php
+    file_get_contents('https://ntfy.sh/backups', false, stream_context_create([
+        'http' => [
+            'method' => 'POST',
+            'header' =>
+                "Content-Type: text/plain\r\n" .
+                "Tags: warning,mailsrv13,daily-backup",
+            'content' => 'Backup of mailsrv13 failed'
+        ]
+    ]));
+    ```
+
+<figure markdown>
+  ![priority notification](../static/img/notification-with-tags.png){ width=500 }
+  <figcaption>Detail view of notifications with tags</figcaption>
+</figure>

-```
-curl -H "Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/mytopic<
-```
-        
--- a/docs/static/css/extra.css
+++ b/docs/static/css/extra.css
@ -2,3 +2,13 @@ figure img {
    border-radius: 7px;
    filter: drop-shadow(3px 3px 5px #ccc);
 }
+
+.remove-md-box {
+    background: none;
+    border: none;
+    margin: 0 auto;
+}
+
+.remove-md-box td {
+    padding: 0 10px
+}
--- a/docs/static/img/notification-with-tags.png
+++ b/docs/static/img/notification-with-tags.png
--- a/docs/static/img/notification-with-title.png
+++ b/docs/static/img/notification-with-title.png
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -79,7 +79,8 @@ nav:
        - "Polling": subscribe/poll.md
 - "Other things":
  - "Examples": examples.md
-  - "FAQs": faq.md
+  - "Emojis 🥳 🎉": emojis.md
  - "Development": develop.md
+  - "FAQs": faq.md


--- a/scripts/emoji-convert.sh
+++ b/scripts/emoji-convert.sh
@ -7,10 +7,11 @@ SCRIPTDIR="$(cd "$(dirname "$0")" && pwd)"
 ROOTDIR="$(cd "$(dirname "$0")/.." && pwd)"

 if [ -z "$1" ]; then
-    echo "Syntax: $0 FILE.(js|json)"
+    echo "Syntax: $0 FILE.(js|json|md)"
    echo "Example:"
    echo "  $0 emoji-converted.json"
    echo "  $0 $ROOTDIR/server/static/js/emoji.js"
+    echo "  $0 $ROOTDIR/docs/emojis.md"
    exit 1
 fi

@ -19,6 +20,30 @@ if [[ "$1" == *.js ]]; then
 // Original data source: https://github.com/github/gemoji/blob/master/db/emoji.json
 const rawEmojis = " > "$1"
    cat "$SCRIPTDIR/emoji.json" | jq -rc 'map({emoji: .emoji,aliases: .aliases})' >> "$1"
+elif [[ "$1" == *.md ]]; then
+  echo "# Emoji reference
+
+<!-- This file was generated by scripts/emoji-convert.sh -->
+
+You can [tag messages](../publish/#tags-emojis) with emojis 🥳 🎉 and other relevant strings. Matching tags are automatically
+converted to emojis. This is a reference of all supported emojis. To learn more about the feature, please refer to the
+[tagging and emojis page](../publish/#tags-emojis).
+
+<table class="remove-md-box"><tr>
+" > "$1"
+
+  count="$(cat "$SCRIPTDIR/emoji.json" | jq -r '.[] | .emoji' | wc -l)"
+  percolumn=$(($count / 3)) # This will misbehave if the count is not divisible by 3
+  for col in 0 1 2; do
+    from="$(($col * $percolumn + 1))"
+    to="$(($col * $percolumn + 1 + $percolumn))"
+    echo "<td><table><thead><tr><th>Tag</th><th>Emoji</th></tr></thead><tbody>" >> "$1"
+    cat "$SCRIPTDIR/emoji.json" \
+      | jq -r '.[] | "<tr><td><code>" + .aliases[0] + "</code></td><td>" + .emoji + "</td></tr>"' \
+      | sed -n "${from},${to}p" >> "$1"
+    echo "</tbody></table></td>" >> "$1"
+  done
+  echo "</tr></table>" >> "$1"
 else
  cat "$SCRIPTDIR/emoji.json" | jq -rc 'map({emoji: .emoji,aliases: .aliases})' > "$1"
 fi