1   /*
2    * Copyright 2019 LINE Corporation
3    *
4    * LINE Corporation licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   https://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package com.linecorp.centraldogma.server.mirror;
17  
18  import java.io.File;
19  import java.net.URI;
20  import java.time.Instant;
21  import java.time.ZonedDateTime;
22  import java.util.concurrent.ConcurrentHashMap;
23  
24  import org.jspecify.annotations.Nullable;
25  
26  import com.cronutils.model.Cron;
27  
28  import com.linecorp.centraldogma.common.MirrorException;
29  import com.linecorp.centraldogma.server.command.CommandExecutor;
30  import com.linecorp.centraldogma.server.credential.Credential;
31  import com.linecorp.centraldogma.server.storage.repository.Repository;
32  
33  /**
34   * Contains the properties for a mirroring task and performs the task.
35   */
36  public interface Mirror {
37  
38      /**
39       * Returns the ID of the mirroring task.
40       */
41      String id();
42  
43      /**
44       * Returns the schedule for the mirroring task.
45       * {@code null} if the mirroring task is not scheduled.
46       */
47      @Nullable
48      Cron schedule();
49  
50      /**
51       * Returns the next execution time of the mirroring task.
52       *
53       * @param lastExecutionTime the last execution time of the mirroring task
54       */
55      ZonedDateTime nextExecutionTime(ZonedDateTime lastExecutionTime);
56  
57      /**
58       * Returns the direction of the mirroring task.
59       */
60      MirrorDirection direction();
61  
62      /**
63       * Returns the authentication credentials which are required when accessing the Git repositories.
64       */
65      Credential credential();
66  
67      /**
68       * Returns the Central Dogma repository where is supposed to keep the mirrored files.
69       */
70      Repository localRepo();
71  
72      /**
73       * Returns the path in the Central Dogma repository where is supposed to keep the mirrored files.
74       */
75      String localPath();
76  
77      /**
78       * Returns the remote URI of the Git repository which will be mirrored from.
79       */
80      RepositoryUri remoteUri();
81  
82      /**
83       * Returns the URI of the Git repository which will be mirrored from.
84       */
85      default URI remoteRepoUri() {
86          return remoteUri().uri();
87      }
88  
89      /**
90       * Returns the path of the Git repository where is supposed to be mirrored.
91       */
92      default String remotePath() {
93          return remoteUri().path();
94      }
95  
96      /**
97       * Returns the name of the branch in the Git repository where is supposed to be mirrored.
98       */
99      default String remoteBranch() {
100         return remoteUri().branch();
101     }
102 
103     /**
104      * Returns a <a href="https://git-scm.com/docs/gitignore">gitignore</a> pattern for the files
105      * which won't be mirrored.
106      */
107     @Nullable
108     String gitignore();
109 
110     /**
111      * Returns whether this {@link Mirror} is enabled.
112      */
113     boolean enabled();
114 
115     /**
116      * Returns the zone where this {@link Mirror} is pinned to.
117      */
118     @Nullable
119     String zone();
120 
121     /**
122      * Performs the mirroring task.
123      *
124      * @param workDir the local directory where keeps the mirrored files
125      * @param executor the {@link CommandExecutor} which is used to perform operation to the Central Dogma
126      *                 storage
127      * @param maxNumFiles the maximum number of files allowed to the mirroring task. A {@link MirrorException}
128      *                    would be raised if the number of files to be mirrored exceeds it.
129      * @param maxNumBytes the maximum bytes allowed to the mirroring task. A {@link MirrorException} would be
130      *                    raised if the total size of the files to be mirrored exceeds it.
131      * @param triggeredTime the time when the mirroring task is triggered.
132      */
133     MirrorResult mirror(File workDir, CommandExecutor executor, int maxNumFiles, long maxNumBytes,
134                         Instant triggeredTime);
135 
136     /**
137      * Injects the shared base-client pool managed by the mirroring scheduler. The pool maps a string key
138      * (encoding host, port, TLS flag, and maxResponseLength) to a shared base client instance. Only
139      * CentralDogma-type mirrors use this; the default implementation is a no-op.
140      */
141     default void setBaseClientPool(ConcurrentHashMap<String, Object> baseClientPool) {}
142 }