README.adaptation How an OpenCDN interfaces with a running Streaming Server Topics: 1. Interface description 2. Porting guidelines 3. Application Programming Interface 1. Interface description --------------------- An OpenCDN entity (e.g. a Node or Origin) loads a Convergence Layer module, as dictated by $ad_layer (this variable name will soon be replaced by $conv_layer) in etc/Nodeconfig.pm, that can be either "Dummy.pm" or "Meta.pm" The former does nothing else than make the node happy, can be used for development, and claims to be able to carry any streaming technology. The latter loads the Darwin.pm, Helix.pm and VLC.pm Adaptation Layer packages, and if such technologies are actually found running on board, registers such capabilities to the RRDM, by a one-char encoding. Encoding is 'r' for real, 'd' for Apple Darwin, 'w' for Windows Media (actually unsupported) and 'v' for VideoLAN. The following scheme exemplifies the control hierarchy. +---------------------+ | Node.pm / Origin.pm | +----------+----------+ | v +-------------------------------+ | Meta.pm | Convergence Layer +---+----------+-----------+----+ | ^ | ^ | ^ v | v | v | +----+----+ +-----+--+ +-----+--+ |Darwin.pm| |Helix.pm| | VLC.pm | Adaptation Layer(s) +----+----+ +----+---+ +----+---+ | | | v v v +------------+ +------------+ +----------+ | Apple | | Helix | | | Streaming technology | Darwin | |Univ. Server| | VideoLAN | |Str. Server | | by Real | | | +------------+ +------------+ +----------+ 2. Porting guidelines ------------------ When porting the OpenCDN architecture to a new streaming server technology, a new Perl Adaptation layer module has to written, in charge of hiding the streaming server control interface, and to offer a common API to the Meta.pm Convergence Layer. In fact, either Darwin.pm, Helix.pm or VLC.pm do offer the same API interface, and the same should be for the new technology. If the new technology deals with a completely incompatible streaming control protocol, a new one-character code has to be defined for it, and Meta.pm modified accordingly. Otherwise, Meta.pm should be modified as well, in order to use the new module instead of the already existing one. 3. Application Programming Interface --------------------------------- Here follows a short synopsis about the subroutines to be implemented by an Adaptation Layer module, which interfaces a streaming technology. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name new ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Performs Adaptation Layer initialization, checks that the streaming server is running, etc arguments: $node_address | Received from control layer returns: $ret | OK/NO on succcess/failure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name term ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Performs Adaptation Layer termination arguments: none returns: none ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name mk_mount ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Evaluates origin IP and mountpoint, and local mountpoint arguments: $or_uri | content origin URL --------------+---------------------------- $prog_uri | content program URL returns: $ip | origin IP address --------------+---------------------------- $mount | origin mount point --------------+---------------------------- $destmount | local mount point ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name do_relay ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Pulls media from an Origin server, located at a given mount point, and makes it available for clients, at a local mount point. Optionally, it checks if the relay is still functioning well. Tags this relay with a given name. arguments: $address | IP address of the origin --------------+---------------------------- $mountpoint | mount point at the origin --------------+---------------------------- $destmount | local mount point --------------+---------------------------- $check | is the relay still working ? returns: $ret_code | 200 or 220 on success | 550/1/2/3 on failure --------------+------------------------ $ret_val | reason phrase --------------+---------------------------- $name | name tag for the relay ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name no_relay ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Dismantles the relay indicated by the name tag. arguments: $name | name tag of the relay returns: $ret_code | 200 or 220 on success | 550/3 on failure --------------+----------------- $ret_val | reason phrase ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name query_band ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Gathers total throughput from the streaming server arguments: none returns: $current_bandwith | total throughput in bit/s ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name relays_stats ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Returns informations about active relays arguments: none returns: $ret_code | reference to a data hash on success (see code) | reason phrase on failure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name clients_stats ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Returns informations about connected clients arguments: none returns: $ret_code | reference to a data hash on success (see code) | reason phrase on failure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name set_RTSP_credentials ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Protects node contents form unauthorized access User is "ocdn", and is fixed inside of the code arguments: $RTSPpassword | clear text of the password to set returns: $ret_code | 200 on success | 550 on failure --------------+----------------- $ret_val | reason phrase ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name rem_RTSP_credentials ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Removes protection of node's contents unauthorized access arguments: none returns: $ret_code | 200 --------------+----------------- $ret_val | OK ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub name origin_config ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ description: Performs origin initialization arguments: $transp | one of 'drw' char, as a transport code returns: $ret_code | 200 on success | code from Helix --------------+----------------- $ret_val | reason phrase