diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1cb5dc1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contribution guidelines + +## Development environment + +### Prerequisites + +- PHP (version TBD) +- `make` +- `entr` to watch for file changes +- `xdg-open` link handler to invoke browser +- patience + +### Cloning or updating the repository + +Ensure the consistency of the `languages` submodule by using the following options: + +- `git clone --recurse-submodules ` +- `git pull --recurse-submodules` + +### 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 + +## Code style guidelines + +### General + +**Indentation**: Tabs (4-wide) + +**Filename seperator**: Hyphen (`-`) + +### PHP + +**Identifier casing**: `snake_case` and `CONSTANT_CASE` + +**Comments and documentation**: TBD + +### HTML & CSS + +**Identifier casing**: `kebab-case`, occasional `snake_case` + +**Comments and documentation**: TBD + +### JavaScript + +**Identifier casing**: `camelCase` and `CONSTANT_CASE`, occasional `snake_case` + +**Comments and documentation**: [JSDoc](https://jsdoc.app/) + +## Contact + +- Web Development Session Community on [caliban.org](https://sog.caliban.org/) +- Project lead, querying logic, deployment, community filtering: `someguy` on Session +- Documentation, code quality, HTML generation, CSS, JS: `gravel` on Session diff --git a/README.md b/README.md index eebc2cf..0cab54f 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,17 @@ ## 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. +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 https://sessioncommunities.online/. ## What is Session? -Session is a private messaging app that protects your meta-data, -encrypts your communications, and makes sure your messaging activities -leave no digital trail behind. +Session is a private messaging app that protects your meta-data, +encrypts your communications, and makes sure your messaging activities +leave no digital trail behind. https://getsession.org/ @@ -22,58 +22,54 @@ https://getsession.org/ Currently this script crawls the following sites: -- https://github.com/GNU-Linux-libre/Awesome-Session-Group-List -- https://lokilocker.com/Mods/Session-Groups/wiki/Session-Open-Groups -- https://session.directory/ +- +- +- -Additionally, the following open community servers are polled: +Additionally, a few other servers are hardcoded, see [querying logic](php/fetch-servers.php). -- https://open.getsession.org -- http://13.233.251.36:8081 +### How does this work? -### Steps +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. + +The querying logic consists of these steps: 1. Fetching source HTML: `get_html_from_known_sources()` 1. Extracting Session invites from the HTML: `extract_join_links_from_html()` and `get_servers_from_join_links()` 1. Making sure servers are online: `reduce_servers()` -1. Querying the servers for all available rooms -and normalize active user numbers: `query_servers_for_rooms()` -1. De-duplicating servers based on public keys: +1. Querying the servers for all available rooms +and normalizing active user numbers: `query_servers_for_rooms()` +1. De-duplicating servers based on public keys: `get_pubkeys_of_servers()` and `reduce_addresses_of_pubkeys()` 1. Aggregating all server info & adding language data: `generate_info_arrays()` -1. Generating static HTML content: `generateHTML()` - -### Legacy support -Right now we fully support legacy SOGS servers, -although this support is likely going to be dropped soon, -since those servers can not even be joined anymore with current Session clients. -Dropping legacy support will also increase maintainability. +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. ### Work around bad routing to Chinese servers -Depending on your location, it is possible for you to get really bad routing to -SOGS servers behind the GFW. 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. +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. +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()`. ### Official repositories -- https://github.com/mdPlusPlus/sessioncommunities.online -- https://lokilocker.com/SomeGuy/sessioncommunities.online -If your favourite Session community is missing a language flag, +- GitHub: +- Lokinet Gitea: + +If your favourite Session community is missing a language flag, you can issue a pull request here: -- https://github.com/mdPlusPlus/sessioncommunities.online-languages/ +- ## Contact -If you want to contact me, you can add me on Session via my -[ONS](https://docs.oxen.io/using-the-oxen-blockchain/using-oxen-name-system): -"someguy" (without the quotes) +If you want to contact me, you can add me on Session via my +[ONS](https://docs.oxen.io/using-the-oxen-blockchain/using-oxen-name-system): +`someguy`. diff --git a/php/getenv.php b/php/getenv.php index baec93d..fd20799 100644 --- a/php/getenv.php +++ b/php/getenv.php @@ -1,12 +1,23 @@ $len + 3) ? substr($url, 0, $len).'...' - : $string; + : $url; } /*