sheepit-shadow-nabber/protocol.txt

=== Session creation ===

Url: Server url + "/server/config.php"
Parameters as GET:
    * login: User's login in plain text.
    * password: User's password in plain text.
    * version: Client's version, for example 3.3.1762.
    * os: Computer's operating system, at the moment only "windows", "mac" and "linux" are supported.
    * os_version: Full version of os, for example "Windows 8.1".
    * bits: Architecture size, at the moment only "32bit" and "64bit" are supported.
    * cpu_family: CPU's family, on linux it can be found in /proc/cpuinfo via the attribute "cpu family".
    * cpu_model: CPU's model, on linux it can be found in /proc/cpuinfo via the attribute "model".
    * cpu_model_name: CPU's model in human readable format, on linux it can be found in /proc/cpuinfo via the attribute "model name".
    * cpu_cores: Number of cores (or thread) available.
    * ram: Memory available (in kilobytes).
    * ram_max: Maximum memory allowed for renderer (in kilobytes).
    * extras (optional): Extra data used for the configuration.
    * hostname (optional): Hostname of the machine, useful for distinguishing multiple machines with the same hardware configuration. Only used for display on the website.
    * ui (optional): User interface used by the client, useful for statistics
    * headless: Is the machine is running headless (Eevee is not compatible with headless)
    * hwid: a pseudonymous hardware hash

Answer in case of error:
<?xml version="1.0" encoding="utf-8" ?>
<config status="X" />
where X:
    * 100 => No version given.
    * 101 => Client is too old.
    * 102 => Authentication failure.
    * 103 => WebSession has expired.
    * 104 => Missing parameter.
    * something else => Unknown error.

Answer with no error:
A status of "0" to specify everything is okay, publickey contains the public key for login, generated by the server, plus a list of URL paths for request, validation job, etc.
A path is provided for error, job request, job validation, download needed file, heartbeat (keepmealive), logout and speedtest results.
Also a speedtest element containing a url for each mirror leading to a payload for the ensuing speedtest.
The maximum duration between two heartbeats in seconds is given by the attribute "max-period".

<?xml version="1.0" encoding="utf-8" ?>
<config status="0" publickey="a public key">
    <request type="request-job" path="/server/request_job.php" />
    <request type="download-archive" path="/server/archive.php" />
    <request type="error" path="/server/error.php" />
    <request type="keepmealive" path="/server/keepmealive.php" max-period="1440" />
    <request type="logout" path="/account.php?mode=logout&amp;worker=1" />
    <request type="speedtest-answer" path="/server/speedtest.php" />
    <speedtest>
        <target url="https://static-frankfurt3-de.sheepit-renderfarm.com/scene/speedtest.zip" />
        <target url="https://static-murcia-es.sheepit-renderfarm.com/scene/speedtest.zip" />
        <target url="https://static-nuremberg-de.sheepit-renderfarm.com/scene/speedtest.zip" />
        <target url="https://static-roubaix-fr.sheepit-renderfarm.com/scene/speedtest.zip" />
        <target url="https://static-sg.sheepit-renderfarm.com/scene/speedtest.zip" />
        <target url="https://static-tx3-usa.sheepit-renderfarm.com/scene/speedtest.zip" />
        <target url="https://static-ut-usa.sheepit-renderfarm.com/scene/speedtest.zip" />
        <target url="https://static-va-usa.sheepit-renderfarm.com/scene/speedtest.zip" />
    </speedtest>
</config>

The client then performs a speedtest on these mirror urls and POSTs back the 3 fastest ones using the "speedtest-answer" endpoint, together with the transfer time for the payload:
<speedtest>
   <result target="https://static-roubaix-fr.sheepit-renderfarm.com/scene/speedtest.zip" speed="724155" ping="26"/>
   <result target="https://static-nuremberg-de.sheepit-renderfarm.com/scene/speedtest.zip" speed="674325" ping="33"/>
   <result target="https://static-frankfurt3-de.sheepit-renderfarm.com/scene/speedtest.zip" speed="566186" ping="26"/>
</speedtest>


=== Session end ===

Url: use the request type "logout" from the configuration answer.
No additional parameter is required.

=== Download renderer archive ===

Url: use the request type "download-archive" from the configuration answer.
Parameter as GET or POST:
    * type: "binary"
    * job: ID of the job

Answer:
No error: the file
On error: an 404 http code


=== Download job archive ===

Url: use the request type "download-archive" from the configuration answer.
Parameter as GET or POST:
    * type: "job"
    * job: ID of the job

Answer:
No error: the file
On error: an 404 http code


=== Job request ===

Url: use the request type "request-job" from the configuration answer.
Parameter as GET or POST:
    * computemethod: What compute types are available on this machine. 0 for CPU or GPU, 1 for CPU only, 2 for GPU only.
    * network_dl: Download speed in bytes/second
    * network_up: Upload speed in bytes/second
    * cpu_cores: Number of cores currently available for rendering (optional).
    * ram_max: Maximum memory allowed for renderer (in kilobytes).
    * rendertime_max: Maximum allowed render time in seconds, 0 means no time limit
    * gpu_type: GPU's type, (OPTIX)
    * gpu_model: Model name of the GPU available for rendering
    * gpu_ram: GPU memory size (in bytes)

