HTTP and archive helpers for the whole editor. More...

#include <C:/Users/kirby/Documents/Github/deki/deki-editor/deki-editor/include/deki-editor/EditorHttpUtils.h>

Classes
struct	ArchiveLink
	A symbolic link in an archive: its entry name and the path it points to, as the archive stores them. More...

Static Public Member Functions
static std::string	FetchUrl (const std::string &url)
	GETs a URL and returns the body, or "" on any failure.
static bool	IsAllowedUrl (const std::string &url, std::string &reason)
	The rule every fetch and download checks first: https://, at most 2048 characters, printable ASCII without quoting metacharacters.
static bool	DownloadFile (const std::string &url, const std::string &localPath, std::atomic< bool > *cancelFlag=nullptr, HttpStatusCallback status=nullptr)
	Downloads a URL to a local file.
static bool	DownloadFileVerified (const std::string &url, const std::string &localPath, const std::string &expectedSha256, std::atomic< bool > *cancelFlag=nullptr, HttpStatusCallback status=nullptr, bool allowUnpinned=false)
	Downloads and checks the file against an expected lowercase hex SHA-256.
static std::string	Sha256File (const std::string &path)
	SHA-256 of a file as lowercase hex, or "" if it cannot be read.
static bool	ExtractZip (const std::string &zipPath, const std::string &destDir, HttpStatusCallback status=nullptr, std::string *error=nullptr)
	Extracts a zip into destDir.
