commit 43e6e441bf812f78239141fb847b4fdfa1ba2a68
parent faf959fe48a597635f2bb92254ec0d511aa9648e
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Wed, 5 Jun 2024 19:02:44 +0200
docs: enhance
Diffstat:
11 files changed, 37 insertions(+), 17 deletions(-)
diff --git a/c2ec/db/drop.sql b/c2ec/db/drop.sql
@@ -9,6 +9,7 @@ DELETE FROM _v.patches WHERE patch_name IN (
'proc-c2ec-retry-listener',
'proc-c2ec-status-listener',
'proc-c2ec-transfer-listener',
+ '0001-c2ec-add-confirmed-id',
'access'
);
@@ -20,4 +21,4 @@ DROP ROLE IF EXISTS c2ec_operator;
DROP ROLE IF EXISTS c2ec_api;
DROP ROLE IF EXISTS c2ec_admin;
-COMMIT;
-\ No newline at end of file
+COMMIT;
diff --git a/docs/content/architecture/wallee.tex b/docs/content/architecture/wallee.tex
@@ -5,9 +5,9 @@ Wallee offers level 1 PCI-DSS \cite{pci-dss} compliant payment processes to its
From the perspective of Wallee, the system looks as follows:
\begin{itemize}
- \item The Wallee terminal uses the Bank-Integration API of C2EC to get notified about parameter selection and inform C2EC about the payment.
- \item The Wallee terminal needs the credit card of the customer to authorize the payment.
- \item The Wallee terminal uses the \textit{Wallee Backend} to authorize the payment using the supplied Android Till SDK \autoref{ref-wallee-till-api}
+ \item The Wallee terminal uses the new Terminals API of C2EC to get notified about parameter selection and inform C2EC about the payment.
+ \item The Wallee terminal needs the credit card (or other supported payment means) of the customer to authorize the payment.
+ \item The Wallee terminal uses the Wallee Backend to authorize the payment using the supplied Android Till SDK \autoref{ref-wallee-till-api}
\end{itemize}
\subsection{Wallee Terminal}
diff --git a/docs/content/implementation/a-c2ec.tex b/docs/content/implementation/a-c2ec.tex
@@ -16,13 +16,13 @@ The implementation of the terminals API can be found in \autoref{sec-implementat
\label{fig-diagram-c2ec-apis-sequence}
\end{figure}
-\subsubsection{Decoupling steps using Events}
+\subsubsection{Decoupling Withdrawal Steps}
-The concept of publishers and subscribers is used in the implementation. It allows decoupling different steps of the process and allows different steps to be handled and executed in their own processes. Publishers can also be called notifiers or similar, while the subscriber can also be called listener or similar.
+The concept of publishers and subscribers is used in the implementation. It allows decoupling different steps of the process and allows different steps to be handled and executed in their own processes. Publishers can also be called notifiers or similar, while the subscriber can also be called listener. Subscriptions are also implemented using long-polling. Long-polling imitates subscribers by rescheduling a request after some time and keeping the connection open until the specified amount of time exceeds and the requested component responds.
-The communication of publishers and subscribers happens through channels. A publisher will publish to a certain channel when a defined state is reached. The subscriber who listens to this channel will capture the message sent through the channel by the publisher and start processing it.
+The communication of publishers and subscribers happens through channels or long-polling. A publisher will publish to a certain channel when a defined state is reached. The subscriber who listens to this channel will capture the message sent through the channel by the publisher and start processing it.
-To decouple different steps in the withdrawal process an event based architecture is implemented. This means that every action which leads to a state transition of the withdrawal will trigger an event. The applications processes are listening to those events. The consumer of the API can wait to be notified by the API, by registering to those events via a long polling request at the API. This long-polling will then wait until the listener receives the event and return the received messages to the consumer.
+To decouple different steps in the withdrawal process an event based architecture is implemented. This means that every action leading to a state transition of the withdrawal triggers an event. The trigger can be a real event trigger like a database trigger or a retry mechanism which periodically checks for state updates. The applications processes are listening to those events. Consuming clients such as the wallet or the terminal can wait to be notified by the API. The notification is achieved by registering the respective events via a long polling request. The long-polling request will then wait until the backend is ready to send the response. If the long-poll time exceeds and the result the consumer is looking for is not available, it must reschedule a long-poll request.
Following a short list of events and from whom they are triggered and who listens to them:
@@ -35,27 +35,27 @@ Following a short list of events and from whom they are triggered and who listen
\end{itemize}
\item From selected to confirming
\begin{itemize}
- \item Description: Payment confirmation request sent to the Bank-Integration API of C2EC.
+ \item Description: Payment confirmation request sent to the Terminals API of C2EC.
\item Registered by: Terminal
- \item Listened by: Confirmation
+ \item Listened by: Confirmation process
\end{itemize}
\item From selected to confirmed
\begin{itemize}
\item Description: Payment confirmation success will send a withdrawal operation status update event.
- \item Registered by: Confirmation
- \item Listened by: Consumers (via Bank-Integration-API)
+ \item Registered by: Confirmation process
+ \item Listened by: Consumer wallets (via Bank-Integration-API)
\end{itemize}
\item From selected to aborted
\begin{itemize}
\item Description: Payment confirmation failure will trigger a retry event.
- \item Registered by: Confirmation
- \item Listened by: Retrier
+ \item Registered by: Confirmation process
+ \item Listened by: Retry process
\end{itemize}
\item Refund
\begin{itemize}
\item Description: Transfers which represent refunds in C2EC.
\item Registered by: Exchange (through the Wire Gateway API)
- \item Listened by: Transfer
+ \item Listened by: Transfer process
\end{itemize}
\end{itemize}
diff --git a/docs/content/implementation/c-database.tex b/docs/content/implementation/c-database.tex
@@ -79,3 +79,8 @@ The withdrawal status trigger emits the status of a withdrawal when the status i
\subsubsection{Payment Trigger}
The payment trigger is triggered through the withdrawal confirmation request of the Terminals API (described in \autoref{sec-implementation-terminal-api}). It will start the confirmation of the transaction at the providers backend, through the provider specific confirmation process.
+
+\subsection{Migrating The Database}
+
+To add new SQL to the project a script can be added to the \textit{db} directory of the \textit{c2ec} directory. Make sure to add the path of the new SQL script to the migration script named \textit{migration.sh}. This will execute the migration when using the migration command as documented in \autoref{sec-implementation-deployment-migration}. Additionally the new migration shall be registered to the versioning scheme which is installed alongside the c2ec scheme. For examples how this is done scripts within the \textit{db} directory can help.
+
diff --git a/docs/content/implementation/f-deployment.tex b/docs/content/implementation/f-deployment.tex
@@ -48,6 +48,13 @@ When the simulation shall be installed the \textit{prod}-flag in the C2EC config
When the provider and the terminal was successfully registered, the configuration located inside the \texttt{C2EC\_HOME} must be adjusted to the correct values. Once this is done, the C2EC process can be started using \texttt{./c2ec -c [PATH-TO-CONFIGFILE]}.
+The POS terminal app must be deployed by the Wallee support. The Android package (APK) will be installed over the air by them once the APK was accepted and signed by them. To get a signed APK, it must be sent to \textit{info@wallee.com}. They will first check and sign the APK. After this step another message must be sent to them with a link to the signed APK. With this request the information of the terminal to install the application on must be given. Wallee will then rollout the app on the specified device.
+
+\subsubsection{Making C2EC Accessible Via Internet}
+
+To make the C2EC instance available a web-server must be configured to receive requests and hand them to the C2EC instance. The exact configuration will not be covered within this thesis. The test installation uses a NGINX reverse proxy \cite{nginx-reverse-proxy} to allow the access over the internet. A rudimentary configuration is enough to allow the access. It helps to set big timeouts since a lot of long-polling is done. To not undermine this, NGINX should not terminate the connection before the long-poll time exceeds. Setting big values for timeouts will be a good practice for C2EC. On the other hand clients should not run long running requests against C2EC but instead leverage retries to extend the time they wait for a response. A value between 30 and 60 seconds might be a good choice for long-polling requests.
+
\subsection{Migration And Releases}
+\label{sec-implementation-deployment-migration}
-When a new version of the system shall be installed, the new executable can be built by issueing \texttt{make build}. After migrating the database using \texttt{make migrate} the newly built executable can be started.
+When a new version of the system shall be installed, the new executable can be built by issueing \texttt{make build}. After migrating the database using \texttt{make migrate} the newly built executable can be started. For new versions of the cli and the installation \texttt{make cli} and \texttt{make simulation} can be used.
diff --git a/docs/content/results/discussion.tex b/docs/content/results/discussion.tex
@@ -10,6 +10,8 @@ A challenge which was encountered during the implementation of the terminal appl
Towards the end of the implementation it became obvious that a simple authorization was not enough to imitate the real time feeling of the withdrawal. Other requests were necessary to do so. To findout which requests needed to be filed against the Wallee backend some investigation had to be made. The documentation does explain which states exists in Wallee's transaction scheme but does not explain, which operation must be triggered to transition states. This made the investigation somewhat cumbersome. Also the integration of the backend needed more investigation than assumed. This also led to the
+Our work makes a faster uptake of GNU Taler possible. Potential customers will not need a bank account or other things to withdraw digital cash. They can now use C2EC and the terminal app for Wallee to withdraw digital cash using GNU Taler.
+
\section{Limitations and Future Work}
Due to the short time available during the thesis, features and integrations are missing which can make C2EC even more valuable. Because of this I provide a list of future work. Maybe there are other students or collaborators who want to join in and add their features to the existing code. The list might not be complete and any new ideas are appreciated. I splitted the list into the list of extensions and improvements. The improvements list also shows some limitations of the implementation done during the thesis.
diff --git a/docs/figures/.gitkeep b/docs/figures/.gitkeep
diff --git a/docs/figures/expl_bode.pdf b/docs/figures/expl_bode.pdf
Binary files differ.
diff --git a/docs/listings/.gitkeep b/docs/listings/.gitkeep
diff --git a/docs/project.bib b/docs/project.bib
@@ -275,7 +275,13 @@
title = {Authentication},
url = {https://docs.taler.net/design-documents/049-auth.html},
howpublished = {\url{https://docs.taler.net/design-documents/049-auth.html}}
+}
+@misc{nginx-reverse-proxy,
+ author = {NGINX},
+ title = {NGINX Reverse Proxy},
+ url = {https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/},
+ howpublished = {\url{https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/}}
}
@misc{wallet-withdrawal,
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
