1//===-- llvm/Debuginfod/Debuginfod.cpp - Debuginfod client library --------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8///
9/// \file
10///
11/// This file contains several definitions for the debuginfod client and server.
12/// For the client, this file defines the fetchInfo function. For the server,
13/// this file defines the DebuginfodLogEntry and DebuginfodServer structs, as
14/// well as the DebuginfodLog, DebuginfodCollection classes. The fetchInfo
15/// function retrieves any of the three supported artifact types: (executable,
16/// debuginfo, source file) associated with a build-id from debuginfod servers.
17/// If a source file is to be fetched, its absolute path must be specified in
18/// the Description argument to fetchInfo. The DebuginfodLogEntry,
19/// DebuginfodLog, and DebuginfodCollection are used by the DebuginfodServer to
20/// scan the local filesystem for binaries and serve the debuginfod protocol.
21///
22//===----------------------------------------------------------------------===//
23
24#include "llvm/Debuginfod/Debuginfod.h"
25#include "llvm/ADT/StringExtras.h"
26#include "llvm/ADT/StringRef.h"
27#include "llvm/BinaryFormat/Magic.h"
28#include "llvm/DebugInfo/DWARF/DWARFContext.h"
29#include "llvm/DebugInfo/Symbolize/Symbolize.h"
30#include "llvm/HTTP/HTTPClient.h"
31#include "llvm/HTTP/StreamedHTTPResponseHandler.h"
32#include "llvm/Object/BuildID.h"
33#include "llvm/Object/ELFObjectFile.h"
34#include "llvm/Support/CachePruning.h"
35#include "llvm/Support/Caching.h"
36#include "llvm/Support/Errc.h"
37#include "llvm/Support/Error.h"
38#include "llvm/Support/FileUtilities.h"
39#include "llvm/Support/MemoryBuffer.h"
40#include "llvm/Support/Path.h"
41#include "llvm/Support/ThreadPool.h"
42
43#include <optional>
44#include <thread>
45
46namespace llvm {
47
48using llvm::object::BuildIDRef;
49
50namespace {
51std::optional<SmallVector<StringRef>> DebuginfodUrls;
52// Many Readers/Single Writer lock protecting the global debuginfod URL list.
53llvm::sys::RWMutex UrlsMutex;
54} // namespace
55
56std::string getDebuginfodCacheKey(llvm::StringRef S) {
57 return utostr(X: xxh3_64bits(data: S));
58}
59
60// Returns a binary BuildID as a normalized hex string.
61// Uses lowercase for compatibility with common debuginfod servers.
62static std::string buildIDToString(BuildIDRef ID) {
63 return llvm::toHex(Input: ID, /*LowerCase=*/true);
64}
65
66bool canUseDebuginfod() {
67 return HTTPClient::isAvailable() && !getDefaultDebuginfodUrls().empty();
68}
69
70SmallVector<StringRef> getDefaultDebuginfodUrls() {
71 std::shared_lock<llvm::sys::RWMutex> ReadGuard(UrlsMutex);
72 if (!DebuginfodUrls) {
73 // Only read from the environment variable if the user hasn't already
74 // set the value.
75 ReadGuard.unlock();
76 std::unique_lock<llvm::sys::RWMutex> WriteGuard(UrlsMutex);
77 DebuginfodUrls = SmallVector<StringRef>();
78 if (const char *DebuginfodUrlsEnv = std::getenv(name: "DEBUGINFOD_URLS")) {
79 StringRef(DebuginfodUrlsEnv)
80 .split(A&: DebuginfodUrls.value(), Separator: " ", MaxSplit: -1, KeepEmpty: false);
81 }
82 WriteGuard.unlock();
83 ReadGuard.lock();
84 }
85 return DebuginfodUrls.value();
86}
87
88// Set the default debuginfod URL list, override the environment variable.
89void setDefaultDebuginfodUrls(const SmallVector<StringRef> &URLs) {
90 std::unique_lock<llvm::sys::RWMutex> WriteGuard(UrlsMutex);
91 DebuginfodUrls = URLs;
92}
93
94/// Finds a default local file caching directory for the debuginfod client,
95/// first checking DEBUGINFOD_CACHE_PATH.
96Expected<std::string> getDefaultDebuginfodCacheDirectory() {
97 if (const char *CacheDirectoryEnv = std::getenv(name: "DEBUGINFOD_CACHE_PATH"))
98 return CacheDirectoryEnv;
99
100 SmallString<64> CacheDirectory;
101 if (!sys::path::cache_directory(result&: CacheDirectory))
102 return createStringError(
103 EC: errc::io_error, S: "Unable to determine appropriate cache directory.");
104 sys::path::append(path&: CacheDirectory, a: "llvm-debuginfod", b: "client");
105 return std::string(CacheDirectory);
106}
107
108std::chrono::milliseconds getDefaultDebuginfodTimeout() {
109 long Timeout;
110 const char *DebuginfodTimeoutEnv = std::getenv(name: "DEBUGINFOD_TIMEOUT");
111 if (DebuginfodTimeoutEnv &&
112 to_integer(S: StringRef(DebuginfodTimeoutEnv).trim(), Num&: Timeout, Base: 10))
113 return std::chrono::milliseconds(Timeout * 1000);
114
115 return std::chrono::milliseconds(90 * 1000);
116}
117
118/// The following functions fetch a debuginfod artifact to a file in a local
119/// cache and return the cached file path. They first search the local cache,
120/// followed by the debuginfod servers.
121
122std::string getDebuginfodSourceUrlPath(BuildIDRef ID,
123 StringRef SourceFilePath) {
124 SmallString<64> UrlPath;
125 sys::path::append(path&: UrlPath, style: sys::path::Style::posix, a: "buildid",
126 b: buildIDToString(ID), c: "source",
127 d: sys::path::convert_to_slash(path: SourceFilePath));
128 return std::string(UrlPath);
129}
130
131Expected<std::string> getCachedOrDownloadSource(BuildIDRef ID,
132 StringRef SourceFilePath) {
133 std::string UrlPath = getDebuginfodSourceUrlPath(ID, SourceFilePath);
134 return getCachedOrDownloadArtifact(UniqueKey: getDebuginfodCacheKey(S: UrlPath), UrlPath);
135}
136
137std::string getDebuginfodExecutableUrlPath(BuildIDRef ID) {
138 SmallString<64> UrlPath;
139 sys::path::append(path&: UrlPath, style: sys::path::Style::posix, a: "buildid",
140 b: buildIDToString(ID), c: "executable");
141 return std::string(UrlPath);
142}
143
144Expected<std::string> getCachedOrDownloadExecutable(BuildIDRef ID) {
145 std::string UrlPath = getDebuginfodExecutableUrlPath(ID);
146 return getCachedOrDownloadArtifact(UniqueKey: getDebuginfodCacheKey(S: UrlPath), UrlPath);
147}
148
149std::string getDebuginfodDebuginfoUrlPath(BuildIDRef ID) {
150 SmallString<64> UrlPath;
151 sys::path::append(path&: UrlPath, style: sys::path::Style::posix, a: "buildid",
152 b: buildIDToString(ID), c: "debuginfo");
153 return std::string(UrlPath);
154}
155
156Expected<std::string> getCachedOrDownloadDebuginfo(BuildIDRef ID) {
157 std::string UrlPath = getDebuginfodDebuginfoUrlPath(ID);
158 return getCachedOrDownloadArtifact(UniqueKey: getDebuginfodCacheKey(S: UrlPath), UrlPath);
159}
160
161// General fetching function.
162Expected<std::string> getCachedOrDownloadArtifact(StringRef UniqueKey,
163 StringRef UrlPath) {
164 SmallString<10> CacheDir;
165
166 Expected<std::string> CacheDirOrErr = getDefaultDebuginfodCacheDirectory();
167 if (!CacheDirOrErr)
168 return CacheDirOrErr.takeError();
169 CacheDir = *CacheDirOrErr;
170
171 return getCachedOrDownloadArtifact(UniqueKey, UrlPath, CacheDirectoryPath: CacheDir,
172 DebuginfodUrls: getDefaultDebuginfodUrls(),
173 Timeout: getDefaultDebuginfodTimeout());
174}
175
176// An over-accepting simplification of the HTTP RFC 7230 spec.
177static bool isHeader(StringRef S) {
178 StringRef Name;
179 StringRef Value;
180 std::tie(args&: Name, args&: Value) = S.split(Separator: ':');
181 if (Name.empty() || Value.empty())
182 return false;
183 return all_of(Range&: Name, P: [](char C) { return llvm::isPrint(C) && C != ' '; }) &&
184 all_of(Range&: Value, P: [](char C) { return llvm::isPrint(C) || C == '\t'; });
185}
186
187static SmallVector<std::string, 0> getHeaders() {
188 const char *Filename = getenv(name: "DEBUGINFOD_HEADERS_FILE");
189 if (!Filename)
190 return {};
191 ErrorOr<std::unique_ptr<MemoryBuffer>> HeadersFile =
192 MemoryBuffer::getFile(Filename, /*IsText=*/true);
193 if (!HeadersFile)
194 return {};
195
196 SmallVector<std::string, 0> Headers;
197 uint64_t LineNumber = 0;
198 for (StringRef Line : llvm::split(Str: (*HeadersFile)->getBuffer(), Separator: '\n')) {
199 LineNumber++;
200 Line.consume_back(Suffix: "\r");
201 if (!isHeader(S: Line)) {
202 if (!all_of(Range&: Line, P: llvm::isSpace))
203 WithColor::warning()
204 << "could not parse debuginfod header: " << Filename << ':'
205 << LineNumber << '\n';
206 continue;
207 }
208 Headers.emplace_back(Args&: Line);
209 }
210 return Headers;
211}
212
213Expected<std::string> getCachedOrDownloadArtifact(
214 StringRef UniqueKey, StringRef UrlPath, StringRef CacheDirectoryPath,
215 ArrayRef<StringRef> DebuginfodUrls, std::chrono::milliseconds Timeout) {
216 SmallString<64> AbsCachedArtifactPath;
217 sys::path::append(path&: AbsCachedArtifactPath, a: CacheDirectoryPath,
218 b: "llvmcache-" + UniqueKey);
219
220 Expected<FileCache> CacheOrErr =
221 localCache(CacheNameRef: "Debuginfod-client", TempFilePrefixRef: ".debuginfod-client", CacheDirectoryPathRef: CacheDirectoryPath);
222 if (!CacheOrErr)
223 return CacheOrErr.takeError();
224
225 FileCache Cache = *CacheOrErr;
226 // We choose an arbitrary Task parameter as we do not make use of it.
227 unsigned Task = 0;
228 Expected<AddStreamFn> CacheAddStreamOrErr = Cache(Task, UniqueKey, "");
229 if (!CacheAddStreamOrErr)
230 return CacheAddStreamOrErr.takeError();
231 AddStreamFn &CacheAddStream = *CacheAddStreamOrErr;
232 if (!CacheAddStream)
233 return std::string(AbsCachedArtifactPath);
234 // The artifact was not found in the local cache, query the debuginfod
235 // servers.
236 if (!HTTPClient::isAvailable())
237 return createStringError(EC: errc::io_error,
238 S: "No working HTTP client is available.");
239
240 if (!HTTPClient::IsInitialized)
241 return createStringError(
242 EC: errc::io_error,
243 S: "A working HTTP client is available, but it is not initialized. To "
244 "allow Debuginfod to make HTTP requests, call HTTPClient::initialize() "
245 "at the beginning of main.");
246
247 HTTPClient Client;
248 Client.setTimeout(Timeout);
249 for (StringRef ServerUrl : DebuginfodUrls) {
250 SmallString<64> ArtifactUrl;
251 sys::path::append(path&: ArtifactUrl, style: sys::path::Style::posix, a: ServerUrl, b: UrlPath);
252
253 // Perform the HTTP request and if successful, write the response body to
254 // the cache.
255 {
256 StreamedHTTPResponseHandler Handler(
257 [&]() { return CacheAddStream(Task, ""); }, Client);
258 HTTPRequest Request(ArtifactUrl);
259 Request.Headers = getHeaders();
260 Error Err = Client.perform(Request, Handler);
261 if (Err) {
262 consumeError(Err: Handler.abort());
263 return std::move(Err);
264 }
265 if ((Err = Handler.commit()))
266 return std::move(Err);
267
268 unsigned Code = Client.responseCode();
269 if (Code && Code != 200)
270 continue;
271 }
272
273 Expected<CachePruningPolicy> PruningPolicyOrErr =
274 parseCachePruningPolicy(PolicyStr: std::getenv(name: "DEBUGINFOD_CACHE_POLICY"));
275 if (!PruningPolicyOrErr)
276 return PruningPolicyOrErr.takeError();
277
278 Expected<bool> PrunedOrErr =
279 pruneCache(Path: CacheDirectoryPath, Policy: *PruningPolicyOrErr);
280 // Log the error but continue execution: failure to prune the cache is not
281 // fatal.
282 if (!PrunedOrErr)
283 logAllUnhandledErrors(E: PrunedOrErr.takeError(), OS&: WithColor::warning());
284
285 // Return the path to the artifact on disk.
286 return std::string(AbsCachedArtifactPath);
287 }
288
289 return createStringError(EC: errc::argument_out_of_domain, S: "build id not found");
290}
291
292DebuginfodLogEntry::DebuginfodLogEntry(const Twine &Message)
293 : Message(Message.str()) {}
294
295void DebuginfodLog::push(const Twine &Message) {
296 push(Entry: DebuginfodLogEntry(Message));
297}
298
299void DebuginfodLog::push(DebuginfodLogEntry Entry) {
300 {
301 std::lock_guard<std::mutex> Guard(QueueMutex);
302 LogEntryQueue.push(x: Entry);
303 }
304 QueueCondition.notify_one();
305}
306
307DebuginfodLogEntry DebuginfodLog::pop() {
308 {
309 std::unique_lock<std::mutex> Guard(QueueMutex);
310 // Wait for messages to be pushed into the queue.
311 QueueCondition.wait(lock&: Guard, p: [&] { return !LogEntryQueue.empty(); });
312 }
313 std::lock_guard<std::mutex> Guard(QueueMutex);
314 if (!LogEntryQueue.size())
315 llvm_unreachable("Expected message in the queue.");
316
317 DebuginfodLogEntry Entry = LogEntryQueue.front();
318 LogEntryQueue.pop();
319 return Entry;
320}
321
322DebuginfodCollection::DebuginfodCollection(ArrayRef<StringRef> PathsRef,
323 DebuginfodLog &Log,
324 ThreadPoolInterface &Pool,
325 double MinInterval)
326 : Log(Log), Pool(Pool), MinInterval(MinInterval) {
327 for (StringRef Path : PathsRef)
328 Paths.push_back(Elt: Path.str());
329}
330
331Error DebuginfodCollection::update() {
332 std::lock_guard<sys::Mutex> Guard(UpdateMutex);
333 if (UpdateTimer.isRunning())
334 UpdateTimer.stopTimer();
335 UpdateTimer.clear();
336 for (const std::string &Path : Paths) {
337 Log.push(Message: "Updating binaries at path " + Path);
338 if (Error Err = findBinaries(Path))
339 return Err;
340 }
341 Log.push(Message: "Updated collection");
342 UpdateTimer.startTimer();
343 return Error::success();
344}
345
346Expected<bool> DebuginfodCollection::updateIfStale() {
347 if (!UpdateTimer.isRunning())
348 return false;
349 UpdateTimer.stopTimer();
350 double Time = UpdateTimer.getTotalTime().getWallTime();
351 UpdateTimer.startTimer();
352 if (Time < MinInterval)
353 return false;
354 if (Error Err = update())
355 return std::move(Err);
356 return true;
357}
358
359Error DebuginfodCollection::updateForever(std::chrono::milliseconds Interval) {
360 while (true) {
361 if (Error Err = update())
362 return Err;
363 std::this_thread::sleep_for(rtime: Interval);
364 }
365 llvm_unreachable("updateForever loop should never end");
366}
367
368static bool hasELFMagic(StringRef FilePath) {
369 file_magic Type;
370 std::error_code EC = identify_magic(path: FilePath, result&: Type);
371 if (EC)
372 return false;
373 switch (Type) {
374 case file_magic::elf:
375 case file_magic::elf_relocatable:
376 case file_magic::elf_executable:
377 case file_magic::elf_shared_object:
378 case file_magic::elf_core:
379 return true;
380 default:
381 return false;
382 }
383}
384
385Error DebuginfodCollection::findBinaries(StringRef Path) {
386 std::error_code EC;
387 sys::fs::recursive_directory_iterator I(Twine(Path), EC), E;
388 std::mutex IteratorMutex;
389 ThreadPoolTaskGroup IteratorGroup(Pool);
390 for (unsigned WorkerIndex = 0; WorkerIndex < Pool.getMaxConcurrency();
391 WorkerIndex++) {
392 IteratorGroup.async(F: [&, this]() -> void {
393 std::string FilePath;
394 while (true) {
395 {
396 // Check if iteration is over or there is an error during iteration
397 std::lock_guard<std::mutex> Guard(IteratorMutex);
398 if (I == E || EC)
399 return;
400 // Grab a file path from the directory iterator and advance the
401 // iterator.
402 FilePath = I->path();
403 I.increment(ec&: EC);
404 }
405
406 // Inspect the file at this path to determine if it is debuginfo.
407 if (!hasELFMagic(FilePath))
408 continue;
409
410 Expected<object::OwningBinary<object::Binary>> BinOrErr =
411 object::createBinary(Path: FilePath);
412
413 if (!BinOrErr) {
414 consumeError(Err: BinOrErr.takeError());
415 continue;
416 }
417 object::Binary *Bin = std::move(BinOrErr.get().getBinary());
418 if (!Bin->isObject())
419 continue;
420
421 // TODO: Support non-ELF binaries
422 object::ELFObjectFileBase *Object =
423 dyn_cast<object::ELFObjectFileBase>(Val: Bin);
424 if (!Object)
425 continue;
426
427 BuildIDRef ID = getBuildID(Obj: Object);
428 if (ID.empty())
429 continue;
430
431 std::string IDString = buildIDToString(ID);
432 if (Object->hasDebugInfo()) {
433 std::lock_guard<sys::RWMutex> DebugBinariesGuard(DebugBinariesMutex);
434 (void)DebugBinaries.try_emplace(Key: IDString, Args: std::move(FilePath));
435 } else {
436 std::lock_guard<sys::RWMutex> BinariesGuard(BinariesMutex);
437 (void)Binaries.try_emplace(Key: IDString, Args: std::move(FilePath));
438 }
439 }
440 });
441 }
442 IteratorGroup.wait();
443 std::unique_lock<std::mutex> Guard(IteratorMutex);
444 if (EC)
445 return errorCodeToError(EC);
446 return Error::success();
447}
448
449Expected<std::optional<std::string>>
450DebuginfodCollection::getBinaryPath(BuildIDRef ID) {
451 Log.push(Message: "getting binary path of ID " + buildIDToString(ID));
452 std::shared_lock<sys::RWMutex> Guard(BinariesMutex);
453 auto Loc = Binaries.find(Key: buildIDToString(ID));
454 if (Loc != Binaries.end()) {
455 std::string Path = Loc->getValue();
456 return Path;
457 }
458 return std::nullopt;
459}
460
461Expected<std::optional<std::string>>
462DebuginfodCollection::getDebugBinaryPath(BuildIDRef ID) {
463 Log.push(Message: "getting debug binary path of ID " + buildIDToString(ID));
464 std::shared_lock<sys::RWMutex> Guard(DebugBinariesMutex);
465 auto Loc = DebugBinaries.find(Key: buildIDToString(ID));
466 if (Loc != DebugBinaries.end()) {
467 std::string Path = Loc->getValue();
468 return Path;
469 }
470 return std::nullopt;
471}
472
473Expected<std::string> DebuginfodCollection::findBinaryPath(BuildIDRef ID) {
474 {
475 // Check collection; perform on-demand update if stale.
476 Expected<std::optional<std::string>> PathOrErr = getBinaryPath(ID);
477 if (!PathOrErr)
478 return PathOrErr.takeError();
479 std::optional<std::string> Path = *PathOrErr;
480 if (!Path) {
481 Expected<bool> UpdatedOrErr = updateIfStale();
482 if (!UpdatedOrErr)
483 return UpdatedOrErr.takeError();
484 if (*UpdatedOrErr) {
485 // Try once more.
486 PathOrErr = getBinaryPath(ID);
487 if (!PathOrErr)
488 return PathOrErr.takeError();
489 Path = *PathOrErr;
490 }
491 }
492 if (Path)
493 return *Path;
494 }
495
496 // Try federation.
497 Expected<std::string> PathOrErr = getCachedOrDownloadExecutable(ID);
498 if (!PathOrErr)
499 consumeError(Err: PathOrErr.takeError());
500
501 // Fall back to debug binary.
502 return findDebugBinaryPath(ID);
503}
504
505Expected<std::string> DebuginfodCollection::findDebugBinaryPath(BuildIDRef ID) {
506 // Check collection; perform on-demand update if stale.
507 Expected<std::optional<std::string>> PathOrErr = getDebugBinaryPath(ID);
508 if (!PathOrErr)
509 return PathOrErr.takeError();
510 std::optional<std::string> Path = *PathOrErr;
511 if (!Path) {
512 Expected<bool> UpdatedOrErr = updateIfStale();
513 if (!UpdatedOrErr)
514 return UpdatedOrErr.takeError();
515 if (*UpdatedOrErr) {
516 // Try once more.
517 PathOrErr = getBinaryPath(ID);
518 if (!PathOrErr)
519 return PathOrErr.takeError();
520 Path = *PathOrErr;
521 }
522 }
523 if (Path)
524 return *Path;
525
526 // Try federation.
527 return getCachedOrDownloadDebuginfo(ID);
528}
529
530DebuginfodServer::DebuginfodServer(DebuginfodLog &Log,
531 DebuginfodCollection &Collection)
532 : Log(Log), Collection(Collection) {
533 cantFail(
534 Err: Server.get(UrlPathPattern: R"(/buildid/(.*)/debuginfo)", Handler: [&](HTTPServerRequest Request) {
535 Log.push(Message: "GET " + Request.UrlPath);
536 std::string IDString;
537 if (!tryGetFromHex(Input: Request.UrlPathMatches[0], Output&: IDString)) {
538 Request.setResponse(
539 {.Code: 404, .ContentType: "text/plain", .Body: "Build ID is not a hex string\n"});
540 return;
541 }
542 object::BuildID ID(IDString.begin(), IDString.end());
543 Expected<std::string> PathOrErr = Collection.findDebugBinaryPath(ID);
544 if (Error Err = PathOrErr.takeError()) {
545 consumeError(Err: std::move(Err));
546 Request.setResponse({.Code: 404, .ContentType: "text/plain", .Body: "Build ID not found\n"});
547 return;
548 }
549 streamFile(Request, FilePath: *PathOrErr);
550 }));
551 cantFail(
552 Err: Server.get(UrlPathPattern: R"(/buildid/(.*)/executable)", Handler: [&](HTTPServerRequest Request) {
553 Log.push(Message: "GET " + Request.UrlPath);
554 std::string IDString;
555 if (!tryGetFromHex(Input: Request.UrlPathMatches[0], Output&: IDString)) {
556 Request.setResponse(
557 {.Code: 404, .ContentType: "text/plain", .Body: "Build ID is not a hex string\n"});
558 return;
559 }
560 object::BuildID ID(IDString.begin(), IDString.end());
561 Expected<std::string> PathOrErr = Collection.findBinaryPath(ID);
562 if (Error Err = PathOrErr.takeError()) {
563 consumeError(Err: std::move(Err));
564 Request.setResponse({.Code: 404, .ContentType: "text/plain", .Body: "Build ID not found\n"});
565 return;
566 }
567 streamFile(Request, FilePath: *PathOrErr);
568 }));
569}
570
571} // namespace llvm
572