MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Acquisition.hpp
Go to the documentation of this file.
1#pragma once
2
3#include <expected>
4
5namespace MayaFlux::Platform {
6
7/**
8 * @brief Why an acquisition request was refused, with every path that was checked.
9 */
29
30template <typename T>
31using Acquired = std::expected<T, AcquireFailure>;
32
33/**
34 * @brief A shared library at an explicit file path, absolute or relative to the working directory.
35 */
37 std::filesystem::path path;
38};
39
40/**
41 * @brief A shared library given by name, searched under one prefix.
42 *
43 * Candidates are tried in this order. First the platform file name built from base_name:
44 * "lib<name>.so" on Linux, "lib<name>.dylib" on macOS, "<name>.dll" on Windows. If
45 * base_name starts with "lib", the same decoration of the rest of it. Then base_name is
46 * tried as the exact file name. Each round searches lib, lib64, then bin.
47 */
49 std::filesystem::path prefix;
50 std::string base_name;
51};
52
53/**
54 * @brief A shared library given by name, searched directly inside each of several directories.
55 *
56 * For directories that hold libraries themselves, such as /usr/lib, where LibraryFromPrefix
57 * would look in lib, lib64 and bin below them. The names are the ones LibraryFromPrefix
58 * tries, in the same order, and each name is tried in every directory, in the order given,
59 * before the next name. Relative directories resolve against the working directory. Empty
60 * entries are ignored, and directories that do not exist are recorded as tried.
61 */
63 std::vector<std::filesystem::path> directories;
64 std::string base_name;
65};
66
67/**
68 * @brief A shared library the system loader resolves by its exact file name.
69 *
70 * Nothing is searched here. The name is passed to the loader unchanged.
71 */
73 std::string file_name;
74};
75
76using LibrarySource = std::variant<LibraryFromPath, LibraryFromPrefix, LibraryFromDirectories, LibraryFromSystem>;
77
78/**
79 * @brief Where a library comes from after acquisition.
80 *
81 * path is set for LibraryFromPath and LibraryFromPrefix, always absolute. resolved_by_system
82 * is true for LibraryFromSystem, where path is empty and file_name is what the loader receives.
83 */
85 std::filesystem::path path;
86 std::string file_name;
88};
89
90namespace detail {
91
92 template <typename... Ts>
93 struct Overloaded : Ts... {
94 using Ts::operator()...;
95 };
96
97 template <typename... Ts>
98 Overloaded(Ts...) -> Overloaded<Ts...>;
99
101 std::string request,
102 std::vector<std::filesystem::path> tried = {})
103 {
104 return AcquireFailure { .reason = reason, .request = std::move(request), .tried = std::move(tried) };
105 }
106
107 inline bool is_single_component(std::string_view name)
108 {
109 const std::filesystem::path path { std::string(name) };
110 return path.filename() == path && !path.has_root_path() && !path.has_parent_path();
111 }
112
113 inline bool has_control_character(std::string_view name)
114 {
115 return std::ranges::any_of(name, [](char c) {
116 const auto byte = static_cast<unsigned char>(c);
117 return byte < 0x20 || byte == 0x7F;
118 });
119 }
120
121 inline std::optional<AcquireFailure> check_file_name(std::string_view name)
122 {
123 if (name.empty()) {
125 }
126 const bool unsafe = name == "." || name == ".." || !is_single_component(name)
127 || has_control_character(name)
128#if defined(MAYAFLUX_PLATFORM_WINDOWS)
129 || name.find(':') != std::string_view::npos
130#endif
131 ;
132 if (unsafe) {
133 return make_failure(AcquireFailure::Reason::InvalidName, std::string(name));
134 }
135 return std::nullopt;
136 }
137
138 inline std::expected<std::filesystem::path, AcquireFailure> resolve_absolute(const std::filesystem::path& path)
139 {
140 if (path.empty()) {
141 return std::unexpected(make_failure(AcquireFailure::Reason::EmptyRequest, ""));
142 }
143 std::error_code ec;
144 std::filesystem::path absolute = std::filesystem::absolute(path, ec);
145 if (ec) {
146 return std::unexpected(make_failure(AcquireFailure::Reason::Missing, path.string(), { path }));
147 }
148 return absolute;
149 }
150
151 inline std::string shared_library_file_name(const std::string& base_name)
152 {
153#if defined(MAYAFLUX_PLATFORM_WINDOWS)
154 return base_name + ".dll";
155#elif defined(MAYAFLUX_PLATFORM_MACOS)
156 return "lib" + base_name + ".dylib";
157#else
158 return "lib" + base_name + ".so";
159#endif
160 }
161
162 inline bool path_is_regular_file(const std::filesystem::path& path)
163 {
164 std::error_code ec;
165 return std::filesystem::is_regular_file(path, ec) && !ec;
166 }
167
168 inline bool path_is_directory(const std::filesystem::path& path)
169 {
170 std::error_code ec;
171 return std::filesystem::is_directory(path, ec) && !ec;
172 }
173
174 inline bool path_exists(const std::filesystem::path& path)
175 {
176 std::error_code ec;
177 return std::filesystem::exists(path, ec) && !ec;
178 }
179
181 {
182 auto absolute = resolve_absolute(from.path);
183 if (!absolute) {
184 return std::unexpected(absolute.error());
185 }
186 if (!path_exists(*absolute)) {
187 return std::unexpected(make_failure(AcquireFailure::Reason::Missing, from.path.string(), { *absolute }));
188 }
189 if (!path_is_regular_file(*absolute)) {
190 return std::unexpected(make_failure(AcquireFailure::Reason::NotRegularFile, from.path.string(), { *absolute }));
191 }
192 return LibraryLocation { .path = *absolute, .file_name = absolute->filename().string(), .resolved_by_system = false };
193 }
194
195 inline std::vector<std::string> prefix_file_names(const std::string& base_name)
196 {
197 std::vector<std::string> names { shared_library_file_name(base_name) };
198 if (base_name.size() > 3 && base_name.starts_with("lib")) {
199 names.push_back(shared_library_file_name(base_name.substr(3)));
200 }
201 names.push_back(base_name);
202 return names;
203 }
204
206 {
207 if (auto failure = check_file_name(from.base_name)) {
208 return std::unexpected(*failure);
209 }
210 auto absolute = resolve_absolute(from.prefix);
211 if (!absolute) {
212 return std::unexpected(absolute.error());
213 }
214 if (!path_is_directory(*absolute)) {
215 return std::unexpected(make_failure(AcquireFailure::Reason::NotDirectory, from.base_name, { *absolute }));
216 }
217
218 std::vector<std::filesystem::path> tried;
219 for (const std::string& file_name : prefix_file_names(from.base_name)) {
220 for (const char* subdir : { "lib", "lib64", "bin" }) {
221 const std::filesystem::path candidate = *absolute / subdir / file_name;
222 tried.push_back(candidate);
223 if (path_is_regular_file(candidate)) {
224 return LibraryLocation { .path = candidate, .file_name = file_name, .resolved_by_system = false };
225 }
226 }
227 }
228 return std::unexpected(make_failure(AcquireFailure::Reason::Missing, from.base_name, std::move(tried)));
229 }
230
232 {
233 if (auto failure = check_file_name(from.base_name)) {
234 return std::unexpected(*failure);
235 }
236
237 std::vector<std::filesystem::path> directories;
238 for (const std::filesystem::path& directory : from.directories) {
239 if (directory.empty()) {
240 continue;
241 }
242 auto absolute = resolve_absolute(directory);
243 if (!absolute) {
244 return std::unexpected(absolute.error());
245 }
246 directories.push_back(std::move(*absolute));
247 }
248 if (directories.empty()) {
249 return std::unexpected(make_failure(AcquireFailure::Reason::EmptyRequest, from.base_name));
250 }
251
252 std::vector<std::filesystem::path> tried;
253 for (const std::string& file_name : prefix_file_names(from.base_name)) {
254 for (const std::filesystem::path& directory : directories) {
255 const std::filesystem::path candidate = directory / file_name;
256 tried.push_back(candidate);
257 if (path_is_regular_file(candidate)) {
258 return LibraryLocation { .path = candidate, .file_name = file_name, .resolved_by_system = false };
259 }
260 }
261 }
262 return std::unexpected(make_failure(AcquireFailure::Reason::Missing, from.base_name, std::move(tried)));
263 }
264
266 {
267 if (auto failure = check_file_name(from.file_name)) {
268 return std::unexpected(*failure);
269 }
270 return LibraryLocation { .path = {}, .file_name = from.file_name, .resolved_by_system = true };
271 }
272
273}
274
275/**
276 * @brief Resolve a library request to a location the loader can open.
277 *
278 * Each source kind has its own rule, and the compiler requires every kind to be handled.
279 * Relative paths resolve against the working directory. Names must be plain file names.
280 * A refusal lists the paths that were checked.
281 *
282 * @param source The request, as one of the LibrarySource alternatives.
283 * @return The resolved location, or the reason the request was refused.
284 */
285[[nodiscard]] inline Acquired<LibraryLocation> acquire_library(const LibrarySource& source)
286{
287 return std::visit(detail::Overloaded {
288 [](const LibraryFromPath& from) { return detail::acquire_from_path(from); },
289 [](const LibraryFromPrefix& from) { return detail::acquire_from_prefix(from); },
290 [](const LibraryFromDirectories& from) { return detail::acquire_from_directories(from); },
291 [](const LibraryFromSystem& from) { return detail::acquire_from_system(from); } },
292 source);
293}
294
295/**
296 * @brief Validate a header root: an existing directory, optionally containing a marker file.
297 *
298 * @param directory The directory the JIT will add to its include search path. Relative
299 * paths resolve against the working directory.
300 * @param marker_file A plain file name that must be a regular file inside directory, or empty for none.
301 * @return The absolute directory, or the reason it was refused.
302 */
304 const std::filesystem::path& directory,
305 std::string_view marker_file = {})
306{
307 auto absolute = detail::resolve_absolute(directory);
308 if (!absolute) {
309 return std::unexpected(absolute.error());
310 }
311 if (!detail::path_exists(*absolute)) {
312 return std::unexpected(detail::make_failure(AcquireFailure::Reason::Missing, directory.string(), { *absolute }));
313 }
314 if (!detail::path_is_directory(*absolute)) {
315 return std::unexpected(detail::make_failure(AcquireFailure::Reason::NotDirectory, directory.string(), { *absolute }));
316 }
317 if (!marker_file.empty()) {
318 if (auto failure = detail::check_file_name(marker_file)) {
319 return std::unexpected(*failure);
320 }
321 const std::filesystem::path marker = *absolute / marker_file;
322 if (!detail::path_is_regular_file(marker)) {
323 return std::unexpected(detail::make_failure(AcquireFailure::Reason::MarkerMissing, directory.string(), { marker }));
324 }
325 }
326 return *absolute;
327}
328
329}
std::vector< std::string > prefix_file_names(const std::string &base_name)
bool path_is_regular_file(const std::filesystem::path &path)
std::string shared_library_file_name(const std::string &base_name)
bool path_exists(const std::filesystem::path &path)
Acquired< LibraryLocation > acquire_from_prefix(const LibraryFromPrefix &from)
Acquired< LibraryLocation > acquire_from_system(const LibraryFromSystem &from)
Overloaded(Ts...) -> Overloaded< Ts... >
Acquired< LibraryLocation > acquire_from_directories(const LibraryFromDirectories &from)
bool path_is_directory(const std::filesystem::path &path)
Acquired< LibraryLocation > acquire_from_path(const LibraryFromPath &from)
bool is_single_component(std::string_view name)
std::optional< AcquireFailure > check_file_name(std::string_view name)
std::expected< std::filesystem::path, AcquireFailure > resolve_absolute(const std::filesystem::path &path)
AcquireFailure make_failure(AcquireFailure::Reason reason, std::string request, std::vector< std::filesystem::path > tried={})
bool has_control_character(std::string_view name)
std::expected< T, AcquireFailure > Acquired
std::variant< LibraryFromPath, LibraryFromPrefix, LibraryFromDirectories, LibraryFromSystem > LibrarySource
Acquired< LibraryLocation > acquire_library(const LibrarySource &source)
Resolve a library request to a location the loader can open.
Acquired< std::filesystem::path > acquire_header_root(const std::filesystem::path &directory, std::string_view marker_file={})
Validate a header root: an existing directory, optionally containing a marker file.
std::vector< std::filesystem::path > tried
Why an acquisition request was refused, with every path that was checked.
std::vector< std::filesystem::path > directories
A shared library given by name, searched directly inside each of several directories.
A shared library at an explicit file path, absolute or relative to the working directory.
A shared library given by name, searched under one prefix.
A shared library the system loader resolves by its exact file name.
Where a library comes from after acquisition.