mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-11 16:19:10 +02:00
c2dafc1c88Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>
133 lines
4.2 KiB
Text
133 lines
4.2 KiB
Text
---
|
|
title: keys
|
|
sidebarTitle: keys
|
|
---
|
|
|
|
# `fastmcp.server.tasks.keys`
|
|
|
|
|
|
Docket and Redis key encoding for background tasks.
|
|
|
|
The compound Docket task key embeds the auth boundary so that the parser can
|
|
reject cross-scope access without consulting Redis. Authenticated and
|
|
anonymous tasks live in disjoint keyspaces:
|
|
|
|
auth:{enc_scope}:{client_task_id}:{task_type}:{enc_identifier}
|
|
anon:{client_task_id}:{task_type}:{enc_identifier}
|
|
|
|
The same `auth/anon` partition is used for the per-task Redis prefix
|
|
(``fastmcp:task:auth:{enc_scope}`` vs ``fastmcp:task:anon``) — see
|
|
``task_redis_prefix``.
|
|
|
|
``task_scope`` is the raw scope identifier (typically derived from
|
|
``client_id`` or ``client_id|sub``); encoding happens once, at the boundary,
|
|
in this module.
|
|
|
|
|
|
## Functions
|
|
|
|
### `build_task_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
build_task_key(task_scope: str | None, client_task_id: str, task_type: str, component_identifier: str) -> str
|
|
```
|
|
|
|
|
|
Build Docket task key with embedded metadata.
|
|
|
|
When ``task_scope`` is ``None`` the task is anonymous and lives in the
|
|
``anon`` keyspace. Otherwise it lives under ``auth:{enc_scope}``.
|
|
|
|
**Args:**
|
|
- `task_scope`: Raw authorization scope, or ``None`` for anonymous tasks
|
|
- `client_task_id`: Client-provided task ID
|
|
- `task_type`: Type of task ("tool", "prompt", "resource")
|
|
- `component_identifier`: Tool name, prompt name, or resource URI
|
|
|
|
**Returns:**
|
|
- Encoded task key for Docket
|
|
|
|
**Examples:**
|
|
|
|
>>> build_task_key("client-a", "task456", "tool", "my_tool")
|
|
'auth:client-a:task456:tool:my_tool'
|
|
>>> build_task_key(None, "task456", "tool", "my_tool")
|
|
'anon:task456:tool:my_tool'
|
|
>>> build_task_key("client-a", "task456", "resource", "file://data.txt")
|
|
'auth:client-a:task456:resource:file%3A%2F%2Fdata.txt'
|
|
|
|
|
|
### `parse_task_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
parse_task_key(task_key: str) -> TaskKeyParts
|
|
```
|
|
|
|
|
|
Parse Docket task key to extract metadata.
|
|
|
|
**Args:**
|
|
- `task_key`: Encoded task key from Docket
|
|
|
|
**Returns:**
|
|
- Dict with keys: ``task_scope`` (``str | None``), ``client_task_id``,
|
|
- ``task_type``, ``component_identifier``.
|
|
|
|
**Raises:**
|
|
- `ValueError`: If the key has an unrecognized tag or wrong segment count.
|
|
|
|
**Examples:**
|
|
|
|
>>> parse_task_key("auth:client-a:task456:tool:my_tool")
|
|
`{'task_scope': 'client-a', 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
|
|
>>> parse_task_key("anon:task456:tool:my_tool")
|
|
`{'task_scope': None, 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
|
|
|
|
|
|
### `get_client_task_id_from_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
get_client_task_id_from_key(task_key: str) -> str
|
|
```
|
|
|
|
|
|
Extract just the client task ID from a task key.
|
|
|
|
**Args:**
|
|
- `task_key`: Full encoded task key
|
|
|
|
**Returns:**
|
|
- Client-provided task ID
|
|
|
|
**Examples:**
|
|
|
|
>>> get_client_task_id_from_key("auth:client-a:task456:tool:my_tool")
|
|
'task456'
|
|
>>> get_client_task_id_from_key("anon:task456:tool:my_tool")
|
|
'task456'
|
|
|
|
|
|
### `task_redis_prefix` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
task_redis_prefix(task_scope: str | None) -> str
|
|
```
|
|
|
|
|
|
Return the Redis key prefix that owns a given scope.
|
|
|
|
Authenticated tasks live under ``fastmcp:task:auth:{enc_scope}``;
|
|
anonymous tasks live under ``fastmcp:task:anon``. Callers append
|
|
``f":{task_id}:..."`` to compose the final key.
|
|
|
|
|
|
## Classes
|
|
|
|
### `TaskKeyParts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
|
|
Decoded segments of a Docket task key.
|
|
|
|
``task_scope`` is ``None`` for anonymous tasks, the raw scope string
|
|
otherwise.
|
|
|