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  
23  import org.jspecify.annotations.Nullable;
24  
25  import com.cronutils.model.Cron;
26  
27  import com.linecorp.centraldogma.common.MirrorException;
28  import com.linecorp.centraldogma.server.command.CommandExecutor;
29  import com.linecorp.centraldogma.server.credential.Credential;
30  import com.linecorp.centraldogma.server.storage.repository.Repository;
31  
32  /**
33   * Contains the properties for a mirroring task and performs the task.
34   */
35  public interface Mirror {
36  
37      /**
38       * Returns the ID of the mirroring task.
39       */
40      String id();
41  
42      /**
43       * Returns the schedule for the mirroring task.
44       * {@code null} if the mirroring task is not scheduled.
45       */
46      @Nullable
47      Cron schedule();
48  
49      /**
50       * Returns the next execution time of the mirroring task.
51       *
52       * @param lastExecutionTime the last execution time of the mirroring task
53       */
54      ZonedDateTime nextExecutionTime(ZonedDateTime lastExecutionTime);
55  
56      /**
57       * Returns the direction of the mirroring task.
58       */
59      MirrorDirection direction();
60  
61      /**
62       * Returns the authentication credentials which are required when accessing the Git repositories.
63       */
64      Credential credential();
65  
66      /**
67       * Returns the Central Dogma repository where is supposed to keep the mirrored files.
68       */
69      Repository localRepo();
70  
71      /**
72       * Returns the path in the Central Dogma repository where is supposed to keep the mirrored files.
73       */
74      String localPath();
75  
76      /**
77       * Returns the remote URI of the Git repository which will be mirrored from.
78       */
79      RepositoryUri remoteUri();
80  
81      /**
82       * Returns the URI of the Git repository which will be mirrored from.
83       */
84      default URI remoteRepoUri() {
85          return remoteUri().uri();
86      }
87  
88      /**
89       * Returns the path of the Git repository where is supposed to be mirrored.
90       */
91      default String remotePath() {
92          return remoteUri().path();
93      }
94  
95      /**
96       * Returns the name of the branch in the Git repository where is supposed to be mirrored.
97       */
98      default String remoteBranch() {
99          return remoteUri().branch();
100     }
101 
102     /**
103      * Returns a <a href="https://git-scm.com/docs/gitignore">gitignore</a> pattern for the files
104      * which won't be mirrored.
105      */
106     @Nullable
107     String gitignore();
108 
109     /**
110      * Returns whether this {@link Mirror} is enabled.
111      */
112     boolean enabled();
113 
114     /**
115      * Returns the zone where this {@link Mirror} is pinned to.
116      */
117     @Nullable
118     String zone();
119 
120     /**
121      * Performs the mirroring task.
122      *
123      * @param workDir the local directory where keeps the mirrored files
124      * @param executor the {@link CommandExecutor} which is used to perform operation to the Central Dogma
125      *                 storage
126      * @param maxNumFiles the maximum number of files allowed to the mirroring task. A {@link MirrorException}
127      *                    would be raised if the number of files to be mirrored exceeds it.
128      * @param maxNumBytes the maximum bytes allowed to the mirroring task. A {@link MirrorException} would be
129      *                    raised if the total size of the files to be mirrored exceeds it.
130      * @param triggeredTime the time when the mirroring task is triggered.
131      */
132     MirrorResult mirror(File workDir, CommandExecutor executor, int maxNumFiles, long maxNumBytes,
133                         Instant triggeredTime);
134 }