From 99c06f43085ac3fdec47d0a869df119f09903324 Mon Sep 17 00:00:00 2001 From: gravel Date: Tue, 23 May 2023 22:25:14 +0000 Subject: [PATCH] Update wording, add policy & superscript links --- .phpenv | 2 + CONTRIBUTING.md | 18 +++++-- README.md | 84 +++++++++++---------------------- languages/README.md | 26 ++++------ sites/+components/qr_modals.php | 5 +- sites/index.php | 9 ++-- 6 files changed, 62 insertions(+), 82 deletions(-) diff --git a/.phpenv b/.phpenv index 7487b2f..968940f 100644 --- a/.phpenv +++ b/.phpenv @@ -11,6 +11,8 @@ $ROOM_ICONS="$DOCUMENT_ROOT/icons"; $ROOM_ICONS_RELATIVE="icons"; + $REPOSITORY_CANONICAL_URL="https://codeberg.org/gravel/sessioncommunities.online"; + include_once "$PROJECT_ROOT/php/utils/logging.php"; // Read the -v|--verbose option increasing logging verbosity to debug. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5159245..540e87b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,7 @@ - `make` - `entr` to watch for file changes - `xdg-open` link handler to invoke browser +- `libgd` (`php-gd`, `phpX.Y-gd`) for downsizing images - patience ### Cloning or updating the repository @@ -17,20 +18,29 @@ Ensure the consistency of the `languages` submodule by using the following optio - `git clone --recurse-submodules ` - `git pull --recurse-submodules` +### Official repositories + +- Codeberg: +- Lokinet Gitea (mirror): +- GitHub (archive): +- Lokinet Gitea (archive): + +### Structure + +[`fetch-servers.php`](php/fetch-servers.php) queries available servers, and [`generate-html.php`](php/generate-html.php>) generates static HTML. Static HTML is generated from the [`sites`](sites) directory to the [`output`](output) directory, which additionally contains static assets. All contents of `sites` are invoked to produce a HTML page unless they are prefixed with a `+` sign. + ### Development Run at least once: `make fetch` to query servers. This can take around 5 minutes. Run when developing: `make dev` to watch for changes & serve HTML locally in browser. -Does not respond to new files. See [`Makefile`](Makefile) for more details. ### Running your own copy -- point your webserver at the `output` folder -- install systemd services from the `systemd` folder or an equivalent timer -- `session_sudoers`: TBD +- point your webserver at the [`output`](output/) folder +- install and enable systemd services from the [`systemd`](systemd/) folder or an equivalent timer ## Code style guidelines diff --git a/README.md b/README.md index 7763c1c..214b500 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,51 @@ -# Crawl lists of active Session Communities - -## What does this site do? - -This script crawls known sources of published Session Communities, -queries their servers for available information and -displays this information as a static HTML page. -The results of this can be viewed on . +# Self-updating list of Session Communities ## What is Session? -Session is a private messaging app that protects your meta-data, +[Session](https://getsession.org/) is a private messaging app that protects your meta-data, encrypts your communications, and makes sure your messaging activities leave no digital trail behind. - - -## Details -### Which sources are crawled? - -Currently this script crawls the following sites: - -- -- -- - -Additionally, [a few other servers are hardcoded](php/servers/known-servers.php). +## What does this site do? -### How does this work? +Session Communities are public chatrooms accessible from within Session Messenger. +This web project crawls known sources of Session Communities, and +displays information about them as a static HTML page. +[See live](https://sessioncommunities.online/). -The [`update-listing.php`](php/update-listing.php) script invokes the following two PHP scripts: [`fetch-servers.php`](php/fetch-servers.php) to query available servers, and [`generate-html.php`](php/generate-html.php>) to generate the static HTML. +## How do I get my Community listed? -The querying logic consists of these steps: +**Answer**: Submit your Community to one of our [upstream sources](#which-sources-do-you-crawl), or better yet, create another page with links to your favorite Communities for more redundancy. -1. Fetching source HTML: `query_known_sources()` -1. Extracting Session join URLs from the HTML: `parse_join_links()` -1. Building server instances from join URLs: `CommunityServer::from_join_urls()` -1. Adding known servers to list: `CommunityServer::from_known_hosts()` -1. Merging servers based on URL: `CommunityServer::dedupe_by_url()` -1. Making sure servers are online and querying rooms & pubkeys: -`CommunityServer::poll_reachable()` -1. Merging servers based on public keys: `CommunityServer::dedupe_by_pubkey()` +If your Community does not appear on our list: -Static HTML is generated from the [`sites`](sites) directory to the [`output`](output) directory, which additionally contains static assets. All contents of `sites` are invoked to produce a HTML page unless they are prefixed with a `+` sign. +- first, confirm it is listed on an upstream source, +- verify it can be joined from the app, and +- check in our page footer that the list has been updated recently. -### Work around bad routing to Chinese servers +If your Community still does not appear on our list, please [contact us](#contact-us). Note that poor connectivity may affect our ability to list Communities in regions affected by internet censorship. -Depending on your location, it is possible for you to get really bad routing to -SOGS servers behind the [GFW](https://en.wikipedia.org/wiki/Great_Firewall). In this case, -the initial connection is still successful, but you'll never receive -any actual content and the retrieval attempt will simply time out. -This happens randomly. To make sure this won't affect the results, we simply -check whether the server is online (the initial connection being successful), -and then retry a lot of times with a short timeout -until we eventually get the content. -The details can be seen in [`curl_get_contents()`](php/utils/utils.php). +## Which sources do you crawl? -### Official repositories +Communities displayed come from a variety of sources: -- Codeberg: -- Lokinet Gitea (mirror): -- GitHub (former official repository): -- Lokinet Gitea (former mirror): +- , +- , +- , +- [a few hardcoded servers found on the internet](php/servers/known-servers.php). -If your favourite Session community is missing a language flag, read [this](languages/README.md) on how to add a flag. +## Contributing -Alternatively, support this issue on Oxen Github to make language tags a native feature: +See [CONTRIBUTING.md](CONTRIBUTING.md) for information about running the project and contributing code, or [languages/README.md](languages/README.md) to help add language labels for Communities. -- +## Policy -### Contributing +We require that content posted in Communities adheres to the Content Policy laid out in the [Session Terms of Service](https://getsession.org/terms-of-service). Additionally, we may consider Communities unsuitable for display if their content is in breach of copyright and/or encourages or instructs drug use. If Communities explicitly accept such content or fail to moderate such content, we may display these Communities only to users who have disabled JavaScript in their browser, or to none at all. We appreciate contact with and the continued vigilance of server operators to prevent any issues from arising that would lead to us de-listing your Community. -See [CONTRIBUTING.md](CONTRIBUTING.md). +We occassionally accept requests from server operators to de-list whole Community servers; this only applies in cases where we've previously listed them manually (read above about sources). If you feel our listing would be greatly detrimental to the users of your Communities, such as in cases where your Communities reveal sensitive information about your users, you may [contact us](#contact-us) to make such a request. Please note that Session Communities are not designed with private communication in mind and we reserve the right not to de-list your Communities in case they have been listed on one of our sources and/or in case you request to de-list only a subset of your Communities. -## Contact +## Contact us -To report issues, visit the Web Development Community on [caliban.org](http://sog.caliban.org/r/webdev). +To report issues, ask questions or make suggestions, visit the Web Development Community on [caliban.org](http://sog.caliban.org/r/webdev). -In case the issue cannot be resolved publicly, contact [gravel](https://codeberg.org/gravel/gravel) on Session as `gravel` (Registered Session ID). +In case your issue cannot be resolved publicly, contact [gravel](https://codeberg.org/gravel/gravel) on Session as `gravel` (Registered Session ID). diff --git a/languages/README.md b/languages/README.md index da97654..1a6167b 100644 --- a/languages/README.md +++ b/languages/README.md @@ -1,26 +1,18 @@ -# language associations +# Language information on sessioncommunities.online ## Contribute -To contribute, send your changes in the Web Development Community, or fork this repository and submit a pull request with your changes. +To help label Communities by language, send your labelings to us ([see contact info](../README.md#contact-us)), or fork this repository and submit a pull request with your changes (account required). -## Language entries +To make language tags a native feature, support this issue on Oxen Github. -Communities are identified by a string of the form `token+pubkey[:4]`, where: +- -- `token` is the internal name of the community room, -- `+` is a plus sign, -- `pubkey[:4]` are the first four characters of the server public key. +## File format -### Example +Communities are each identified by a short string. You can copy this identifier using the "Copy Community ID" button from within Community details. It should be of the form `roomname+xxxx`. -Given the following invite link: `http://open.getsession.org/session?public_key=a03c383cf63c3c4efe67acc52112a6dd734b3a946b9545f488aaa93da7991238` - -- the token is `session`, -- the first four characters of the public key are `a03c`, -- so the unique identifier is `session+a03c`. - -To add the language of this server, you would search for `a03c` and add or change the entry at `session+a03c`: +Language labels for communities are grouped by server for easy navigation: ```php // https://open.getsession.org/ @@ -34,6 +26,6 @@ To add the language of this server, you would search for `a03c` and add or chang ); ``` -To add a new server, copy the block of an existing server and remove all its entries. +To label a Community, you would search for the `xxxx` suffix (in this case `a03c`) in the [flags file](./language_flags.php) and add the appropriate entry. -Language flags can be copied from . +If you cannot any labels for this code, copy an existing block from another server & replace the entries with your own. If you have trouble entering language flags on your keyboard, you may find it helpful to copy them from . diff --git a/sites/+components/qr_modals.php b/sites/+components/qr_modals.php index 7501e60..c1f609e 100644 --- a/sites/+components/qr_modals.php +++ b/sites/+components/qr_modals.php @@ -38,7 +38,10 @@

- Language: help us label: diff --git a/sites/index.php b/sites/index.php index 26d2909..e66b6fb 100644 --- a/sites/index.php +++ b/sites/index.php @@ -86,6 +86,7 @@ unique Session Communities on servers have been found. (None hidden as JS is off) + why?

Last checked @@ -147,14 +148,14 @@