Transferring a dataset lineage from one account to another: offers, an inbox, signed links and limits
  • Python 88.7%
  • HTML 10.8%
  • Mako 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-01 12:31:50 +01:00
docs feat: offers of a dataset and its versions to another account, out of dataset: an inbox in the account area, a mail with a signed link sent once, one answer whether or not the account exists, offers that lapse, locked answers, one live offer per lineage and a daily limit (DL-17) 2026-10-25 18:00:47 +01:00
src refactor: the framework resolves dataset_transfer's settings from the schema, and config.py reads no environment 2026-10-31 16:50:45 +01:00
.gitignore chore: scaffold splent_feature_dataset_transfer with splent feature:create 2026-10-25 17:28:27 +01:00
COPYING chore: scaffold splent_feature_dataset_transfer with splent feature:create 2026-10-25 17:28:27 +01:00
COPYING.LESSER chore: scaffold splent_feature_dataset_transfer with splent feature:create 2026-10-25 17:28:27 +01:00
MANIFEST.in chore: scaffold splent_feature_dataset_transfer with splent feature:create 2026-10-25 17:28:27 +01:00
pyproject.toml chore: release splent_io/splent_feature_dataset_transfer to v0.2.0 2026-11-01 12:31:50 +01:00
README.md docs: dataset's migration is dataset0011_transfers_moved 2026-10-25 19:34:19 +01:00

splent_feature_dataset_transfer

The dataset_transfer feature of a SPLENT product line.

Offers of a dataset, and every version of it, to another account (DL-17 of uvlhub 3.0). The owner offers it, the account it is offered to accepts or declines it, and only then does the lineage change owner. It was part of splent_feature_dataset up to 0.13.0, reachable through API v1 alone; it is an optional feature of the OpenHubs line now (D10), with a page on the web and the rules below. A hub without it has no transfers at all.

A SPLENT feature is a Python package that a product composes with others. Its models, routes, services, templates and hooks are registered when the product starts. What this feature provides and requires is listed in the [tool.splent.contract] section of pyproject.toml, which splent feature:contract --write keeps in sync with the source.

Use it in a product

splent feature:add splent_feature_dataset_transfer

It requires auth (1.23.0 or later), dataset (0.14.0 or later) and mail (1.5.0 or later). The change of the OpenHubs model that goes with it is docs/openhubs_spl.uvl.patch: an optional node under repositorio, with dataset_transfer => dataset, => auth and => mail.

API v1's transfer routes are served by splent_feature_dataset_api 0.4.0 or later in a product that has both (see "API v1" below).

The rules (DL-17)

  • One answer, whether or not the account exists. An offer names its account by its address (the web, API v1) or by its id (API v1). When that is not an account that may sign in (none at that address, none with that id, or one switched off) the offer is kept all the same, with nobody behind it, and the sender is answered exactly as for an account: the same page, the same 202, the same listing, and the offer lapses as an unanswered one does. Nobody can accept it. So no answer says which addresses have an account or which accounts are switched off (A08-10), and while an offer waits its sender sees whom they named, never more: the address, or the id they gave. Once the account answers, the sender learns it.
  • A mail with a signed link. An account that may sign in is mailed the offer, with a link to its page (/transfers/offers/<token>), signed with the product's key for tokens (the framework's splent_framework.keys, salt dataset-transfer-offer) and naming the offer and its recipient. The link opens nothing by itself: the page answers its recipient, signed in, and is a 404 for anyone else, a link that is not genuine, or one older than any offer lives. The mail carries a token, so mail sends it once, at once, keeps it with its link cut, and never sends it again; the answers to the sender carry no secret, and are retried.
  • Offers lapse. DATASET_TRANSFER_EXPIRY_DAYS (14) after it was made an unanswered offer is cancelled as expired, the moment anything reads it: an answer, which is refused; a listing; a new offer of its lineage, which then goes through. Each new offer also settles a few others that lapsed, so there is no cron to run.
  • Locked answers. Accept, decline and cancel lock the offer (SELECT ... FOR UPDATE) and read it again before they answer, and an acceptance locks the lineage too and records the answer in the transaction that moves it (dataset's LineageService.change_owner, with commit=False). An acceptance and a cancellation at the same time end one way, never both (A08-23, A10-09).
  • One live offer per lineage. pending_key is lineage:<root id> while an offer is pending and empty after, under a unique key: a second offer of any version of the lineage is refused while the first waits, even when both are made at the same time.
  • A limit per account and day. An account makes DATASET_TRANSFER_MAX_OFFERS_PER_DAY (10) offers in a day at most, whatever became of them and whether or not they reached an account, so the offers are nobody's way to mail strangers. Past it, the web says so and API v1 answers 429 transfer_limit, with Retry-After.

What moves on acceptance, and what is refused before (a lineage split across accounts, one that changed owner after the offer), is dataset's: the whole lineage moves as a unit, with any file still in its old owner's folder.

On the web

  • The offer, from the dataset's page: its owner sees "Offer to another account" among its actions (dataset's dataset.view.actions slot), which opens /datasets/<id>/transfer, an address and an optional note. While an offer of the lineage waits, the page says to whom it went, and offers to withdraw it.
  • The inbox, /transfers: Transfers in the Account section of the menu and of the user menu, after Edit profile, with the count of the offers that wait for the account's answer. What waits for its answer, with Accept and Decline; what it offered, with Withdraw; and what became of the rest.
  • The page of an offer, which the mail links to, with Accept and Decline. It carries its token in the address, so it is sent with auth's keep_token_private: no Referer, no cache, no script of another site.

