Crate onetaskgraph_plugin_api

Expand description

The contract every onetaskgraph source is written against.

This crate holds exactly what a plugin author needs in order to implement a source, and nothing else: the two traits, the work types, the query and paging types, the capability declaration, and the error enum. The engine that drives sources lives in onetaskgraph-core, and no plugin crate may depend on it: deny.toml permits that crate exactly one wrapper, the binary, failing the required deny job, and scripts/check-plugin-isolation.sh reads the real cargo metadata graph inside just check.

Keeping this crate still is the point. Every change here rebuilds and re-tests every plugin, which is exactly the cost the split exists to avoid paying on an ordinary engine change. When a new type could plausibly sit on either side, it belongs in onetaskgraph-core unless a trait signature names it.

Structs§

Asset: One asset a record holds, as a read reports it.
AssetName: One asset’s name: a bare file name ending in an accepted image extension.
AssetPayload: One asset a create or an update carries to a destination.
AssetUpload: What a hosted source uploaded for one asset of one record: the bytes’ SHA-256 and the URL it serves them at.
AssetUploads: The value of MetadataKey::ASSETS_KEY on a destination record: what its hosted source uploaded, by asset name.
AssetWrite: The assets a create or an update of one task or document carries.
AssetsWritten: What an asset-carrying write answers with: where the record now is, and the content the destination stored.
BatchComment: One comment of a batch: a new comment on one existing task, held to the version the caller read when if_version names one.
BatchUpdate: One update of a batch: a targeted update of one existing task, held to the version the caller read when if_version names one, and written only while the task holds one of the priorities when_priority names when it names any.
BodySize: How large the body one write of an item would store is, as its destination counts it, and the most that destination holds in one.
Capabilities: One source’s declared abilities.
Comment: One comment on a task, as its source holds it.
CommentBody: What a comment says: anything at all, except nothing.
CommentCopy: One comment a copy writes: what it says, and the comment it is a copy of.
CommentOrigin: Where a copied comment came from: the comment as its origin holds it.
Cursor: A plugin-defined resume token. The engine stores and returns one; it never interprets one.
DependencyEdge: A dependency between two work items.
DependencyEndpoint: One endpoint of a dependency edge.
Designator: Names a tracker without conveying anything about it: <plugin>/<64 lowercase hex>, the SHA-256 of <plugin>\n<identifier> over the backend’s own opaque identifier of itself — a Linear workspace’s organization id, a GitHub Project’s node id — or, for a plugin whose backend has none, alias/<public_alias>, the alias every host’s configuration of that tracker declares identically.
Document: One piece of information that lives in a project and is not work.
DocumentQuery: A filter over a source’s documents.
DocumentVersionCoverage: Which parts of a document a source’s change token — its Document::version — vouches for.
Health: Whether a source is answering right now.
HeldTask: The item one source holds for an issue — a task, or a project such as a plan’s home card — as far as moving it to done needs it.
HeldVersion: One task’s write held to the version its caller read.
IssueHolding: What one source holds for one issue a landing closed, and what moving it to done would write — the answer to TaskSource::issue_holdings.
IssueRef: One issue of one repository, as owner/name#N — exactly the spelling onevcs reports in a landing event’s closes.
ItemWrite: One create-or-update of a work item at a destination.
JournalEntry: One request a source sent while a journal was open.
Label: A tag a source attaches to work.
LabelFilter: Label membership, by name rather than by id.
LinkTypeConfig: One entry of a source’s link_types configuration, as written.
LinkTypes: A source’s link_types configuration: each link type a source mirrors natively, with the destination’s word for it.
MetadataKey: One caller-owned metadata key: <namespace>.<name>, at least two non-empty segments separated by dots, whose first segment is not MetadataKey::RESERVED_NAMESPACE.
MetadataMatch: One caller-defined metadata value a task must hold.
Metered: What one source’s requests have spent against one budget, split by where each figure came from.
Metering: Everything one source has sent to its backend since it was built, and what that spent against each budget the backend meters it by.
NativeId: A source’s own opaque identifier for one item.
NativeLink: One native relation to add or remove between two tasks of one source, mirroring a link.
NativeWord: A native relation word a source’s link_types was checked to mirror as: only LinkTypes::checked makes one, so no NativeLink carries a word its plugin refused.
NewComment: One comment to add to a task.
Page: One page of results, and where to pick up.
PageRequest: One step of a walk through a result set.
ParentWrite: One parent write: child’s parent set to parent, or removed for None.
Project: A grouping of tasks, shaped like a Task without a parent of its own.
ProjectQuery: A filter over a source’s projects.
ProjectVersionCoverage: Which parts of a project a source’s change token — its Project::version — vouches for.
Relations: What a source reads of one task’s relations.
Repository: A repository identified by its normalized origin, without a URL scheme or .git suffix.
SourceName: The name a configuration document gives one configured source.
Status: A source’s status, kept in both normalised and original form.
StatusContradiction: One item whose card contradicts its issue’s closure, and the option that brings it in line — one entry of TaskSource::status_contradictions.
StatusMapping: One source’s status_mapping: for each status category it mentions, the names it gives each item kind, or null.
StatusName: One status name a source’s backend holds: a board option, a workflow state, a project status.
StoredHeading: One heading of a record, as its backend stores it: its text, and the id the backend gave it.
Task: One unit of work as a source reports it.
TaskDetailRead: One task as TaskSource::get_task_details reads it: the task, and the first page of its comments when they were asked for.
TaskLink: One typed link, as one endpoint holds it under TaskLink::METADATA_KEY.
TaskQuery: A filter over a source’s tasks.
TaskRef: One task named by another task’s Task::delivers or Task::delivered_by.
TaskUpdate: A targeted update of one existing task. A member left None (or empty) leaves that field exactly as the source holds it.
TaskUpdateOutcome: What a source answers a TaskUpdate of a task it holds with.
TextQuery: A free-text search and the fields it searches.
VersionCoverage: Which parts of a task a source’s change token vouches for.
WaitCause: The word a plugin names one kind of wait by — see Clock::sleep_because.
WholeTask: One task as a write’s own response showed it whole: everything an entry of the cache holds, at the version that response determines.
WriteJournal: Every request a source sent between TaskSource::begin_journal and TaskSource::end_journal, in the order sent.

