GCC Code Coverage Report

Directory: cvmfs/
File: cvmfs/sync_union.h
Date: 2025-11-09 02:35:23
Exec Total Coverage
Lines: 4 7 57.1%
Branches: 0 0 -%
Line Branch Exec Source
1 /**
2 * This file is part of the CernVM File System
3 *
4 * This file defines a class to abstract information retrieval from
5 * union file system components.
6 *
7 * There is a class UnionSync which is the base class for all
8 * supported union file systems and provides support for the basic union fs
9 * principals.
10 *
11 * There are three main principals, union file systems follow:
12 * 1. Copy on Write
13 * read-only files in CVMFS will be copied up to an overlay
14 * volume on write access.
15 * 2. Whiteout
16 * the union file system has to mark files as deleted, if you
17 * remove them from a read only file system
18 * 3. Opaque Directories
19 * if you delete an entire directory from the read only file
20 * system and recreate it empty afterwards the union file system
21 * has to mark this directory as opaque to hide all old contents
22 *
23 * Furthermore, the union file system could create special files
24 * for internal bookkeeping which should be ignored.
25 *
26 * Classes that derive from UnionSync implement the specifics of a concrete
27 * union file system (e.g. AUFS, overlayfs).
28 */
29
30 #ifndef CVMFS_SYNC_UNION_H_
31 #define CVMFS_SYNC_UNION_H_
32
33 #include <set>
34 #include <string>
35
36 #include "sync_item.h"
37 #include "util/shared_ptr.h"
38
39 namespace publish {
40
41 class AbstractSyncMediator;
42 class SyncMediator;
43
44 enum UnionFsType {
45 kUnionFsUnknown,
46 kUnionFsAufs,
47 kUnionFsOverlay,
48 kUnionFsTarball,
49 };
50
51 /**
52 * Interface definition of repository synchronization based on
53 * a union filesystem overlay on top of a mounted CVMFS volume.
54 */
55 class SyncUnion {
56 public:
57 /**
58 * @param rdonly_path the absolute path to the mounted cvmfs repository
59 * @param union_path the absolute path to the mounted union file system volume
60 * @param scratch_path the absolute path to the read write branch attached to
61 * the union file system
62 * @param mediator a reference to a SyncMediator object used as bridge to
63 * the actual sync process
64 */
65 SyncUnion(AbstractSyncMediator *mediator, const std::string &rdonly_path,
66 const std::string &union_path, const std::string &scratch_path);
67 108 virtual ~SyncUnion() { }
68
69 /**
70 * Initialize internal state of the synchronisation. This needs to be called
71 * before running anything else.
72 * Note: should be up-called!
73 */
74 virtual bool Initialize();
75
76 /**
77 * Main routine, process scratch space
78 */
79 virtual void Traverse() = 0;
80
81 ✗ virtual void PostUpload() { }
82
83 /**
84 * This produces a SyncItem and initialises it accordingly. This is the only
85 * way client code can generate SyncItems to make sure it is always set up
86 * properly (see SyncItem::SyncItem() for further details).
87 * @param relative_parent_path the directory path the SyncItem resides in
88 * @param filename file/directory name of directory entry
89 * @param entry_type type of the item in the union directory
90 * @return a SyncItem object wrapping the dirent
91 */
92 SharedPtr<SyncItem> CreateSyncItem(const std::string &relative_parent_path,
93 const std::string &filename,
94 const SyncItemType entry_type) const;
95
96 306 inline std::string rdonly_path() const { return rdonly_path_; }
97 252 inline std::string union_path() const { return union_path_; }
98 ✗ inline std::string scratch_path() const { return scratch_path_; }
99
100 /**
101 * Whiteout files may have special naming conventions.
102 * This method "unmangles" them and retrieves the original file name
103 * @param filename the filename as in the scratch directory
104 * @return the original filename of the scratched out file in CVMFS repository
105 */
106 virtual std::string UnwindWhiteoutFilename(
107 SharedPtr<SyncItem> entry) const = 0;
108
109 /**
110 * Union file systems use opaque directories to fully support rmdir
111 * e.g: $ rm -rf directory
112 * $ mkdir directory
113 * This would produce an opaque directory whose contents are NOT merged with
114 * the underlying directory in the read-only branch
115 * @param directory the directory to check for opacity
116 * @return true if directory is opaque, otherwise false
117 */
118 virtual bool IsOpaqueDirectory(SharedPtr<SyncItem> directory) const = 0;
119
120 /**
121 * Checks if given file is supposed to be whiteout.
122 * These files indicate that a specific file has been deleted.
123 * @param filename the filename to check
124 * @return true if filename seems to be whiteout otherwise false
125 */
126 virtual bool IsWhiteoutEntry(SharedPtr<SyncItem> entry) const = 0;
127
128 /**
129 * Union file systems may use some special files for bookkeeping.
130 * They must not show up in to repository and are ignored by the recursion.
131 * Note: This needs to be up-called!
132 * @param parent directory in which file resides
133 * @param filename to decide whether to ignore or not
134 * @return true if file should be ignored, otherwise false
135 */
136 virtual bool IgnoreFilePredicate(const std::string &parent_dir,
137 const std::string &filename);
138
139 54 bool IsInitialized() const { return initialized_; }
140 ✗ virtual bool SupportsHardlinks() const { return false; }
141
142 protected:
143 std::string rdonly_path_;
144 std::string scratch_path_;
145 std::string union_path_;
146
147 AbstractSyncMediator *mediator_;
148
149 /**
150 * Allow for preprocessing steps before emitting any SyncItems from SyncUnion.
151 * This can be overridden by sub-classes but should always be up-called. Typi-
152 * cally this sets whiteout and opaque-directory flags or handles hardlinks.
153 * @param entry the SyncItem to be pre-processed
154 * (pointer parameter for google style guide compliance [1])
155 * [1] https://google-styleguide.googlecode.com/svn/trunk/
156 * cppguide.html#Function_Parameter_Ordering
157 */
158 virtual void PreprocessSyncItem(SharedPtr<SyncItem> entry) const;
159
160 /**
161 * Callback when a regular file is found.
162 * @param parent_dir the relative directory path
163 * @param filename the filename
164 */
165 virtual void ProcessRegularFile(const std::string &parent_dir,
166 const std::string &filename);
167
168 /**
169 * Callback when a directory is found.
170 * @param parent_dir the relative directory path
171 * @param dir_name the filename
172 * @return true if file system traversal should branch into
173 * the given directory, false otherwise
174 */
175 virtual bool ProcessDirectory(const std::string &parent_dir,
176 const std::string &dir_name);
177 virtual bool ProcessDirectory(SharedPtr<SyncItem> entry);
178 virtual bool ProcessUnmaterializedDirectory(SharedPtr<SyncItem> entry);
179
180 /**
181 * Callback when a symlink is found.
182 * @param parent_dir the relative directory path
183 * @param link_name the filename
184 */
185 virtual void ProcessSymlink(const std::string &parent_dir,
186 const std::string &link_name);
187
188 /**
189 * Called if the file system traversal enters a directory for processing.
190 * @param parent_dir the relative directory path.
191 */
192 virtual void EnterDirectory(const std::string &parent_dir,
193 const std::string &dir_name);
194
195 /**
196 * Called before the file system traversal leaves a processed directory.
197 * @param parent_dir the relative directory path.
198 */
199 virtual void LeaveDirectory(const std::string &parent_dir,
200 const std::string &dir_name);
201
202 /**
203 * Callback when a character device is found
204 * @param parent_dir the relative directory path
205 * @param filename the filename
206 */
207 void ProcessCharacterDevice(const std::string &parent_dir,
208 const std::string &filename);
209
210 /**
211 * Callback when a block device is found
212 * @param parent_dir the relative directory path
213 * @param filename the filename
214 */
215 void ProcessBlockDevice(const std::string &parent_dir,
216 const std::string &filename);
217
218 /**
219 * Callback when a named pipe is found.
220 * @param parent_dir the relative directory path
221 * @param filename the filename
222 */
223 void ProcessFifo(const std::string &parent_dir, const std::string &filename);
224
225 /**
226 * Callback when a unix domain socket is found.
227 * @param parent_dir the relative directory path
228 * @param filename the filename
229 */
230 void ProcessSocket(const std::string &parent_dir,
231 const std::string &filename);
232
233 /**
234 * Called to actually process the file entry.
235 * @param entry the SyncItem corresponding to the union file to be processed
236 */
237 void ProcessFile(SharedPtr<SyncItem> entry);
238
239 private:
240 bool initialized_;
241 }; // class SyncUnion
242
243 } // namespace publish
244
245 #endif // CVMFS_SYNC_UNION_H_
246