Merge branch 'qmnguyen0711/add-docs-for-pack-objects' into 'master'

Add documentation for pack-object cache

See merge request gitlab-org/gitaly!3636

2 files changed, 39 insertions, 5 deletions

diff --git a/cmd/gitaly-hooks/README.md b/cmd/gitaly-hooks/README.md
index 849bf3372..629cebbd0 100644
--- a/cmd/gitaly-hooks/README.md
+++ b/cmd/gitaly-hooks/README.md
@@ -12,10 +12,11 @@
 | `pre-receive`  | used as the git pre-receive hook                | none                                 | `<old-value>` SP `<new-value>` SP `<ref-name>` LF |
 | `update`       | used as the git update hook                     | `<ref-name>` `<old-object>` `<new-object>` | none
 | `post-receive` | used as the git post-receive hook               | none                                 | `<old-value>` SP `<new-value>` SP `<ref-name>` LF |
+| `git`          | used as the git pack-objects hook               | `pack-objects` `[--stdout]` `[--shallow-file]` | `<object-list>` |
 
 ## Where is it invoked from?
 
-There are two main code paths that call `gitaly-hooks`.
+There are three main code paths that call `gitaly-hooks`.
 
 ### git receive-pack (SSH & HTTP)
 
@@ -30,10 +31,12 @@ This is accomplished through the `with_hooks` method [here](https://gitlab.com/g
 called, which then calls the `gitaly-hooks` binary. This method doesn't rely on git to run the hooks. Instead, the arguments and input to the
 hooks are built in ruby and then get shelled out to `gitaly-hooks`.
 
-## What does gitaly-hooks do?
+### git upload-pack (SSH & HTTP)
+
+Only when the pack-objects cache is enabled in Gitaly's configuration file.
 
-`gitaly-hooks` will take the arguments and make an RPC call to `PreReceiveHook`, `UpdateHook`, or `PostReceiveHook` accordingly.
+SSHUploadPack and PostUploadPack, when executing `git upload-pack`, set `uploadpack.packObjectsHook` to the path of the `gitaly-hooks` binary. Afterward, when `git upload-pack` requests packfile data, it calls `gitaly-hooks` binary instead of `git pack-objects`. [That happens here in `WithPackObjectsHookEnv`](https://gitlab.com/gitlab-org/gitaly/-/blob/47164700a1ea086c5e8ca0d02feefe4e68bf4f81/internal/git/hooks_options.go#L54)
 
-**Note:**
-Currently `gitaly-hooks` will only make an RPC call to `PreReceiveHook`, `UpdateHook`, or `PostReceiveHook` if a feature flag `gitaly_hook_rpc` is enabled. Otherwise, `gitaly-hooks` falls back to calling the ruby hooks directly.
+## What does gitaly-hooks do?
 
+`gitaly-hooks` will take the arguments and make an RPC call to `PreReceiveHook`, `UpdateHook`, `PostReceiveHook`, or `PackObjectsHook` accordingly.
diff --git a/doc/design_pack_objects_cache.md b/doc/design_pack_objects_cache.md
index c104380db..a44a67679 100644
--- a/doc/design_pack_objects_cache.md
+++ b/doc/design_pack_objects_cache.md
@@ -6,6 +6,37 @@ The purpose of this document is to give more insight into the design choices we
 
 Please read the [administrator documentation for the pack-objects cache](https://docs.gitlab.com/ee/administration/gitaly/configure_gitaly.html#pack-objects-cache) if you are not already familiar with what it does or what it is for.
 
+Please read [Pack-objects cache for CI Git clones epic](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/372) for more information about Pack-objects cache.
+
+## High-level architecture
+
+```
+Gitaly (PostUploadPack)  git-upload-pack  gitaly-hooks  Gitaly (PackObjectsHook)  git-pack-objects
+------------+----------  -------+-------  -----+------  -----------+------------  -------+--------
+            |  fetch request    |              |                   |                     |
+            +------------------>| pack request |                   |                     |
+            |                   +------------->|   gRPC request    |                     |
+            |                   |              +------------------>| pack request (miss) |
+            |                   |              |                   +-------------------->|
+            |                   |              |                   |                     |
+            |                   |              |                   |<--------------------+
+            |                   |              |<------------------+   packfile data     |
+            |                   |<-------------+   gRPC response   |                     |
+            |<------------------+ packfile data|                   |                     |
+            |   fetch response  |              |                   |                     |
+            |                   |              |                   |                     |
+------------+----------  -------+-------  -----+------  -----------+------------  -------+--------
+Gitaly (PostUploadPack)  git-upload-pack  gitaly-hooks  Gitaly (PackObjectsHook)  git-pack-objects
+```
+
+The whole pack-objects cache path depends on
+[uploadpack.packObjectsHook](https://git-scm.com/docs/git-config#Documentation/git-config.txt-uploadpackpackObjectsHook)
+option. When upload-pack would run git pack-objects to create a packfile for a
+client, it will run `gitaly-hooks` binary instead. The arguments when calling
+`gitaly-hooks` includes `git pack-objects` at the beginning. This pattern is
+similar to how Gitaly handles Git hooks during a push (such as `pre-preceive`
+and `post-receive`).
+
 ## Problem scope
 
 We designed this cache to solve a specific problem on GitLab.com: high