Answer in case of error:
<?xml version="1.0" encoding="utf-8" ?>
<jobrequest status="X" />
where X:
    * 0   => No error
    * 200 => No job available, the client should wait few minutes before requesting a new job (typical value is 1 minute).
    * 201 => The client does not have rendering right.
    * 202 => Client's session is dead. Client should send another config request before requesting a new job.
    * 203 => Client's session has been disabled (usually because the client is sending broken frames). The client should alert the end user and logout.
    * 205 => No renderer is available for Client's hardware (pair of OS and architecture). For example, Blender is not available for MacOS 32bits.
    * 206 => Server is in maintenance mode, and is not issuing jobs (but it will keep the session alive). Try again in a few minutes.
    * 207 => Server is overloaded, and is not issuing jobs (but it will keep the session alive). Try again in a few minutes.
    * something else => unknown error
    
Answer with no error:
<?xml version="1.0" encoding="utf-8" ?>
<jobrequest status="0">
	<stats credits_session="0" credits_total="6318899" frame_remaining="36830" waiting_project="42" connected_machine="773" renderable_project="0" />
	<job id="1" use_gpu="1" archive_md5="db26b54689516484633b7d4855fb1567" path="compute-method.blend" frame="0340" synchronous_upload="1" validation_url="https%3A%2F%2Fsheepit-renderfarm.com%2Fserver%2Fsend_frame.php%3Fjob%3D1%26frame%3D0340" name="human readable name" password="some password">
		<renderer md5="05234503229a4660e428e8d227746d8d" commandline=".e --factory-startup --disable-autoexec -noaudio -b .c --engine CYCLES -o .o -f .f -x 1" update_method="remainingtime"/>
		<script>
			<!-- a server generated python script configuring the render with the right settings for the farm -->
		</script>
	</job>
</jobrequest>

stats => Some statistics about the session and the farm
	* where
		* credits_session => The points earned in this session
		* credits_total => Represents the total amount of points of this account
		* frame_remaining => How many frames are left to be rendered on the farm in total
		* waiting_project => How many projects are in the render queue
		* connected_machines => How many machines are connected to the farm right now
		* renderable_projects => How many projects are available to be rendered by this session/machine
job => an element containing information about the new job
	* where
		* job id => The job id
		* use_gpu => A flag selecting the render device (CPU/GPU) according to the session settings and the project (for example when a CPU+GPU session receives a CPU only project), 0 means false, 1 true
		* archive_md5 => The MD5 checksum of the project zip, used to verify integrity after download
		* path => The path to the blend file within the archive
		* frame => The frame number to be rendered
		* synchronous_upload => A flag indicating whether the job result can be queued up for uploading (0) or should be sent back immediately (1, only for the test frames)
		* validation_url => The URL to send the job validation to
		* name => The project name that will be displayed in the ui
		* password => The archive password

		renderer => An element containing information about the blender binary used for the job
			* where
				* md5 => The MD5 checksum of the binary archive, used to validate file integrity after download
				* commandline => Launch arguments for the blender executable
				* update_method => Whether to keep track of progress by remaining time (remainingtime) or render tile (by_tile)

		script => A server generated python script setting blender up with the right farm-related settings for the project

=== Job validation ===

Url: use the url of job's node for 'validationurl'.
Parameter as GET or POST:
    * job: Job ID
    * frame: Job's frame number
    * rendertime: Job's render time
    * preptime: Job's preparation time
    * file: Frame to validate as form-data post
    * memoryused (optional): Max memory used for the render
    * cores (optional): Number of cores used from the render
    * speedsamples (optional): Number of cycles samples done in 1 second
Parameter as form-urlencoded:
    * file: the frame to send   

Answer in case of error:
<?xml version="1.0" encoding="utf-8"?>
<jobvalidate status="X"/>
where X:
    * 0 => No error
    * 300 => Missing parameter in request.
    * 301 => Client generated a broken frame (usually an too old gpu who generated black frame).
    * 302 => File uploaded was not an image.
    * 303 => Failed to upload the image to the server.
    * 304 => Client's session is disabled or dead.
    * something else => unknown error

=== Session heartbeat ===

Url: use the request type "keepmealive" from the configuration answer.
Parameter as GET or POST:
    * job: ID of the rendering job
    * frame: Frame number of the rendering job
    * rendertime: current render time (optional)
    * remainingtime: current remaining time to render the frame (optional)
    * paused: whether the client is actively paused or not

Answer:
<?xml version="1.0" encoding="utf-8" ?>
<keepmealive status="X" />
where X:
    * 0 => No error.
    * 400 => Stop this job (usually because the job has been cancelled).

=== Error send ===

Url: use the request type "error" from the configuration answer.
Parameter as GET or POST:
	* type: X
		where X:
			* 1 => The client received a wrong configuration
			* 2 => Authentication with www failed
			* 3 => Client version too old
			* 4 => The session got disabled
			* 5 => Blender binary not available
			* 6 => Blender binary missing
			* 7 => Couldn't find a scene in the blend file
			* 8 => Rendering produced no output file
			* 9 => File download failed
			* 10 => Can not create directory
			* 11 => Network issue
			* 12 => Renderer crashed
			* 13 => Renderer failed due to running out of VRAM
			* 14 => Render process got killed by OS
			* 15 => Renderer is missing libraries
			* 16 => Process execution failed
			* 17 => OS not supported
			* 18 => CPU not supported
			* 19 => GPU not supported
			* 20 => Renderer got killed by user
			* 21 => Renderer failed due to running out of RAM
			* 22 => Renderer got killed by server
			* 23 => Renderer got killed due to exceeding the user time limit
			* 24 => Renderer crashed with a python error
			* 25 => Job validation failed
			* 26 => Final image is too large
			* 27 => Render engine not available
			* 99 => Unknown error
    * job: job ID
    * frame: job's frame number
    * render_time (optional): job's frame number
    * memoryused (optional): max memory used for the render (in kilo bytes)
Parameter as form-urlencoded:
    * file: the error log to send