User Authentication (external)

It is important to note that nor the APE_Server or the APS framework handle user authentication. However the APS framework does provides you with methods that can be used to authenticate users using another source like your website user system. There are currently two ways on doing this, using the connect event, using eventPush or both.

1. Using the connect event

The connect event is triggered right before the client connects to the APE Server. You can use this event to perform an ajax request to the source that would validate the user's authenticity. Since you will be making an ajax request you must initially return false so the process of connecting to the APE Server is halted. To resume the connecting process you would call client.connect(). In this case you would conditionally call client.connect() form inside the ajax request callback function.

To illustrate the idea in code i'll be using jQuery to perform the ajax request in the code below:

	//Create new client object
	var client = new APS("localhost:6969");
	
	//Adds the `connect` event to the client
	client.on("connect", function(){

		//Check if the user's name is known
		if(!!client.user.name){

			//Ajax call to get the user info
			$.getJSON("script_to_get_user_info.php", function(data){

				//Check if the user is signed and its information is provided
				if(data.signed && data.user){

					//import the user information to the client.user object
					client.user = data.user;
					
					//Resumes the connecting process
					client.connect();
				}else{
					//User is not signed
					alert("SORRY NO REALTIME FOR YOU!");
				}
			});
			
			//Holds the connecting process
			return false;
		}
		
		//We have a name, continue connecting to the APE server
		return true;
	})
	
	//Subscribes to the channel `chat`
	client.sub("chat");

NOTE: the client.connect() will re-trigger the connect events so if your ajax callback function does not sets a value to client.user.name you might create a infinity loop in this specific example.

The code above is just an example and may have its vulnerability, you can further secure this method according with your setup and application.

2. Using eventPush

In this method you don't control who connects to server but who can send/publish to the server.eventPush is an option in the client. The way this method works is by routing all events after the user has been connected to the APE Server to an intermediary script. In this case events will be routed to a PHP script which would then be conditionally routed the APE Server.

You must set client.option.eventPush to the intermediary script path, this will also enable the re-routing of the events. For example:

client.option.eventPush = "events_relay_script.php";

Note that the intermediary script is not limited to be a PHP script. The ApePubSub package does includes a PHP class and API that eases the processing of events but you may create your own processing script/class for your preferred language.

For example if using the bundled PHP class your events_relay_script.php can be as simple as the code below:

<?php
	include("lib/APS.php");
	
	$aps = new APS("ape.ptejada.com");
	
	if(!isUserAuthenticated()) $aps->error("302", "You must login first");
	
	$aps->respond();
?>

The script assumes the function isUserAuthenticated() is your method to determine if user can send events to the server. If that function returns false than an error event would be sent to the client, cancelling the event been sent to the APE Server. In this case the error is 302, to handle this event on the client side you would have to listen for the error302 event like:

client.on("error302", function(errorCode, message){
    alert(message);
});

A brief documentation of the PHP APS class

For live examples and their source check the live demos eventPush Chat (source) and PHPapp (source).

Conclusion

In the first method using the connect event you can control/filter who can connect to the APE Server while in the second method using eventPush you can control/filter the events been send to the APE Server after users are connected. You can use both methods in your application for optimal results, all seemly integrated into your application overflow.