[[PageOutline]]

= GeniusWeb Parties Server =

This is the homepage of the GeniusWeb parties server.
This server can provide a list of runnable parties, and create running instances of specified parties on a HTPT GET request. When an instance is made, a websocket link to the running party is provided to the caller.

The GeniusWeb main page is [https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb here].


The Parties server runs on Tomcat 8 and is developed with Eclipse EE.

== Installation ==
* Install [​https://archive.apache.org/dist/tomcat/tomcat-8 apache-tomcat 8]. You can re-use an existing installation. 
* Download the parties server war file from [http://artifactory.ewi.tudelft.nl/artifactory/webapp/#/artifacts/browse/tree/General/libs-release-local/geniusweb/partiesserver the artifactory]. Go into the latest version of the partiesserver and download (right click) the war file. NOTICE: your browser must have cookies enabled to access the artifactory.
* Copy the downloaded war file into the tomcat webapps directory
* (Re)start tomcat 

Now your local partiesserver should be up and running. 

{{{#!td style="background: #fee"
NOTICE: The server provides URIs to connect with parties.
These URI's contain hard IP numbers that are determined automatically using InetAddress.getLocalHost.
If you have multiple network adapters, unexpected IP numbers may be generated.
}}}

== Upgrade
To upgrade, 
* Stop tomcat
* remove the old war file plus the unzipped version (if exists) from the tomcat webapps directory
* repeat the installation as above

= GUI 
After installing and starting, go to [http://localhost:8080/partiesserver-1.0.0] (replace 1.0.0 with the version you installed). You should get this webpage

[[Image(home.png)]]

Example parties are discussed on the [
can be found in [https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb#WritingapartyinJava GeniusWeb example parties]. 

== Adding or changing a Party

To change a profile or add a new party,

* Make sure the profiles server has been run (apache will unzip the war file)
* Locate the unzipped partiesserver folder inside your tomcat webapps directory
* locate the partiesrepo directory inside that folder. This folder contains all current parties
* Copy your new version of a party.jar over an existing one. Or copy a new party.jar into this folder. Make sure that you have the jar file with all dependencies.
* The parties should now show up in the "list of party files" on the server webpage. Make sure you force refresh the page as some browsers show only old cached data.
* If the file is visible in that list, but does not show up in list of "currently runnable parties" then the jar does not contain a valid party. Check the apache tomcat logs to see why the jar has been rejected. 

== Human GUI party
There is a humangui party available as example party. This party shows a GUI (graphical user interface) through which a human user can steer the negotiation manually. Download the party and install it as described above to use this party. Check the [https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb GeniusWeb core pages] for more detail. 

= Communication protocol
This section deals with the communication protocols of the  partiesserver. This is relevant if you need to communicate directly with it, e.g. when you build your own GUI or start up your own parties from a script.

Other implementations of a partiesserver should adhere to the same communication protocols to ensure compatibility with GeniusWeb.



== Context path
context path of a web application defines the URL that end users will access the application from. A simple context path like myapp means the web app can be accessed from a URL like ​{{{http://localhost:8080/partiesserver/}}}.

The services provided by the partiesserver are all relative to this context path. 
||path || description ||required||
||/ || parties server homepage with links to sub-services ||N||
||/available || available parties ||Y||
||/running || currently running parties || N ||
||/free || currently available (free) party-run slots || Y ||
||/run/<party name> || run the specified party ||Y ||
||/party/<party name> || connection to currently running party ||N||
||/partiesrepo/||Directory listing of available parties||N||
"required" means that all server implementations should implement this path, and follow the protocol for that path. 

Tech note: on the /run/<party name> requirement, we need this format {{{/run/<party>}}} so that we can extract the context path from a given party reference. This is needed because GeniusWeb internally passes around only party references. However some services need to access the other services, particularly {{{/free}}}

=== /info
returns general information [https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/wiki/WikiStart#serverobjects ServerInfo object], like this
{"freeSlots":4,"totalSlots":4}

The free slots are the slots that can accomodate more running parties, each running party requires a slot. The totalSlots indicates the total number of slots on this server, which is available when all parties have finished running.

=== /available
/available provide a list of available parties on the server.
When a client accesses the partiesserver at {{{ws:...partiesserver/websocket/available}}}, a websocket is created. This websocket sends the clients list as a JSON list, each list element containing a GeneralPartyInfo object. 

A GeneralPartyInfo object contains the following: 
{{{
	URI                          uri;
	geniusweb.party.Capabilities capabilities;
	String                       description;
}}}

The uri contains a http address that, when accessed, starts up a new instance of the party. This is discussed in more detail in the next section. 

A full, updated list is sent over the websocket every time the list changes.

In the geniusweb java implementation these fields are automatically generated from the parties contained in the jar files in the {{{partiesserver/partiesrepo}}} directory that was mentioned above. Other implementations might use a different scheme.

* On the server implementation provided here, the urls look like {{{http://...:8080/partiesserver/run/<party name>}}} 


=== /run/<party>
/run/<party> creates new running instance of a party
When a client does a http get with an URI as provided in the GeneralPartyInfo field above, the server tries to create a running instance of that party. There are two possible responses from the party server:

* If the party was launched sucessfully: the http get returns a websocket address (ws:...) as plain text on which the party can be contacted.
* If the party could not be launched (eg, not enough resources) the server returns error code 503 "Service Unavailable". The 503 including a message like {{{retry later at 1556631286760}}}. The message is kept human readable but the last element of the message must be a unix timestamp (milliseconds since 1970) containing the time at which to retry. To create this message, the server can either create a default (e.g. let the client retry after a fixed set time) or actually use the estimated termination times of the parties. The current available server does the latter. 

The "retry later" message must contain the text "retry later" and have the number as the last element of the returned string. The message must be sent as plain text and must be in the normal response channel (not the error channel). The reason is that in Tomcat, placing messages through the error channel result in a html-formatted response object that we can't decypher anymore automatically. The only way to get around that is to use the normal channel and set the error code manually. In a tomcat HttpServlet, this goes like this:

{{{
response.setStatus(HttpServletResponse.SC_SERVICE_UNAVAILABLE);
response.getWriter().append("retry later at " + time);
}}}

If the connection was succesful and thus the response was a websocket address, the websocket connection implements a {{{Connection<Inform, Action>}}}. This connection has the following protocol:
 * it accepts JSON-formatted Inform objects and these are passed into the party (see the the party module in GeniusWeb core)
 * can send JSON-formatted Action objects as requested by the agent (see the events module in GeniusWeb core)

All parties must be guaranteed to terminate at some time. 

=== /running
/running provides a websocket that continuously sends a list of currently running parties (each being a serialized RunningPartyInfo object containing the name, id , start and  (worst case) end time. 

=== /free

/free is just a plain (non-websocket) connection that immediately returns an integer number with the number of available slots for running new party instances at this moment.

=== Communicating with the party through the websocket
As mentioned, the /run command returns a websocket address through which communication with the running party instance takes place.

The connection thus created allows Inform JSON objects to be sent to the party, and Action JSON objects to be sent by the party. The protocol determines the meaning and order of these.

If the party throws an exception, this exception should cause the socket to close (as a party can only do Actions). A close reason can only have a 123 character explanation which generally is too short for stacktraces. It is recommended therefore that such explanation is a reasonably human readable abstract of the full cause. The full stacktrace can be shown/logged in full detail on the partyserver.  

== Detecting termination of a party
The partiesserver does not have a separate communication protocol to hear when parties have been terminated. Instead, the PartySocket (that the partiesserver provides for communication between the party and the server) is sniffed for characteristic termination events. The following events are considered indicative for termination:
1. The socket breaks, eg because one of the parties closes it, some network failure, etc.
2. The socket has reached its time-out. The time-out is initially set to 3 seconds which is assumed to be ample for setting up and configuring a party. When the socket detects a Settings object being sent to the party, it sets the time-out to settings.getProgress().getTerminationTime().
3. A "Finished" Inform object being sent to the party.


== Using the source code ==
You can download the source repository of rhe java implementation. Note that you don't need this if you just want to use the parties server to host your parties or to compile parties.

{{{
svn checkout https://tracinsy.ewi.tudelft.nl/pub/svn/GeniusWebPartiesServer/
}}}

Since this is a tomcat web application, you need Eclipse Enterprise edition if you want to run this from Eclipse. 
Also, to checkout from Eclipse, you need to prepare Eclipse for this. Check https://tracinsy.ewi.tudelft.nl/pubtrac/GeniusWeb/wiki/WikiStart

It is maven based so you only need maven to compile the code.