static bool	ParseArchiveLinks (const std::string &names, const std::string &verbose, std::vector< ArchiveLink > &out, std::string &error)
	The links in an archive, read from tar -tf (its entry names, one per line) and tar -tvf (the same entries in the same order; a link's line starts with 'l' and ends "name -> target").
static bool	MaterializeArchiveLinks (const std::string &destDir, const std::vector< ArchiveLink > &links, std::string &error)
	Puts a copy of each link's target where the link would be, under destDir: a file is copied, a directory copied whole, and a link to another link once that one is in place.
static bool	ZipEntriesAreSafe (const std::string &zipPath, std::string &reason)
	Lists the archive and applies IsSafeArchiveEntry to every entry.
static bool	IsSafeArchiveEntry (const std::string &entry)
	Checks one archive entry name: no absolute path, drive letter, UNC prefix, control character or ".." segment (either separator).
static bool	ParseGitHubRelease (const std::string &json, const std::string &assetPattern, const std::string &repo, std::string &outVersion, std::string &outDownloadUrl)
	Reads GitHub "latest release" JSON: the tag, and the first asset whose browser_download_url contains assetPattern.

Static Public Attributes
static constexpr int	kMaxRedirects = 10

Detailed Description

HTTP and archive helpers for the whole editor.

The one place that uses WinHTTP (Windows) and curl (Unix).

Member Function Documentation

◆ FetchUrl()

std::string DekiEditor::EditorHttpUtils::FetchUrl ( const std::string & url )

static

GETs a URL and returns the body, or "" on any failure.

https only (IsAllowedUrl). No shell is involved on any platform.

◆ IsAllowedUrl()

bool DekiEditor::EditorHttpUtils::IsAllowedUrl	(	const std::string &	url,
		std::string &	reason )

static

The rule every fetch and download checks first: https://, at most 2048 characters, printable ASCII without quoting metacharacters.

◆ DownloadFile()

bool DekiEditor::EditorHttpUtils::DownloadFile	(	const std::string &	url,
		const std::string &	localPath,
		std::atomic< bool > *	cancelFlag = nullptr,
		HttpStatusCallback	status = nullptr )

static

Downloads a URL to a local file.

cancelFlag (optional) stops the download when set; status (optional) gets progress lines.

Follows up to kMaxRedirects redirects, in a loop. A redirect may not downgrade https to http.

◆ DownloadFileVerified()

bool DekiEditor::EditorHttpUtils::DownloadFileVerified	(	const std::string &	url,
		const std::string &	localPath,
		const std::string &	expectedSha256,
		std::atomic< bool > *	cancelFlag = nullptr,
		HttpStatusCallback	status = nullptr,
		bool	allowUnpinned = false )

static

Downloads and checks the file against an expected lowercase hex SHA-256.

What is fetched here gets run (toolchain archives become the compilers that build the user's firmware), so an unchecked download trusts both the network and the mirror. On a mismatch the file is deleted and this returns false.

An empty expectedSha256 is refused unless allowUnpinned is set (only for board-pack sources the user added); then the check is skipped and logged, so an unpinned download is visible. The built-in toolchain definitions pin every archive.

◆ Sha256File()

std::string DekiEditor::EditorHttpUtils::Sha256File ( const std::string & path )

static

SHA-256 of a file as lowercase hex, or "" if it cannot be read.

◆ ExtractZip()

bool DekiEditor::EditorHttpUtils::ExtractZip	(	const std::string &	zipPath,
		const std::string &	destDir,
		HttpStatusCallback	status = nullptr,
		std::string *	error = nullptr )

static

Extracts a zip into destDir.

Before writing anything, refuses an archive with entries that would land outside destDir (ZipEntriesAreSafe). On Windows a symbolic link in the archive is extracted as a copy of what it points to (MaterializeArchiveLinks): tar.exe cannot create links without administrator rights or Developer Mode, and failing on them failed the whole extract. error, when given, says why it failed.

◆ ParseArchiveLinks()

bool DekiEditor::EditorHttpUtils::ParseArchiveLinks	(	const std::string &	names,
		const std::string &	verbose,
		std::vector< ArchiveLink > &	out,
		std::string &	error )

static

The links in an archive, read from tar -tf (its entry names, one per line) and tar -tvf (the same entries in the same order; a link's line starts with 'l' and ends "name -> target").

False, with error, when the two listings do not line up.

◆ MaterializeArchiveLinks()

bool DekiEditor::EditorHttpUtils::MaterializeArchiveLinks	(	const std::string &	destDir,
		const std::vector< ArchiveLink > &	links,
		std::string &	error )

static

Puts a copy of each link's target where the link would be, under destDir: a file is copied, a directory copied whole, and a link to another link once that one is in place.

False, with error, when a target is absolute or outside destDir. A link to nothing is left out, as such a link would lead nowhere either.

◆ ZipEntriesAreSafe()

bool DekiEditor::EditorHttpUtils::ZipEntriesAreSafe	(	const std::string &	zipPath,
		std::string &	reason )

static

Lists the archive and applies IsSafeArchiveEntry to every entry.

◆ IsSafeArchiveEntry()

bool DekiEditor::EditorHttpUtils::IsSafeArchiveEntry ( const std::string & entry )

static

Checks one archive entry name: no absolute path, drive letter, UNC prefix, control character or ".." segment (either separator).

◆ ParseGitHubRelease()

bool DekiEditor::EditorHttpUtils::ParseGitHubRelease	(	const std::string &	json,
		const std::string &	assetPattern,
		const std::string &	repo,
		std::string &	outVersion,
		std::string &	outDownloadUrl )

static

Reads GitHub "latest release" JSON: the tag, and the first asset whose browser_download_url contains assetPattern.

When repo ("owner/name") is given, the asset must live under that repository's releases; a release body naming any other host is rejected whole.

Member Data Documentation

◆ kMaxRedirects

int DekiEditor::EditorHttpUtils::kMaxRedirects = 10

staticconstexpr

The documentation for this class was generated from the following file:

deki-editor/include/deki-editor/EditorHttpUtils.h

Classes

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ FetchUrl()

◆ IsAllowedUrl()

◆ DownloadFile()

◆ DownloadFileVerified()

◆ Sha256File()

◆ ExtractZip()

◆ ParseArchiveLinks()

◆ MaterializeArchiveLinks()

◆ ZipEntriesAreSafe()

◆ IsSafeArchiveEntry()

◆ ParseGitHubRelease()

Member Data Documentation

◆ kMaxRedirects