PROTOCOLS

Engine

Defined in fuchsia.pkg.rewrite/rewrite.fidl

Manages fuchsia-pkg:// rewrite rules.

When a package resolver is asked to resolve a fuchsia-pkg URL, it must first iterate through its sequence of rewrite rules (given by List). The rewrite engine will rewrite the given URL with the first rule that:

• matches the given URL
• produces a valid URL when applied to the given URL If no rules match, the URL is resolved as-is.

This interface is intended to be implemented by package resolver components, and used by repository administration tools.

StartEditTransaction

Begins a rule edit transaction.

Request

Name	Type
transaction	request<EditTransaction>

List

Return an iterator over all rewrite rules.

• request iterator is a request for an iterator.

Request

Name	Type
iterator	request<RuleIterator>

ListStatic

Return an iterator over all static (immutable) rewrite rules. These rules are handled as lower priority than dynamic rules and cannot be modified (although they can be overridden) by EditTransactions.

• request iterator is a request for an iterator.

Request

Name	Type
iterator	request<RuleIterator>

TestApply

Rewrite the given url with the current rewrite rule set, returning the rewritten url. If no rules match or a rule matches but performs an identity transformation, this API returns url unchanged.

This API is intended only for reflecting on rule side effects. Using this API to pre-apply the rules, then passing the result to fuchsia.pkg/PackageResolver.Resolve would apply the rules twice.

• request url the url to rewrite.

• response rewritten the rewritten url.

• error ZX_ERR_INVALID_ARGS If url is not a valid fuchsia-pkg:// URL. See fuchsia-pkg URL.

fuchsia-pkg URL: https://fuchsia.dev/fuchsia-src/concepts/storage/package_url

Request

Name	Type
url	string

Response

Name	Type
result	Engine_TestApply_Result

EditTransaction

Defined in fuchsia.pkg.rewrite/rewrite.fidl

ListDynamic

Return an iterator over all dynamic (editable) rewrite rules. The iterator will reflect any changes made to the rewrite rules so far in this transaction.

• request iterator is a request for an iterator.

Request

Name	Type
iterator	request<RuleIterator>

ResetAll

Removes all dynamically configured rewrite rules, leaving only any statically configured rules.

Request

Name	Type

Add

Add a rewrite rule with highest priority. If rule already exists, this API will prioritize it over other rules.

• request rule the rewrite rule to persist.

• status ZX_OK if the rule was staged to be added.
• status ZX_ERR_INVALID_ARGS If url is not a valid fuchsia-pkg:// URL. See fuchsia-pkg URL.

fuchsia-pkg URL: https://fuchsia.dev/fuchsia-src/concepts/storage/package_url

Request

Name	Type
rule	Rule

Response

Name	Type
status	zx/status

Commit

Commit this transaction, or detect another transaction that committed before this one.

• status ZX_OK the staged edits were successfully committed.
• status ZX_ERR_UNAVAILABLE another transaction committed before this one.
• status ZX_ERR_ACCESS_DENIED editing dynamic rewrite rules is permanently disabled.

Request

Name	Type

Response

Name	Type
status	zx/status

RuleIterator

Defined in fuchsia.pkg.rewrite/rewrite.fidl

The iterator over all the rewrite rules defined in a Engine.

Next

Advance the iterator and return the next batch of rules.

• response rules a vector of Rule rules. Will return an empty vector when there are no more rules.

Request

Name	Type

Response

Name	Type
rules	vector<Rule>

STRUCTS

Engine_TestApply_Response

Defined in fuchsia.pkg.rewrite/rewrite.fidl

Name	Type	Description	Default
rewritten	string		No default

LiteralRule

Defined in fuchsia.pkg.rewrite/rewrite.fidl

A literal match and replacement rule.

Examples

Replaces example.com with test.example.com for all packages

{
    host_match: "example.com"
    host_replacement: "test.example.com"
    path_prefix_match: "/"
    path_prefix_replacement: "/"
}

Replaces example.com with test.example.com for fuchsia-pkg://example.com/rolldice. A package called "rolldice" in another repo would not be rewritten.

{
    host_match: "example.com"
    host_replacement: "test.example.com"
    path_prefix_match: "/rolldice"
    path_prefix_replacement: "/rolldice"
}

Redirects all packages under "fuchsia-pkg://example.com/examples/" to "fuchsia-pkg://example.com/examples/beta/".

{
    host_match: "example.com"
    host_replacement: "example.com"
    path_prefix_match: "/examples/"
    path_prefix_replacement: "/examples/beta/"
}

Name	Type	Description	Default
host_match	string	The exact hostname to match.	No default
host_replacement	string	The new hostname to replace the matched host_match with.	No default
path_prefix_match	string	The absolute path to a package or directory to match against. If path_prefix_match ends with '/', it will match any packages or subdirectories below the matched path. If path_prefix_match does not end with '/', it will be interpreted as as an exact match. Examples "/example" only matches a package called "example" at the root of the repo. "/parent/examples" and "/examples" would not match. "/example/" would match any package under the "example" path at the root of the repo. For example, "/example/", "/example/package" would both match.	No default
path_prefix_replacement	string	The absolute path to a single package or a directory to replace the matched path_prefix_match with. path_prefix_match and path_prefix_replacement must both match directories or both match exact packages. Mixing the two forms is not allowed.	No default

UNIONS

Engine_TestApply_Result

Defined in fuchsia.pkg.rewrite/rewrite.fidl

Name	Type	Description
response	Engine_TestApply_Response
err	zx/status

XUNIONS

Rule

Defined in fuchsia.pkg.rewrite/rewrite.fidl

A rewrite rule, represented as an xunion for future compatibility.

Name	Type	Description
literal	LiteralRule