Command protocol

The Command protocol was evolved at Flipkart and is used by PHP processes(web-site content delivery application) to communicate with the fk-w3-agent. The fk-w3-agent is a Phantom predecessor proxy daemon. The Command protocol is defined as follows:

A Command has this structure:
+------------+---------+------------+--------------+---+---------------+------------+--------------+---+---------------+----+
| delim char | command | delim char | param name 1 | = | param value 1 | delim char | param name n | = | param value n | \n |
+------------+---------+------------+--------------+---+---------------+------------+--------------+---+---------------+----+
+------------+
| data bytes |
+------------+ 
where
 - Command and params appear on a single line terminating in '\n' char
 - 'delim char' is any non-ascii character
 - 'command' is an arbitrary sequence of characters
 - 'param name'='param value' can repeat any number of times. Are of type : arbitrary sequence of characters
 - 'data' is an arbitrary sequence of bytes
 
Response from Command execution has this structure:
 
+--------+----+
| status | \n |
+--------+----+
(or)
+--------+-------------+-------------+----+
| status | white space | data length | \n |
+--------+-------------+-------------+----+
+------------+
| data bytes |
+------------+

The Command protocol continues to be supported by Phantom. The Command protocol proxy requires following capabilities:

• Socket listener - that can receive Command requests. This is available as TCPNettyServer in the runtime module. A more efficient Unix Domain Sockets based listener, suitable for local access, is available as UDSNettyServer in the runtime-netty-uds and a Java Old I/O (OIO) variant is available as UDSOIOServer in the runtime-oio-uds module.
• Command Codecs - interpret Command protocol semantics. This is available in the runtime module.
• Request processing - processes Command protocol calls and relay it to the target handler. This is available in the runtime module.
• Resilience and fault tolerance integration - to support timeouts, synchronous and asynchronous invocation and fallbacks. This is available in the task module.

Follow the instructions below to configure your Command proxy:

• Create a file by name spring-proxy-listener-config.xml and configure the TCP or UDS socket listener, the Channel pipeline factory, Command proxy handler, and the Phantom registry and repository beans (or) simply copy this file from sample-task-proxy Maven module. Note: the path src/main/resources/external must be preserved as the location for this file. The following bean configurations are worth noting:

<bean id="commandBufferDecoder" class="com.flipkart.phantom.runtime.impl.server.netty.decoder.command.CommandBufferDecoder" scope="prototype"/>
<bean id="commandProcessingChannelHandler" class="com.flipkart.phantom.runtime.impl.server.netty.handler.command.CommandProcessingChannelHandler" scope="prototype">
    <property name="defaultChannelGroup" ref="defaultChannelGroup"/>
    <property name="repository" ref="taskHandlerRepository"/>
</bean>

• Create a file by name spring-proxy-handler-config.xml in the same location and configure the proxy beans like:

<bean class="com.flipkart.phantom.sample.handler.ArithmeticTaskHandler"></bean>

The following configuration options and features are worth noting:

• This example uses the TCP socket listener. You may use the UDS listener if required. Here again you have a choice of using either the Netty based UDS listener or the Java Old I/O based UDS listener.
• Sample configuration for using the Netty UDS listener:

<!-- UDS Server -->
<bean id="udsServer" class= "com.flipkart.phantom.runtime.impl.server.netty.UDSNettyServer">
    <property name="socketName" value="${proxy.core.server.uds.socketName}" />
    <property name="socketDir" value="${proxy.core.server.uds.socketDir}" />
    <property name="defaultChannelGroup" ref="defaultChannelGroup"/>
    <property name="pipelineFactory" ref="commandChannelPipelineFactoryUDS"/>
</bean>		 
<!--  ChannelHandlerPipelineFactory for Command processing -->
<bean id="commandChannelPipelineFactoryUDS" class="com.flipkart.phantom.runtime.impl.server.netty.ChannelHandlerPipelineFactory">
    <property name="channelHandlerBeanNamesMap">
        <map>
	    <entry key="commandBufferDecoder" value="commandBufferDecoder"/>				
	    <entry key="commandHandler" value="commandProcessingChannelHandler"/>
	</map>
    </property>
</bean>		

• Sample configuration for using the Java Old I/O based UDS listener:

<!-- UDS OIO Server -->
<bean id="udsOIOServer" class= "com.flipkart.phantom.runtime.impl.server.oio.UDSOIOServer">
    <property name="socketName" value="${proxy.core.server.uds.socketName}" />
    <property name="socketDir" value="${proxy.core.server.uds.socketDir}" />
    <property name="repository" ref="taskHandlerRepository"/>		
</bean>

Full sample listener and proxy handler configurations using Netty are available here : Command proxy Listener Configuration , Command proxy handler configuration

The sample-task-proxy module has a sample Phantom PHP client for accessing Phantom proxy using the Command protocol.