provcat.resolver

Resolver is the interface. TemplateResolver is the default implementation. It reads the schemes and stages sections of the configuration::

schemes:
  data+table:
    parts: [org, domain, env, family, name]   # names for authority + segments
    target: "lakefs://{org}-{domain}/{ref}/tables/{family}/{name}"
    ref: "{env}"                               # default for {ref}; may name parts
    match: {org: "[a-z0-9]+", domain: "[a-z0-9]+"}   # each part must match
  code:
    parts: [org, repo]
    rest: path              # extra segments are joined into {path}
    target: "github://{org}/{repo}/{path}"
    pass_selector: true     # hand ?at= on to the physical URI
  # tenant: org             # the part that names the tenant (see below)

stages:
  "data+table://acme/shared/prod/agreements/qa_outputs":
    production: "commit:b8a2f9c"

Selectors on a logical URI:

• branch:X, tag:X, commit:X set {ref} to X.
• version:N sets {version} to N. {ref} keeps its default.
• A bucket (the s3, gcs and azure drivers) keeps only branches in its path, and a fixed version goes in ?at=. So for a target whose store is a bucket, commit:ID keeps {ref} at its default and goes on to the physical URI as ?at=commit:ID. version:ID does the same when the target has no {version}. tag: is refused, because a bucket has no tags. The resolver asks refs_in_path which stores are buckets; the catalog gives it one that reads the attribute of the same name on each store. A resolver without it treats every store as lakeFS does.
• A selector that nothing uses is refused, never dropped. version: needs {version}, and branch:, tag: and commit: need {ref}, unless the target has {at}, the scheme has pass_selector, or the store is a bucket that takes the selector in ?at=.
• stage:NAME looks up NAME in stages and uses the selector stored there.
• ts:TIME keeps {ref} at its default, and goes on to the physical URI as ?at=ts:TIME, with or without pass_selector. Only the store can say which commit a branch had at TIME, so the lakefs and github drivers resolve it. A target without {ref} loses the branch, so the resolution keeps it as ts_branch. The catalog gives a GitHub store ?at=ts:BRANCH@TIME.

Template variables are the part names, the rest name, ref, version and at (the whole selector as kind:value). Each value is percent-encoded before it goes into the template, so a value can never add a path segment or a ?at= to the physical URI.

With pass_selector, the physical URI gets the selector that the resolver used: a stage becomes the selector it points at, and a scheme with a ref default passes branch:<ref> when the URI has no selector. With version:, only the version is passed.

tenant names the part that says whose a URI is, for example org. A resolver made for one tenant refuses a URI of another tenant of such a scheme. A scheme without tenant serves every tenant.

match gives a regular expression for a part. A URI whose part does not match the whole expression is refused, so that names such as lakeFS repository names stay valid and cannot run together.

Entries send one logical name, or every name under a prefix, somewhere other than the template of its scheme::

entries:
  "code://acme/tokenizer/prod":
    target: "github://acme/tokenizer/{path}?at=branch:prod"
  "code://acme/tokenizer/prod/weights":
    target: "hf://models/acme/tokenizer/{path}"
  "data+table://acme/shared/prod/corpora":
    target: "lakefs-acme://acme-corpora/{ref}/{path}"
    ref: main

• The longest key that is a prefix of the URI wins, by whole parts. A URI that no key matches goes to the template of its scheme.
• {path} is the rest of the URI after the key, each part encoded. A target without {path} serves only the URI that is its key.
• {ref} is for a store that keeps the branch in the path, such as lakeFS. branch:, tag: and commit: on the URI fill it, and ref is the default. A target without {ref} takes the selector of the URI in place of its own ?at=.
• ts:TIME keeps the branch of the target. A target that names a branch in ?at= gives it as ts_branch, as a template does. A target fixed to a tag or a commit refuses ts:.
• A target whose store is a bucket follows the bucket rules above: commit: and version: keep {ref} at ref and go on as ?at=, and tag: is refused. Any other store refuses version:.
• A stage of the URI comes first, and its selector then applies as above.
• A key must be a URI of a logical scheme, with no ?at=. Its parts must fit the parts and match of the scheme as far as the key goes. The store of a target is fixed text.

Resolution(logical: Uri, physical: Uri, via: tuple[str, ...] = (), ts_branch: str | None = None)

Resolver.handles(scheme: str) -> bool

Resolver.resolve(uri: Uri) -> Resolution

TemplateResolver(schemes: dict | None = None, stages: dict | None = None, tenant: str | None = None, entries: dict | None = None, refs_in_path: Callable[[str], bool | None] | None = None)

TemplateResolver.handles(scheme: str) -> bool

TemplateResolver.serves(uri: Uri) -> bool

TemplateResolver.resolve(uri: Uri) -> Resolution