fuchsia.pkg.rewrite

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

NameType
transaction request<EditTransaction>

List

Return an iterator over all rewrite rules.

  • request iterator is a request for an iterator.

Request

NameType
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

NameType
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.googlesource.com/fuchsia/+/master/docs/the-book/package_url.md

Request

NameType
url string

Response

NameType
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

NameType
iterator request<RuleIterator>

ResetAll

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

Request

NameType

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.googlesource.com/fuchsia/+/master/docs/the-book/package_url.md

Request

NameType
rule Rule

Response

NameType
status int32

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.

Request

NameType

Response

NameType
status int32

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

NameType

Response

NameType
rules vector<Rule>

STRUCTS

Engine_TestApply_Response

Defined in fuchsia.pkg.rewrite/generated

NameTypeDescriptionDefault
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/" }

NameTypeDescriptionDefault
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/generated

NameTypeDescription
response Engine_TestApply_Response
err int32

XUNIONS

Rule

Defined in fuchsia.pkg.rewrite/rewrite.fidl

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

NameTypeDescription
literal LiteralRule