Enums§

AssetContentType: The content type an asset is stored and served as, decided by its name’s extension alone.
AuthorKind: Who wrote a comment, as the source that holds it can tell: a person, a bot — an integration, an app, an automation acting on its own — or neither, when the source cannot say. Decided by the plugin, through TaskSource::comment_author_kind.
BatchAnswer: What became of one item of a batched write.
Classification: Who may read an item: anybody, or only those who may read where it is kept.
ClosedAs: The two closures a card is brought in line with: the categories a closed issue’s reason can read as that name an option to move its card to.
Completion: What moving one issue’s item to done comes to at one source — the task it holds riding on every outcome that has one, so none can be told without its task, or with one, that has not.
ContradictedItem: The item a StatusContradiction is about, under the member naming its kind — task, as every contradiction was before a project could be one, or project.
Coverage: Whether a source’s change token vouches for one part of a task.
DependencyKind: What a DependencyEdge means.
DependencySupport: How far a source can walk its own dependency edges.
Direction: Which way a dependency query walks the graph.
EndpointRefusal: Why DependencyEndpoint::from_value refused what a caller asked to be written. Neither variant carries a value the caller gave, so a refusal can be printed anywhere.
ItemKind: The kind of work item named by a dependency endpoint.
LinkDirection: Which end of a directed link an item is.
Location: Where an entity is, in the one form a consumer can act on without knowing the backend.
MetadataRecord: Which kind of record a narrow metadata write names.
ParentAnswer: What became of one ParentWrite.
PartOutcome: What one request a write sent came to.
Priority: How much a task matters, in the one vocabulary every source is normalised into.
ProjectFilter: Which project a task must belong to.
RequestKind: What one request of a write was.
Shown: What one response showed of the task a write left behind.
SourceError: Why a source could not answer.
StatusCategory: The normalised status vocabulary shared across every source.
StatusNames: What one category of a status_mapping names: one name for every kind, or a name for each kind it maps.
Support: Whether a source applies one predicate itself.
TextFields: Which fields a TextQuery searches.
UnmappedStatus: Why a mapping gives no name for one category and one kind.
UpdatedField: One field of a task a TaskUpdate names, as the answer to it reports what was written.
Visibility: Who can read a destination, as its backend reports it on a live read.
WriteSupport: Whether a source can be written through at all.
WriteTarget: The item a write is about to reach, so a source can say who can read where it lands.

