[cta-eos] Updates chapter 3 (XrdSsi + protobufs)

doc/latex/CTA_EOS_Intro.tex

@@ -9,7 +9,7 @@ CTA-EOS interface design. The file lifecycle includes:
    \begin{itemize}
    \item File create: write until initial close (CLOSEW)
    \item File update: denied for files with copy on tape. This can be achieved by administrators by adding an immutable
-	 flag (ACL) to the directories configured to go to tape in EOS, or as rule in EOS.
+	 flag (ACL) to the directories configured to go to tape in EOS, or as a rule in EOS.
    \end{itemize}
 \item[Retrieve File:] ~
    \begin{itemize}

doc/latex/CTA_EOS_Protocol.tex

@@ -4,193 +4,47 @@
 \section{Data serialization}
 \label{dataSerialization}
 
-All messages that are sent from EOS to CTA and from CTA to EOS will be serialized using Google protocol buffers. A
-dedicated type of workflow will be assigned but the administrator to the events that should be propagated to CTA. This
-will trigger the sending of a {\tt{}notification} message (through an interface still to be decided). The sending must
-be synchronous, with error propagation to the user. The option of asynchronous events is possible for the ones not
-requiring error propagation to the user.
-
-The error back-propagation protobuf is still TBD.
-
-The protocol buffer specification used by the EOS fuse mount is not be shared with the EOS/CTA interface in order
-to keep the development of the fuse mount and EOS/CTA interface completely decoupled.
-
-The communication channel used for EOS-CTA communication is still being decided. The main technical constraint is
-the threading model: the XrootD server should allow maximum parallelism of the requests serving in the CTA front
-end. This is used inside the front end to internally pack requests together to improve database and object store
-bandwidth, in order to meet the performance requirements described in \ref{perfreq}.
-
-The EOS to CTA and CTA to EOS interface must be designed to handle the versioning issues of deployments of EOS and
-CTA where the interface has been upgraded.  Such upgrades would start with a new version of CTA being installed
-first that can talk both the old and new interface protocol(s).  Then each EOS instance would be upgraded, one
-experiment at a time.
-
-The workflows will no longer set any file properties on the EOS side, as those will be set by CTA via ``tape replica''
-and ``xattr'' calls.
-
-\begin{lstlisting}
-syntax = "proto3";
-package eos.wfe;
-
-message Id {
-  fixed64 uid      = 1;        //< user identity number
-  string username  = 2;        //< user name
-  fixed64 gid      = 3;        //< group identity number
-  string groupname = 4;        //< group name
-}
-
-message Checksum {
-  string value     = 1;        //< checksum value
-  string name      = 2;        //< checksum name
-}
-
-message Clock {
-  fixed64 sec      = 1;        //< seconds of a clock
-  fixed64 nsec     = 2;        //< nanoseconds of a clock
-}
-
-message Md {
-  fixed64 fid      = 1;        //< file/container id
-  fixed64 pid      = 2;        //< parent id
-  Clock ctime      = 3;        //< change time
-  Clock mtime      = 4;        //< modification time
-  Clock btime      = 5;        //< birth time
-  Clock ttime      = 6;        //< tree modification time
-  Id owner         = 7;        //< ownership
-  fixed64 size     = 8;        //< size
-  Checksum cks     = 9;        //< checksum information
-  sfixed32 mode    = 10;       //< mode
-  string lpath     = 11;       //< logical path
-  map<string,string>
-             xattr = 12;       //< xattribute map
-};
-
-message Security {
-  string host      = 1;        //< client host
-  string app       = 2;        //< app string
-  string name      = 3;        //< sec name
-  string prot      = 4;        //< security protocol
-  string grps      = 5;        //< security grps
-}
-
-message Client {
-  Id user          = 1;        //< acting client
-  Security sec     = 2;        //< client security information
-}
-
-message Service {
-  string name      = 1;        //< name of the service
-  string url       = 2;        //< access url of the service
-}
-
-message Workflow {
-  enum EventType { NONE = 0; OPENR = 1; OPENW = 2; CLOSER = 3; CLOSEW = 4;
-                   DELETE = 5; PREPARE = 6; }
-  EventType event   = 1;       //< event
-  string queue      = 2;       //< queue
-  string wfname     = 3;       //< workflow
-  string vpath      = 4;       //< vpath
-  Service instance  = 5;       //< instance information
-  fixed64 timestamp = 6;       //< event timestamp
-}
-
-message Notification {
-  Workflow wf       = 1;       //< workflow
-  string turl       = 2;       //< transport URL
-  Client cli        = 3;       //< client information
-  Md file           = 4;       //< file meta data
-  Md directory      = 5;       //< directory meta data
-}
-
-message Xattr {
-  enum Operation { NONE = 0; GET = 1; ADD = 2; SET = 3; DELETE = 4;}
-  fixed64 fid         = 1;     //< file id
-  map<string, string>
-               xattrs = 2;     //< xattribute map
-  Operation op        = 3;     //< operation to execute for this xattr map
-}
-
-message Tapereplica {
-   enum Status { NONE = 0; OFFTAPE = 1; ONTAPE = 2; ONTAPESAVE = 3;}
-   fixed64 fid        = 1;     //< file  id
-   Status status      = 2;     //< state state for file ID
-   fixed64 size       = 3;     //< File size as recorded on tape for cross check
-   Checksum cks       = 4;     //< File checksum as computer while writing to tape
-}
-
-message Error {
-  enum Audience { NONE = 0; EOSLOG = 1; ENDUSER = 2;} 
-  Audience audience   = 1;     //< The intended audience of the error message
-  fixed64 code        = 2;     //< Zero means success, non-zero means error
-  string message      = 3;     //< An empty if success, else an error message
-}
-
-// The following message is used to wrap all messages sent between EOS and its
-// peers.
-//
-// This wrapper message allows new message types to be added to the protocol in
-// future.  
-//
-// This wrapper message also allows EOS peers to receive non-EOS messages as long
-// as the following two conditions are met:
-// 1. The peer uses a wrapper message with exactly the same (simple) structure. 
-// 2. No two message types use the same numeric tag value. 
-//
-// The structure of this message is based on the "Union Types" section of the
-// following Google protocol buffers web page:
-//
-//    https://developers.google.com/protocol-buffers/docs/techniques
-//
-// A protocol buffer parser cannot determine a message type based solely on its
-// contents. The type field of this wrapper message provides the required metadata.
-
-message Wrapper {
-  enum Type {NONE = 0; ERROR = 1; NOTIFICATION = 2; XATTR = 3; TAPEREPLICA = 4;}
-  Type type                 = 1;
-  Error error               = 2;
-  Notification notification = 3;
-  Xattr xattr               = 4;
-  Tapereplica tapereplica   = 5;
-}
-\end{lstlisting}
-
-\section{CTA front end extension} \label{CLI}
-
-As SSIv2 is not available yet, we could use an interim interface over the current CLI. We could modify the current CTA
-command-line tool to receive a protocol buffer message on its standard in and send that message to the CTA front end as
-the contents of a virtual file in the CTA front-end's virtual namespace.
-
-The CTA command-line tool currently:
-\begin{enumerate}
-\item Base64 encodes each element of the argv[] array passed to its main() function.
-\item Concatenates all of the encoded elements together into a single string with an ampersand '\&' between each encoded element.
-\item Calls the XrdCl::FILE::Open() method with the resulting string as the name of the file to be opened.
-\end{enumerate}
-For example executing \texttt{cta admin ls} at command prompt would cause the cta program to call:
-\begin{lstlisting}
-XrdCl::FILE::Open("Y3Rh&YWRtaW4=&bHM=")
-\end{lstlisting}
-where {\tt{}Y3Rh} is the base64 encoding of {\tt cta},  {\tt YWRtaW4} is {\tt admin} and {\tt bHM=} is {\tt ls}. This
-therefore means the file opened is always named {\tt Y3Rh} which is the base64 encoding of {\tt cta}. The modified
-CTA command-line tool could use a different file name when sending the protocol buffer message so that the CTA front end
-could be incrementally modified to continue to handle all of the current cta commands by processing the ``Y3Rh'' file and
-all of the new protocol buffer messages by handling the opening of the new file, for example {\tt protobuf}.
-
-The EOS workflow engine currently talks to CTA by executing bash scripts that call the {\tt{}cta} command-line
-tool.  These bash scripts selectively pass the appropriate arguments to the {\tt{}cta} command-line tool for each
-required action.  When a protocol buffer message is used instead of executing a bash script, the protocol buffer
-will contain everything known by EOS about the file being acted upon. The CTA front end will therefore receive
-everything it needs to know about the file and more.  It will be responsibility of the CTA front end to only select
-what information it needs from the protocol buffer message.
-
-\section{Move to Xrootd's SSIv2}
-\label{SSI}
-
-The \href{http://xrootd.org/doc/dev42/ssi\_reference.htm}{Scalable Service Interface} functionality of XRootD is
+All messages sent from EOS to CTA and from CTA to EOS will be serialized using Google protocol buffers.
+
+A dedicated type of workflow will be assigned by the administrator to the events that should be propagated to CTA. This
+will trigger the sending of a {\tt{}notification} message. The sending must be synchronous, with error propagation to
+the user. (Asynchronous events could be allowed for events with no requirement for error propagation to the user.)
+
+The workflows will not set any file properties on the EOS side, as those will be set by CTA via ``tape replica'' and
+``xattr'' calls.
+
+The protocol buffer definition will provide the  CTA Frontend with everything EOS knows about the file.
+It will be responsibility of the CTA Frontend to select only the information it needs from the protocol buffer message.
+
+\section{XRootD SSIv2}
+
+The communication channel between EOS and CTA will use the XRootD
+\href{http://xrootd.org/doc/dev42/ssi\_reference.htm}{Scalable Service Interface version 2}
+(SSIv2) protocol.
+
+functionality of XRootD is
 expected to provide a threading model matching our requirements (i.e. without the per-file serialization of the calls).
 
+The XRootD server should allow maximum parallelism of requests served to the CTA Frontend. This is used inside the
+frontend to internally pack requests together to improve database and object store bandwidth, in order to meet the
+performance requirements described in \ref{perfreq}.
+
+\section{EOS-CTA Protocol Versioning}
+
+The protocol buffer specification will be defined in a separate project shared by the EOS and CTA projects. This project
+will also include a set of generic headers to couple the protocol buffer definitions with the XRootD SSIv2 transport
+layer.
+
+In the case that the protocol buffer definitions are updated, a new version of CTA should be installed first, followed
+by upgrading the EOS instances one-at-a-time. CTA should maintain compatability with old protocol versions until the
+upgrades have been rolled out to all experiments.
+
 \section{EOS support of tape notions}
 
-In order to achieve those function, EOS will keep track of tape-related mode (should have a copy on tape), as well as
-keeping track of the tape replica status.
+EOS will keep track of tape-related mode (should have a copy on tape) and the tape replica status.
+
+\begin{alertbox}
+Should EOS check the Storage Class on open?
 
+Does EOS need to keep track of the tape copy ID?
+\end{alertbox}