From 402fed9fed0af250f3ff0e1c9e56e8e424e2dd54 Mon Sep 17 00:00:00 2001
From: Kaivan Kamali <kxk302@psu.edu>
Date: Mon, 6 Jul 2020 11:32:21 -0400
Subject: [PATCH] Added doc explaining what happens when you upload a file to
 Galaxy.

---
 doc/source/dev/file_upload.md | 47 +++++++++++++++++++++++++++++++++++
 doc/source/dev/index.rst      |  1 +
 2 files changed, 48 insertions(+)
 create mode 100644 doc/source/dev/file_upload.md

diff --git a/doc/source/dev/file_upload.md b/doc/source/dev/file_upload.md
new file mode 100644
index 00000000000..fe5f6241e04
--- /dev/null
+++ b/doc/source/dev/file_upload.md
@@ -0,0 +1,47 @@
+# Uploading file to Galaxy
+
+## What happens when you upload a file to Galaxy?
+
+When you upload a file to Galaxy, a worker thread creates a job and enqueues it to do the upload. The following call graph documents what the worker thread actually does to create and enqueue the file upload job. All the files are in ./galaxy/lib.
+
+* In galaxy/web/framework/middleware/batch.py -> BatchMiddleware.__call__() -> self.application()
+  * In galaxy/web/framework/middleware/request_id.py -> RequestIDMiddleware.__call__() -> self.app()
+    * In galaxy/web/framework/middleware/xforwardedhost.py -> XForwardedHostMiddleware.__call__() -> self.app()
+      * In galaxy/web/framework/middleware/translogger.py -> TransLogger.__call__() -> self.application()
+        * In galaxy/web/framework/middleware/error.py -> ErrorMiddleware.__call__() ->  self.application()
+          * In galaxy/web/framework/middleware/base.py -> WebApplication.__call__() -> handle_request() -> method()
+            * In galaxy/web/framework/middleware/decorators.py -> expose_api() -> func()
+              * In galaxy/webapps/galaxy/api/tools.py -> ToolsController.create() -> self._create() -> tool.handle_input()
+                * In galaxy/tools/__init__.py -> handle_input() -> execute_job()
+                  * In galaxy/tools/execute.py -> execute() -> execute_single_job() -> tool.handle_single_execution()
+                    * In galaxy/tools/__init__.py -> handle_single_execution() -> self.execute() -> self.tool_action_execute()  
+
+In order to avoid excessive indentation, self.tool_action_execute() call graph is documented separately.  
+
+* In galaxy/tools/actions/upload.py -> BaseUploadToolAction.execute()  
+  * upload_common.persist_uploads() -- Persist files to upload
+  * self._setup_job()
+    * upload_common.get_uploaded_datasets()
+      * In upload_common.py -> new_upload()
+        * __new_history_upload()
+          * Create HistoryDatasetAssociation
+    * upload_common.create_paramfile() -- dumps it into a tmp file
+    * self._create_job() -> upload_common.create_job() -- create Job object, set various fields, enqueue the job (write it to job table in DB)
+      * In galaxy/tools/actions/upload_common.py -> create_job()
+        * trans.app.model.job()
+          * session_id
+          * user_id
+          * library_folder_id
+          * tool_id
+          * tool_version
+          * job_state
+        * trans.sa_session.add(job) -- adds Job object to SqlAlchemy session to be flushed next (persisted to job table in DB) 
+        * job.add_parameter() -- include the dumped param file above
+        * job.add_output_dataset()
+        * trans.sa_session.add(output_object) -- object_output is HistoryDatasetAssociation object
+        * trans.sa_session.ad(job)
+        * trans.app.job_manager.enqueue(job, tool) -- Queue the job for execution  
+          * tool.get_configured_job_handler()
+          * Create queue call back partial function
+          * Create message call back partial function
+          * self.app.job_config.assign_handler(job, queue_callback, message_callback)
\ No newline at end of file
diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst
index dfc9f93430a..101f0b800fd 100644
--- a/doc/source/dev/index.rst
+++ b/doc/source/dev/index.rst
@@ -14,3 +14,4 @@ Development Documentation
   debugging_tests
   debugging_galaxy
   starting_galaxy
+  file_upload