Merge branch 'main' of lokilocker.com:SomeGuy/sessioncommunities.online

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 <repository-url>`
+- `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

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/
+- <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: <https://github.com/mdPlusPlus/sessioncommunities.online>
+- Lokinet Gitea: <https://lokilocker.com/SomeGuy/sessioncommunities.online>
+
+If your favourite Session community is missing a language flag,
 you can issue a pull request here:
-- https://github.com/mdPlusPlus/sessioncommunities.online-languages/
 
+- <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`.

php/getenv.php

@@ -1,12 +1,23 @@
 <?php
 	$PROJECT_ROOT = dirname(__FILE__);
 	
-	while (!file_exists("$PROJECT_ROOT/.phpenv")) {
-		if ($PROJECT_ROOT == "/" || $PROJECT_ROOT == "") 
-			throw new RuntimeException("Could not find .phpenv file.");
-		$PROJECT_ROOT = dirname($PROJECT_ROOT);
-	}
-	
+	(function(){
+		global $PROJECT_ROOT;
+
+		$root_previous = "";
+
+		while (!file_exists("$PROJECT_ROOT/.phpenv")) {
+			if (
+				$PROJECT_ROOT == "/" ||
+				$PROJECT_ROOT == "" ||
+				$PROJECT_ROOT == $root_previous
+			) 
+				throw new RuntimeException("Could not find .phpenv file.");
+			$root_previous = $PROJECT_ROOT;
+			$PROJECT_ROOT = dirname($PROJECT_ROOT);
+		}
+	})();
+
 	require_once "$PROJECT_ROOT/.phpenv";
 	
 	// set_include_path(get_include_path() . PATH_SEPARATOR . $PROJECT_ROOT);

php/utils/server-utils.php

@@ -21,7 +21,7 @@
 	function truncate($url, $len) {
 		return (strlen($url) > $len + 3)
 			? substr($url, 0, $len).'...'
-			: $string;
+			: $url;
 	}
 	
 	/*