Documentation

index.php

@@ -13,6 +13,9 @@
 	*	"Any appearance of design in the Program is purely coincidental and should not in any way be mistaken for evidence of thoughtful software construction."
 	*/
 
+	//	Preamble: Set your details here
+	//	This is where you set up your account's name and bio. You also need to provide a public/private keypair. The posting page is protected with a password that also needs to be set here.
+
 	//	Set up the Actor's information
 	$username = rawurlencode("example");	//	Encoded as it is often used as part of a URl
 	$realName = "E. Xample. Jr.";
@@ -27,13 +30,16 @@
 	//	Password for sending messages
 	$password = "P4ssW0rd";
 
+	//	Logging:
+	//	ActivityPub is a "chatty" protocol. This takes all the requests your server receives and saves them in `/logs/` as a datestamped text file.
+
 	// Get all headers and requests sent to this server
 	$headers     = print_r( getallheaders(), true );
 	$postData    = print_r( $_POST,    true );
 	$getData     = print_r( $_GET,     true );
 	$filesData   = print_r( $_FILES,   true );
 	$body        = json_decode( file_get_contents( "php://input" ), true );
-	$bodyData    = print_r( $input,    true );
+	$bodyData    = print_r( $body,     true );
 	$requestData = print_r( $_REQUEST, true );
 	$serverData  = print_r( $_SERVER,  true );
 
@@ -62,8 +68,9 @@
 		"Server Data: \n$serverData \n\n"
 	);
 
+	//	Routing:
 	//	The .htaccess changes /whatever to /?path=whatever
-	//	What path was requested?
+	//	This runs the function of the path requested.
 	$path = $_GET["path"];
 	switch ($path) {
 		case "":
@@ -86,8 +93,10 @@
 			die();
 	}
 
+	//	The [WebFinger Protocol](https://docs.joinmastodon.org/spec/webfinger/) is used to identify accounts.
+	//	It is requested with `example.com/.well-known/webfinger?resource=acct:username@example.com`
+	//	This server only has one user, so it ignores the query string and always returns the same details.
 	function webfinger() {
-		//	Display the WebFinger JSON
 		global $username, $server;
 
 		$webfinger = array(
@@ -105,9 +114,10 @@
 		die();
 	}
 
+	//	User:
+	//	Requesting `example.com/username` returns a JSON document with the user's information.
 	function username() {
-		//	Display the username JSON
+		global $username, $realName, $summary, $server, $key_public;
-		global $username, $realName, $server, $key_public;
 
 		$user = array(
 			"@context" => [
@@ -142,8 +152,10 @@
 		die();
 	}
 
+	//	Follower / Following:
+	// These JSON documents show how many users are following / followers-of this account.
+	// The information here is self-attested. So you can lie and use any number you want.
 	function following() {
-		//	Display the following JSON
 		global $server;
 
 		$following = array(
@@ -157,9 +169,7 @@
 		echo json_encode( $following );
 		die();
 	}
-
 	function followers() {
-		//	Display the followers JSON
 		global $server;
 		$followers = array(
 			  "@context" => "https://www.w3.org/ns/activitystreams",
@@ -173,8 +183,14 @@
 		die();
 	}
 
+	//	Inbox:
+	//	The `/inbox` is the main server. It receives all requests. 
+	//	This server only responds to "Follow" requests.
+	//	A remote server sends a follow request which is a JSON file saying who they are.
+	//	This code does not cryptographically validate the headers of the received message.
+	//	The name of the remote user's server is saved to a file so that future messages can be delivered to it.
+	//	An accept request is cryptographically signed and POST'd back to the remote server.
 	function inbox() {
-		//	Respond to InBox requests
 		global $body, $server, $username, $key_private;
 
 		//	Get the message and type
@@ -251,8 +267,11 @@
 		die();
 	}
 
+	//	Unique ID:
+	// Every message sent should have a unique ID. 
+	// This can be anything you like. Some servers use a random number.
+	// I prefer a date-sortable string.
 	function uuid() {
-		//	Date sortable UUID
 		return sprintf( "%08x-%04x-%04x-%04x-%012x",
 			time(),
 			mt_rand(0, 0xffff),
@@ -262,10 +281,13 @@
 		);
 	}
 
+	//	Headers:
+	// Every message that your server sends needs to be cryptographically signed with your Private Key.
+	// This is a complicated process. Please read https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/ for more information.
 	function generate_signed_headers( $message, $host, $path ) {
 		global $server, $username, $key_private;
 
-		//	Encode the message to JSON
+		//	Encode the message object to JSON
 		$message_json = json_encode( $message );
 
 		//	Location of the Public Key
@@ -309,8 +331,9 @@
 		return $headers;
 	}
 
+	// User Interface for Writing:
+	// This creates a basic HTML form. Type in your message and your password. It then POSTs the data to the `/send` endpoint.
 	function write() {
-		//	Display an HTML form for the user to enter a message.
 echo <<< HTML
 <!DOCTYPE html>
 <html lang="en-GB">
@@ -335,6 +358,9 @@ HTML;
 		die();
 	}
 
+	//	Send Endpoint:
+	//	This takes the submitted message and checks the password is correct.
+	//	It reads the `followers.json` file and sends the message to every server that is following this account.
 	function send() {
 		global $password, $server, $username, $key_private;