Constants§

ISSUE_REF_PATTERN: The pattern every IssueRef is spelled in: owner/name#N, the number at most nineteen digits — every such number fits the u64 it is read into.
LINKS_HEADING: The heading of the section the engine renders an item’s links under, last in its content.
SIMULATED_CLOCK_VARIABLE: The variable that puts a process of this build on a simulated clock.
SOURCE_NAME_PATTERN: The pattern every SourceName matches.

Traits§

BodyMarkup: Markup a destination’s bodies carry — an anchor a reader addresses a heading by, or a collapsible section in the destination’s own spelling — which the engine hands a source when it builds it.
Clock: A source of monotonic time and of waits measured against it.
SecretResolver: How a plugin reads the credential its configuration names.
SourcePlugin: The factory that turns one configuration block into a live TaskSource.
TaskSource: One configured source, as the engine drives it.
WriteGuard: Renews the engine’s hold on the creates a guarded call writes for, before each request.

Functions§

arrow: The arrow a ## Links line shows a direction with.
asset_references: The assets content references, each once, in the order it first references them.
asset_sha256: The lowercase hex SHA-256 of bytes: what Asset::sha256, AssetPayload::sha256 and AssetUpload::sha256 hold.
assetless: The refusal a source that keeps no assets answers an asset write with.
body_digest: sha256: and the lowercase hex SHA-256 of content: what a rendering’s body_digest records.
commentless: The refusal a source with no comments answers a comment call with.
decided_on: Decide one batched item against its hold and its guard on task, the source’s own read of it — the decision TaskSource::update_tasks’ default makes, for an override that read many items together: Some answer when nothing is to be written.
documentless: The refusal a source with no documents answers a document read with.
is_sha256: Whether digest is a SHA-256 as this contract spells one: 64 lowercase hex digits.
link_line: The ## Links line of link when nothing better is known of its other end: its type, its direction, and the other end’s qualified id.
read_content: content as a read answers it for an item whose metadata holds links: the ## Links section stripped, and None where nothing but the section was there. Content of an item holding no links is answered unchanged, so a section a person wrote is never touched.
relationless: The refusal a source holding no relations answers a relation read or write with.
relinked: content as a write of an item holding metadata stores it: with its ## Links section re-rendered from the links metadata holds, so a content write never drops what a person sees of them.
rewrite_asset_references: content with the target of each reference to an asset served names replaced by the URL it maps to, and every other byte as it was.
serve_asset_references: Point a record’s asset references at where a hosted source serves them, and record what it uploaded: the one way a plugin that declares assets native and serves them at a URL finishes the record it is about to write.
strip_links_section: content with the trailing ## Links section the engine rendered removed — exactly the content it was rendered onto, on a source that stores what it is sent.
system_clock: The real clock: tokio::time::sleep and a monotonic Instant.
unwritable: The refusal a source with no write side answers a write with.
unwritable_field: The refusal a source answers a narrow write of one field of a task with, when it cannot write that field on its own.
unwritable_metadata: The refusal a source answers a narrow metadata write with when it cannot make one on its own.
version_at: Whether found is the version version names, in source’s own order of its tokens.
with_links_section: content with bullets rendered as a ## Links section after it — content itself when there are none. strip_links_section gives back exactly content.

Type Aliases§

SharedBodyMarkup: A shared BodyMarkup, as a source holds the one it was handed.
SharedClock: One clock, shared by everything a process builds.