0ct0pu5/wesnoth
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add the initial draft of the new addon server.

Browse source 
The draft is still preliminary and needs polishing and extending.
This commit is contained in:
Mark de Wever 2012-03-10 10:19:48 +00:00
parent 8684952b2e
commit b2832d94be
5 changed files with 602 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
doc/design/CMakeLists.txt
View file

@ -40,5 +40,17 @@ if(ENABLE_DESIGN_DOCUMENTS)
DEFAULT_PDF
MANGLE_TARGET_NAMES
)
ADD_LATEX_DOCUMENT(
umcd.tex
INPUTS
#
# LaTeX files
#
umcd/abstract.tex
umcd/communication_protocol.tex
umcd/introduction.tex
DEFAULT_PDF
MANGLE_TARGET_NAMES
)
endif(ENABLE_DESIGN_DOCUMENTS)

39
doc/design/umcd.tex Normal file
View file

@ -0,0 +1,39 @@
\documentclass[a4paper,notitlepage]{report}
\usepackage[english]{babel}
\usepackage[utf8x]{inputenc}
\usepackage{fontenc}
\usepackage{lmodern}
\usepackage[colorlinks]{hyperref}
\usepackage{verbatim}
\usepackage{cleveref}
\usepackage{listings}
\author{M.~de Wever}
\title{UMCD design document - DRAFT}
\begin{document}
\maketitle
\tableofcontents
\include{umcd/abstract}
\include{umcd/introduction}
\include{umcd/communication_protocol}
%\include{gui2/introduction}
%\include{gui2/overall_design}
%\include{gui2/design_details}
%\include{gui2/creating_widgets_and_dialogs}
\appendix
%\include{gui2/files_for_the_widget}
%\include{gui2/files_for_the_window}
\end{document}

12
doc/design/umcd/abstract.tex Normal file
View file

@ -0,0 +1,12 @@
\begin{abstract}
The campaign server had little love over the years and its code shows its
age. Several new features have been wanted over the years: better dependency
tracking, better translation integration.
Over the years several initiatives have started, none of these were
finished. Early $2012$ I restarted this project again this document
describes the design and the communication protocol.
\end{abstract}

518
doc/design/umcd/communication_protocol.tex Normal file
View file