Every page reads in the request's language (es included), and so do the refusals; API v1 answers them in English, as it always did.

API v1

The five routes uvlhub 2.12's clients call are dataset_api's, which asks this feature's TransferService (registered under that name, the one dataset gave it):

Route Methods
/api/v1/datasets/<id>/transfer POST
/api/v1/datasets/transfers GET
/api/v1/datasets/transfers/<id>/accept POST
/api/v1/datasets/transfers/<id>/decline POST
/api/v1/datasets/transfers/<id>/cancel POST

They keep their methods, statuses and keys (CO-1). What changed is what DL-17 asks: an offer to an address or an id with no account that may sign in is a 202 like any other, where 2.12 answered 404 or 400, and the to_user_id of an offer to an address is null for its sender until the account answers. A product without this feature serves none of them, and dataset_api registers no datasets:transfer scope.

Configuration

Setting Default Means
DATASET_TRANSFER_EXPIRY_DAYS 14 Days an offer waits for its answer (1 to 365)
DATASET_TRANSFER_MAX_OFFERS_PER_DAY 10 Offers an account makes in a day (0 for no limit)

Both are derivation parameters ([tool.splent.config_schema]): the product decides them.

The table

dataset_transfer_request, the one dataset kept, with its rows and its ids, which uvlhub 2.12's mails and API answers carry.

  • dataset_transfer0001_requests takes it over as uvl took featuremodel's table over: a database dataset migrated has it already, and the revision leaves it alone, so nothing is created twice and no row moves; a new database gets it here, as dataset's 7e2d3e88f41c made it. Its downgrade drops it only when it holds no offer. dataset 0.14.0's dataset0011_transfers_moved drops the table dataset made when it is empty and not taken over yet, so a hub without this feature keeps no table of it.
  • dataset_transfer0002_offer_rules adds to_address and to_named_id (the account as its sender named it), expires_at, cancel_reason (sender, expired, migration or duplicate) and pending_key (unique), and lets to_user_id be NULL. A pending offer gets the default window from the day of the migration; two pending offers of one lineage, which only check-then-act could make, keep the oldest, and the others are cancelled as duplicate. The downgrade lets go of the offers that reached no account, which the older table cannot hold.

An account that goes takes the offers it made or received with it, in the transaction of its deletion (auth's user-deleting).

Moving from uvlhub 2.12 (D13 b)

The migrator loads dataset_transfer_request with its ids. An offer still pending at the cutover is cancelled: status CANCELLED, resolved_at the cutover, cancel_reason migration, no pending_key; the others keep their state. to_address, to_named_id and expires_at stay NULL for every row: an offer of 2.12 names its recipient by its account, as it did. The notices to both parties are the migrator's, held in mail's outbox until the end of RB-2.

Develop

splent feature:test splent_feature_dataset_transfer
splent feature:contract splent_feature_dataset_transfer

A product that does not declare it tests it in a neutral app, with the releases of what it requires; --with splent_feature_dataset loads dataset's working copy instead, until dataset 0.14.0 is released.

Release

splent feature:release splent_feature_dataset_transfer --dry-run --bump minor
splent feature:release splent_feature_dataset_transfer

The first command rehearses the release and changes nothing. The second publishes it to the git forge and to PyPI, and a PyPI version is permanent.