Skip to content

hide implementation detail and update readme #855

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 30, 2025
Merged

hide implementation detail and update readme #855

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
87a6542
hide implementation detail
anonrig Jan 30, 2025
78eee44
update readme
anonrig Jan 30, 2025
32c0092
add required template for friend classes
anonrig Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 68 additions & 83 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ Ada is a fast and spec-compliant URL parser written in C++.
Specification for URL parser can be found from the
[WHATWG](https://url.spec.whatwg.org/#url-parsing) website.

Ada library also includes a [URLPattern](https://url.spec.whatwg.org/#urlpattern) implementation
that is compatible with the [web-platform tests](https://github.com/web-platform-tests/wpt/tree/master/urlpattern).

The Ada library passes the full range of tests from the specification,
across a wide range of platforms (e.g., Windows, Linux, macOS). It fully
supports the relevant [Unicode Technical Standard](https://www.unicode.org/reports/tr46/#ToUnicode).
Expand All @@ -19,16 +22,11 @@ The WHATWG URL specification has been adopted by most browsers. Other tools, su
standard libraries, follow the RFC 3986. The following table illustrates possible differences in practice
(encoding of the host, encoding of the path):

| string source | string value |
|:--------------|:--------------|
| input string | https://www.7‑Eleven.com/Home/Privacy/Montréal |
| string source | string value |
|:------------------------|:------------------------------------------------------------|
| input string | https://www.7‑Eleven.com/Home/Privacy/Montréal |
| ada's normalized string | https://www.xn--7eleven-506c.com/Home/Privacy/Montr%C3%A9al |
| curl 7.87 | (returns the original unchanged) |

### Requirements

The project is otherwise self-contained and it has no dependency.
A recent C++ compiler supporting C++20. We test GCC 12 or better, LLVM 12 or better and Microsoft Visual Studio 2022.
| curl 7.87 | (returns the original unchanged) |

## Ada is fast.

Expand All @@ -50,9 +48,12 @@ Ada has improved the performance of the popular JavaScript environment Node.js:

The Ada library is used by important systems besides Node.js such as Redpanda, Kong, Telegram and Cloudflare Workers.

[![the ada library](http://img.youtube.com/vi/tQ-6OWRDsZg/0.jpg)](https://www.youtube.com/watch?v=tQ-6OWRDsZg)<br />

### Requirements

[![the ada library](http://img.youtube.com/vi/tQ-6OWRDsZg/0.jpg)](https://www.youtube.com/watch?v=tQ-6OWRDsZg)<br />
The project is otherwise self-contained and it has no dependency.
A recent C++ compiler supporting C++20. We test GCC 12 or better, LLVM 14 or better and Microsoft Visual Studio 2022.

## Installation

Expand All @@ -67,8 +68,8 @@ Linux or macOS users might follow the following instructions if they have a rece

1. Pull the library in a directory
```
wget https://github.com/ada-url/ada/releases/download/v2.6.10/ada.cpp
wget https://github.com/ada-url/ada/releases/download/v2.6.10/ada.h
wget https://github.com/ada-url/ada/releases/download/v3.0.0/ada.cpp
wget https://github.com/ada-url/ada/releases/download/v3.0.00/ada.h
```
2. Create a new file named `demo.cpp` with this content:
```C++
Expand Down Expand Up @@ -131,7 +132,7 @@ components (path, host, and so forth).
- Parse and validate a URL from an ASCII or a valid UTF-8 string.

```cpp
auto url = ada::parse("https://www.google.com");
auto url = ada::parse<ada::url_aggregator>("https://www.google.com");
if (url) { /* URL is valid */ }
```

Expand All @@ -140,89 +141,45 @@ accessing it when you are not sure that it will succeed. The following
code is unsafe:

```cpp
auto url = ada::parse("some bad url");
auto> url = ada::parse<ada::url_aggregator>("some bad url");
url->get_href();
```

You should do...

```cpp
auto url = ada::parse("some bad url");
if(url) {
// next line is now safe:
url->get_href();
} else {
// report a parsing failure
}
```

For simplicity, in the examples below, we skip the check because
we know that parsing succeeds. All strings are assumed to be valid
UTF-8 strings.

### Examples
## Examples

- Get/Update credentials
## URL Parser

```cpp
auto url = ada::parse("https://www.google.com");
url->set_username("username");
```c++
auto url = ada::parse<ada::url_aggregator>("https://www.google.com");

url->set_username("username"); // Update credentials
url->set_password("password");
// ada->get_href() will return "https://username:[email protected]/"
```

- Get/Update Protocol

```cpp
auto url = ada::parse("https://www.google.com");
url->set_protocol("wss");
url->set_protocol("wss"); // Update protocol
// url->get_protocol() will return "wss:"
// url->get_href() will return "wss://www.google.com/"
```

- Get/Update host

```cpp
auto url = ada::parse("https://www.google.com");
url->set_host("github.com");
url->set_host("github.com"); // Update host
// url->get_host() will return "github.com"
// you can use `url.set_hostname` depending on your usage.
```

- Get/Update port

```cpp
auto url = ada::parse("https://www.google.com");
url->set_port("8080");
url->set_port("8080"); // Update port
// url->get_port() will return "8080"
```

- Get/Update pathname

```cpp
auto url = ada::parse("https://www.google.com");
url->set_pathname("/my-super-long-path")
url->set_pathname("/my-super-long-path"); // Update pathname
// url->get_pathname() will return "/my-super-long-path"
```

- Get/Update search/query

```cpp
auto url = ada::parse("https://www.google.com");
url->set_search("target=self");
url->set_search("target=self"); // Update search
// url->get_search() will return "?target=self"
```

- Get/Update hash/fragment

```cpp
auto url = ada::parse("https://www.google.com");
url->set_hash("is-this-the-real-life");
url->set_hash("is-this-the-real-life"); // Update hash/fragment
// url->get_hash() will return "#is-this-the-real-life"
```
For more information about command-line options, please refer to the [CLI documentation](docs/cli.md).

- URL search params
### URL Search Params

```cpp
ada::url_search_params search_params("a=b&c=d&e=f");
Expand All @@ -236,6 +193,40 @@ while (keys.has_next()) {
}
```

### URLPattern

Our implementation doesn't provide a regex engine and leaves the decision of choosing the right engine to the user.
This is done as a security measure since the default std::regex engine is not safe and open to DDOS attacks.
Runtimes like Node.js and Cloudflare Workers use the V8 regex engine, which is safe and performant.

```cpp
// Define a regex engine that conforms to the following interface
// For example we will use v8 regex engine

class v8_regex_provider {
public:
v8_regex_provider() = default;
using regex_type = v8::Global<v8::RegExp>;
static std::optional<regex_type> create_instance(std::string_view pattern,
bool ignore_case);
static std::optional<std::vector<std::optional<std::string>>> regex_search(
std::string_view input, const regex_type& pattern);
static bool regex_match(std::string_view input, const regex_type& pattern);
};

// Define a URLPattern
auto pattern = ada::parse_url_pattern<v8_regex_provider>("/books/:id(\\d+)", "https://example.com");

// Check validity
if (!pattern) { return EXIT_FAILURE; }

// Match a URL
auto match = pattern->match("https://example.com/books/123");

// Test a URL
auto matched = pattern->test("https://example.com/books/123");
```

### C wrapper

See the file `include/ada_c.h` for our C interface. We expect ASCII or UTF-8 strings.
Expand Down Expand Up @@ -298,23 +289,21 @@ c++ demo.o ada.o -o cdemo
./cdemo
```

### Command-line interface

For more information about command-line options, please refer to the [CLI documentation](docs/cli.md).

### CMake dependency

See the file `tests/installation/CMakeLists.txt` for an example of how you might use ada from your own
CMake project, after having installed ada on your system.

## Installation

### Homebrew

Ada is available through [Homebrew](https://formulae.brew.sh/formula/ada-url#default).
You can install Ada using `brew install ada-url`.

## Contributing

### Building

Ada uses cmake as a build system. It's recommended you to run the following commands to build it locally.
Ada uses cmake as a build system, but also supports Bazel. It's recommended you to run the following
commands to build it locally.

Without tests:

Expand All @@ -325,16 +314,13 @@ With tests (requires git):
- **Build**: `cmake -B build -DADA_TESTING=ON && cmake --build build`
- **Test**: `ctest --output-on-failure --test-dir build`


With tests (requires available local packages):

- **Build**: `cmake -B build -DADA_TESTING=ON -D CPM_USE_LOCAL_PACKAGES=ON && cmake --build build`
- **Test**: `ctest --output-on-failure --test-dir build`

Windows users need additional flags to specify the build configuration, e.g. `--config Release`.



The project can also be built via docker using default docker file of repository with following commands.

`docker build -t ada-builder . && docker run --rm -it -v ${PWD}:/repo ada-builder`
Expand All @@ -352,5 +338,4 @@ Our tests include third-party code and data. The benchmarking code includes thir

### Further reading


* Yagiz Nizipli, Daniel Lemire, [Parsing Millions of URLs per Second](https://doi.org/10.1002/spe.3296), Software: Practice and Experience 54(5) May 2024.
8 changes: 4 additions & 4 deletions include/ada/url_pattern-inl.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,15 +193,15 @@ url_pattern_component<regex_provider>::compile(

template <url_pattern_regex::regex_concept regex_provider>
result<std::optional<url_pattern_result>> url_pattern<regex_provider>::exec(
const url_pattern_input& input, std::string_view* base_url) {
const url_pattern_input& input, const std::string_view* base_url) {
// Return the result of match given this's associated URL pattern, input, and
// baseURL if given.
return match(input, base_url);
}

template <url_pattern_regex::regex_concept regex_provider>
result<bool> url_pattern<regex_provider>::test(const url_pattern_input& input,
std::string_view* base_url) {
result<bool> url_pattern<regex_provider>::test(
const url_pattern_input& input, const std::string_view* base_url) {
// TODO: Optimization opportunity. Rather than returning `url_pattern_result`
// Implement a fast path just like `can_parse()` in ada_url.
// Let result be the result of match given this's associated URL pattern,
Expand All @@ -215,7 +215,7 @@ result<bool> url_pattern<regex_provider>::test(const url_pattern_input& input,

template <url_pattern_regex::regex_concept regex_provider>
result<std::optional<url_pattern_result>> url_pattern<regex_provider>::match(
const url_pattern_input& input, std::string_view* base_url_string) {
const url_pattern_input& input, const std::string_view* base_url_string) {
std::string protocol{};
std::string username{};
std::string password{};
Expand Down
32 changes: 15 additions & 17 deletions include/ada/url_pattern.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@

#include "ada/implementation.h"
#include "ada/expected.h"
#include "ada/parser.h"
#include "ada/url_pattern_init.h"

#include <string>
#include <unordered_map>
Expand All @@ -18,13 +20,6 @@
#endif // ADA_TESTING

namespace ada {
namespace parser {
template <typename result_type, typename url_pattern_init,
typename url_pattern_options, typename regex_provider>
tl::expected<result_type, errors> parse_url_pattern_impl(
std::variant<std::string_view, url_pattern_init> input,
const std::string_view* base_url, const url_pattern_options* options);
} // namespace parser

enum class url_pattern_part_type : uint8_t {
// The part represents a simple fixed text string.
Expand Down Expand Up @@ -234,20 +229,23 @@ class url_pattern {
/**
* @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-exec
*/
result<std::optional<url_pattern_result>> exec(const url_pattern_input& input,
std::string_view* base_url);
result<std::optional<url_pattern_result>> exec(
const url_pattern_input& input,
const std::string_view* base_url = nullptr);

/**
* @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-test
*/
result<bool> test(const url_pattern_input& input, std::string_view* base_url);
result<bool> test(const url_pattern_input& input,
const std::string_view* base_url = nullptr);

/**
* @see https://urlpattern.spec.whatwg.org/#url-pattern-match
* This function expects a valid UTF-8 string if input is a string.
*/
result<std::optional<url_pattern_result>> match(
const url_pattern_input& input, std::string_view* base_url_string);
const url_pattern_input& input,
const std::string_view* base_url_string = nullptr);

// @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-protocol
[[nodiscard]] std::string_view get_protocol() const ada_lifetime_bound;
Expand Down Expand Up @@ -286,6 +284,12 @@ class url_pattern {
}
#endif // ADA_TESTING

template <url_pattern_regex::regex_concept P>
friend tl::expected<url_pattern<P>, errors> parser::parse_url_pattern_impl(
std::variant<std::string_view, url_pattern_init> input,
const std::string_view* base_url, const url_pattern_options* options);

private:
url_pattern_component<regex_provider> protocol_component{};
url_pattern_component<regex_provider> username_component{};
url_pattern_component<regex_provider> password_component{};
Expand All @@ -295,12 +299,6 @@ class url_pattern {
url_pattern_component<regex_provider> search_component{};
url_pattern_component<regex_provider> hash_component{};
bool ignore_case_ = false;

template <typename result_type, typename url_pattern_init,
typename url_pattern_options, typename regex_provider_for_parse_url>
friend tl::expected<result_type, errors> parser::parse_url_pattern_impl(
std::variant<std::string_view, url_pattern_init> input,
const std::string_view* base_url, const url_pattern_options* options);
};

} // namespace ada
Expand Down
Loading
Loading