@ -0,0 +1,518 @@
\chapter{Communication protocol}
\label{chapter:communication_protocol}
\section{Server configuration}
\label{section:communication_protocol:server}
On the server there are several configuration files:
\begin{itemize}
\item
The main configuration file, umcd.cfg, this file is stored in the
data directory, which is a parameter for the programme. This file is
further discussed in \cref{section:communication_protocol:server:umcd.cfg}.
\item
In this data directory there is a subdirectory per addon. These
directories have the following files:
\begin{description}
\item[umc.cfg]
The config file for the umc, this file is based on the client's
pbl file. This file is further discussed in
\cref{section:communication_protocol:server:umc.cfg}.
\item[umc.gz]
The gzipped umc.
\item[umc-\emph{lang}.cfg]
The configuration file for the translation of the umc. The
\emph{lang} is replace with the locale of the translation.
This file is further discussed in
\cref{section:communication_protocol:server:umc-lang.cfg}.
\item[umc-\emph{lang}.gz]
The gzipped mo-file for the translation. Note if the
compression-ratio for the mo-file is bad, the raw mo-file will be
stored instead. The final decision in the matter will be specified
later.
\end{description}
\end{itemize}
\subsection{umcd.cfg}
\label{section:communication_protocol:server:umcd.cfg}
This file contains the settings of the umcd.
\begin{lstlisting}
[umcd_configuration]
port = PORT
threads = THREADS
[/umcd_configurattion]
\end{lstlisting}
The keys have the following meaning:
\begin{description}
\item[PORT]
The TCP/IP port to listen to for incoming requests.
\item[THREADS]
The number of listeners threads to start. A value of $0$ means start as
many threads as there are detected hardware cores\footnote{Whether
hyper-threading and Co. count as separate cores is unspecified.}.
\end{description}
\subsection{umc.cfg}
\label{section:communication_protocol:server:umc.cfg}
This file contains the configuration of the umc on the server. The
combination of this file together with the various
\mbox{umc-\emph{lang}.cfg} files form the master information regarding an
umc. All other files that specify the umc or its wire-protocol get their
information from these files. Therefore other sections will refer to this
section.
The file is specified like:
\begin{lstlisting}
[umc]
id = ID
name = NAME
icon = ICON
type = TYPE
description = DESCRIPTION
version = VERSION
size = SIZE
authors = AUTHORS
email = EMAIL
uploader_ip_address = UPLOADER_IP_ADDRESS
timestamp = TIMESTAMP
downloads = DOWNLOADS
uploads = UPLOADS
password = PASSWORD
language = LANGUAGE
translatable = TRANSLATABLE
[dependencies]?
[dependency]+
id = ID
version? = VERSION_MASK
[/dependency]
[/dependencies]
[/umc]
\end{lstlisting}
The keys have the following meaning:
\begin{description}
\item[ID]
The unique id of the content. When uploading this value determines
whether an umc is the same umc.
\item[NAME]
The name of the content. This string is not unique. This allows two
versions of the UMC on the server. This can be used to allow a new beta
next to a stable, as long as the ID differs.
\item[ICON]
The icon of the umc, which is shown in the addon-list on the server.
TODO it is not yet specified how the icon is transferred to and from the
client.
\item[TYPE]
The type of the addon. At the moment the following values are allowed:
\begin{description}
\item[CAMPAIGN\_SP] A single player campaign.
\item[CAMPAIGN\_MP] A multi-player player campaign.
\item[ERA] A multi-player era.
\item[MAP] A multi-player map.
\item[MAP\_PACK] A multi-player map pack.
\item[RPG\_SP]
A RPG like single player game. (This also includes builder games in
the style of settlers.)
\item[RPG\_MP]
A RPG like multi-player game. (This also includes builder games in
the style of settlers.)
\item[OTHER] Everything that doesn't fit in one of the above.
\end{description}
\item[DESCRIPTION]
The description of the umc.
\item[VERSION]
A string determining the version. The string should formatted like:
`x.y.z' or `x.y.z-q'. When doing so the version can be parsed as version
number. The `-q' part is sorted alphabetically and is an empty string if
omitted, thus sorted first.
\item[SIZE]
The size of the umc in bytes packed on the server.
\item[AUTHORS]
A colon separated list of authors of the umc. When there is only one
author no colon is required.
\item[EMAIL]
The email address of the primary author or a mailinglist. When there are
problems with the umc the Wesnoth team can use this address to contact
the authors, so make sure it's valid and doesn't need registration.
The address is not used in other ways nor shared with third-parties.
\item[UPLOADER\_IP\_ADDRESS]
The ip address of the last uploader of the umc.
\item[TIMESTAMP]
The timestamp of the last upload.
\item[DOWNLOADS]
The number of times the UMC is downloaded.
\item[UPLOADS]
The number of time a new version of the UMC is uploaded.
\item[PASSWORD]
The password required to upload a new version of an umc or remove an umc
from the server.
\item[LANGUAGE]
The language id of the umc. If omitted American English is assumed.
This allows umc authors who are not able to create content in English to
still create content. However it's still recommended to try to write the
content in American English. (TODO determine whether omitted on the
server or only during the initial upload, if the latter the server
should set it if omitted during the upload.)
\item[TRANSLATABLE]
This flag causes the umc to be synchronised with Wescamp. It's advisable
to only set the flags when the strings are somewhat stable. This flag
can only be set if the language is American English.
\end{description}
The [dependencies] lists the dependencies of the UMC. This allows the client
to download all UMC required to use this UMC. The fields mean:
\begin{description}
\item[ID]
The ID of the UMC to depend upon.
\item[VERSION\_MASK]
This mask is used to validate a version used. The format is:
\begin{description}
\item[$=$VERSION]
The version number of the dependency exactly match the VERSION.
\item[$>=$VERSION]
The version number of the dependency must be greater or equal to
VERSION.
\item[$>$VERSION]
The version number of the dependency must be greater than VERSION.
\item[$<$VERSION]
The version number of the dependency must be less than VERSION
\item[$<=$VERSION]
The version number of the dependency must be less than or equal to
VERSION
\end{description}
Several values can be used in a mask. They are separated by a space. The
masks are and'ed and the user is responsible for setting a sane value;
e.g. `$<$1.0.0 $>$1.0.0' can't match a version.
If this field is omitted, all versions are allowed.
\end{description}
\subsection{umc-\emph{lang}.cfg}
\label{section:communication_protocol:server:umc-lang.cfg}.
The configuration file for the translation of the umc. The
\emph{lang} is replace with the locale of the translation.
\begin{lstlisting}
[language]
id = LANGUAGE
timestamp = TIMESTAMP
translated = TRANSLATED
fuzzy = FUZZY
untranslated = UNTRANSLATED
[translated_umc_strings]
name = NAME
description = DESCRIPTION
[/translated_umc_strings]
[/language]
\end{lstlisting}
\section{UMC configuration}
\label{section:communication_protocol:umc}
The pbl file contains the information regarding the addon. Its contents are
stored on the system of the addon developer and on the server. The file
contains the following data:
\begin{lstlisting}
[umc_configuraton]
id = ID
name = NAME
icon = ICON
type = TYPE
description = DESCRIPTION
version = VERSION
authors = AUTHORS
email = EMAIL
password? = PASSWORD
language? = LANGUAGE
translatable = TRANSLATABLE
[dependencies]?
[dependency]+
id = ID
version? = VERSION_MASK
[/dependency]
[/dependencies]
[/umc_configration]
\end{lstlisting}
The keys have the following meaning:
\begin{description}
\item[ID]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[NAME]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[ICON]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[TYPE]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[DESCRIPTION]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[VERSION]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[AUTHORS]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[EMAIL]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[PASSWORD]
See \cref{section:communication_protocol:server:umc.cfg}.
It may be omitted, during the initial upload. In that case the first
upload results in sending back the password. It's stored in the pbl-file
and the author doesn't need to remember it.
\item[LANGUAGE]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[TRANSLATABLE]
See \cref{section:communication_protocol:server:umc.cfg}.
\end{description}
\section{Wire}
\label{section:communication_protocol:wire}
\section{Request campaign list}
\label{wire:request_campaign_list}
Request:
\begin{lstlisting}
[request_umc_list]
[/requst_umc_list]
\end{lstlisting}
Replay:
\begin{lstlisting}
[umc_list]
[umc]*
id = ID
name = NAME
type = TYPE
description = DESCRIPTION
version = VERSION
size = SIZE
authors = AUTHORS
timestamp = TIMESTAMP
downloads = DOWNLOADS
uploads = UPLOADS
language = LANGUAGE
[dependencies]?
[dependency]+
id = ID
version? = VERSION_MASK
[/dependency]
[/dependencies]
[languages]?
[language]+
id = LANGUAGE
timestamp = TIMESTAMP
translated = TRANSLATED
fuzzy = FUZZY
untranslated = UNTRANSLATED
[translated_umc_strings]
name = NAME
description = DESCRIPTION
[/translated_umc_strings]
[/language]
[/languages]
[/umc]
[/umc_list]
\end{lstlisting}
The fields in [umc] have the following meaning:
\begin{description}
\item[ID]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[NAME]
See \cref{section:communication_protocol:server:umc.cfg}.
The version in [language] is the translated name of the UMC.
\item[TYPE]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[DESCRIPTION]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[VERSION]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[SIZE]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[TIMESTAMP]
The timestamp of the last upload. For the [umcs] it is the upload
of the umc, for the [language] it is the last upload of the
po-file. (NOTE MERGE WITH MASTER LIST.)
\item[DOWNLOADS]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[UPLOADS]
See \cref{section:communication_protocol:server:umc.cfg}.
\item[LANGUAGE]
The id of a language locale. The one in [umc] is the language of
the UMC. If this language is empty American English is assumed. The UMC
is only translatable if this is set to American English (this should be
mentioned in the PBL section).
\end{description}
The [dependencies] lists the dependencies of the UMC, See
\cref{section:communication_protocol:server:umc.cfg}.
The [languages] contains the list of languages the addon is (partly)
translated to. The fields mean:
\begin{description}
\item[ID]
The id of the language the translation for.
\item[TIMESTAMP]
The timestamp the po-file was last updated. NOTE UNIX stamp, should be
at other stamp as well.
\item[TRANSLATED]
The number of translated strings, if this entry is $0$, then the entire
section is not printed.
\item[FUZZY]
The number of strings that are fuzzy.
\item[UNTRANSLATED]
The number of strings that are not translated.
NOTE MAYBE ALSO ADD UP AND DOWNLOAD COUNTER and obviously the SIZE
\end{description}
The section [translated\_umc\_strings] duplicates some strings from the
general [umc] section. This version contains the translated string from
the po file. If not translated or fuzzy it contains the original, just like
normal with gettext. The keys in this section corrospondent with the ones in
[campaign].
\section{Request umc download}
\label{wire:request_umc_download}
This requests to download an umc.
Request:
\begin{lstlisting}
[request_umc_download]
id = ID
[languages]?
[language]*
ID = LANGUAGE
[/language]
[/languages]
[/requst_umc_download]
\end{lstlisting}
The fields are:
\begin{description}
\item[ID]
The id of the umc to download.
\item[LANGUAGE]
The id of the requested language to download.
\end{description}
Replay:
\begin{lstlisting}
[umc_download]
id = ID
status = STATUS
[languages]?
[language]+
id = LANGUAGE
status = STATUS
[/language]
[/languages]
[/umc_download]
\end{lstlisting}
This is a mirror of the request, only all items have a status field. The
status can be OK it the file exists and can be downloaded. Or ERROR if not
possible.
The files send are in the order of appearance in the request and reply. The
files are named:
\begin{description}
\item[ID.gz]
The gzipped campaign files. The file is packed in a single config file
to be extracted to the local file-system.
\item[ID-LANGUAGE.gz]
A gzipped mo-file for a language. If gzip's compression ratio for mo
files is too small the mo-file will be send directly.
\end{description}
\section{Request umc change password}
\label{wire:request_umc_change_password}
This request changes the password.
\section{Request umc upload}
\label{wire:request_umc_upload}
\section{Request umc delete}
\label{wire:request_umc_delete}
\section{Request license}
\label{wire:request_license}

21
doc/design/umcd/introduction.tex Normal file
View file

@ -0,0 +1,21 @@
\chapter{Introduction}
\label{chapter:introduction}
This paper describes the design and communication protocol of the umcd,
which stands for \emph{U}ser \emph{M}ade \emph{C}ontent \emph{D}aemon. The
name was first used by Shadow master.
The server has several new features planned:
\begin{description}
\item[Dependency tracking]
\item[Translated messages]
\item[Wescamp intergration]
The translations are separate. Automatic updates with Wescamp.
\item[Asio]
The network handling is switched to Boost asio.
\end{description}