igni-service 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. igni_service/__init__.py +117 -0
  2. igni_service/agent_wire.py +172 -0
  3. igni_service/agents.py +228 -0
  4. igni_service/app.py +247 -0
  5. igni_service/assets.py +207 -0
  6. igni_service/bundle.py +888 -0
  7. igni_service/clock.py +23 -0
  8. igni_service/cors.py +180 -0
  9. igni_service/crypto.py +150 -0
  10. igni_service/directory.py +217 -0
  11. igni_service/errors.py +84 -0
  12. igni_service/events.py +143 -0
  13. igni_service/host.py +102 -0
  14. igni_service/jwks.py +99 -0
  15. igni_service/keystore.py +96 -0
  16. igni_service/logs.py +47 -0
  17. igni_service/notifications.py +200 -0
  18. igni_service/organisations.py +75 -0
  19. igni_service/py.typed +0 -0
  20. igni_service/registration.py +487 -0
  21. igni_service/revocations.py +345 -0
  22. igni_service/server.py +118 -0
  23. igni_service/service.py +441 -0
  24. igni_service/service_tokens.py +138 -0
  25. igni_service/settings.py +57 -0
  26. igni_service/signing.py +79 -0
  27. igni_service/sql_keystore.py +86 -0
  28. igni_service/sql_tables.py +46 -0
  29. igni_service/subjects.py +149 -0
  30. igni_service/tables.py +56 -0
  31. igni_service/testing.py +1253 -0
  32. igni_service/testing_items.py +237 -0
  33. igni_service/testing_vm_profiles.py +349 -0
  34. igni_service/token_endpoint.py +100 -0
  35. igni_service/tokens.py +314 -0
  36. igni_service/urls.py +83 -0
  37. igni_service/vm_profiles.py +251 -0
  38. igni_service/web.py +410 -0
  39. igni_service/web_sessions.py +203 -0
  40. igni_service-0.1.0.dist-info/METADATA +861 -0
  41. igni_service-0.1.0.dist-info/RECORD +45 -0
  42. igni_service-0.1.0.dist-info/WHEEL +4 -0
  43. igni_service-0.1.0.dist-info/entry_points.txt +2 -0
  44. igni_service-0.1.0.dist-info/licenses/LICENSE +202 -0
  45. igni_service-0.1.0.dist-info/licenses/NOTICE +5 -0
@@ -0,0 +1,117 @@
1
+ """igni-service: what a service needs to be part of an igni deployment.
2
+
3
+ igni = IgniService.from_settings(IgniSettings())
4
+ app = FastAPI(lifespan=igni.lifespan)
5
+ igni.install(app)
6
+
7
+ See the package README for the whole surface.
8
+ """
9
+
10
+ from igni_service.agent_wire import ItemStatus
11
+ from igni_service.agents import Agent, Attachment, Chat
12
+ from igni_service.app import IgniApp
13
+ from igni_service.cors import BearerCors
14
+ from igni_service.directory import Directory, Member, Organisation
15
+ from igni_service.errors import (
16
+ BundleError,
17
+ ConfigurationError,
18
+ EventRefused,
19
+ IgniError,
20
+ IgniUnavailable,
21
+ KeyStoreError,
22
+ NotificationRefused,
23
+ ServiceNotApproved,
24
+ ServiceRevoked,
25
+ VmProfileRefused,
26
+ )
27
+ from igni_service.events import EventAccepted, Producer
28
+ from igni_service.host import Host
29
+ from igni_service.keystore import KeyCipher, KeyStore, MemoryKeyStore, StoredKey
30
+ from igni_service.notifications import Delivered, Notification, Target
31
+ from igni_service.service import IgniService
32
+ from igni_service.settings import IgniSettings
33
+ from igni_service.sql_keystore import SqlKeyStore
34
+ from igni_service.subjects import ExportSection, Subject
35
+ from igni_service.tables import IgniTables
36
+ from igni_service.tokens import (
37
+ PEOPLE_ONLY,
38
+ App,
39
+ Caller,
40
+ CallerKind,
41
+ IgniCall,
42
+ Person,
43
+ Space,
44
+ TokenRefused,
45
+ )
46
+ from igni_service.vm_profiles import (
47
+ AppVmProfile,
48
+ EffectiveVmProfile,
49
+ ServiceVmProfile,
50
+ VmPackages,
51
+ VmProfileRequest,
52
+ VmProfileRequestRecord,
53
+ )
54
+ from igni_service.web import WebSignIn
55
+ from igni_service.web_sessions import (
56
+ MemoryWebSessionStore,
57
+ SqlWebSessionStore,
58
+ WebSession,
59
+ WebSessionStore,
60
+ )
61
+
62
+ __all__ = [
63
+ "AppVmProfile",
64
+ "EffectiveVmProfile",
65
+ "IgniApp",
66
+ "ServiceVmProfile",
67
+ "VmPackages",
68
+ "VmProfileRefused",
69
+ "VmProfileRequest",
70
+ "VmProfileRequestRecord",
71
+ "BearerCors",
72
+ "BundleError",
73
+ "ConfigurationError",
74
+ "Delivered",
75
+ "Agent",
76
+ "Attachment",
77
+ "Chat",
78
+ "EventAccepted",
79
+ "EventRefused",
80
+ "ItemStatus",
81
+ "Directory",
82
+ "ExportSection",
83
+ "Host",
84
+ "IgniCall",
85
+ "IgniError",
86
+ "IgniService",
87
+ "IgniSettings",
88
+ "IgniTables",
89
+ "IgniUnavailable",
90
+ "KeyCipher",
91
+ "KeyStore",
92
+ "KeyStoreError",
93
+ "Member",
94
+ "MemoryKeyStore",
95
+ "MemoryWebSessionStore",
96
+ "Notification",
97
+ "NotificationRefused",
98
+ "ServiceNotApproved",
99
+ "ServiceRevoked",
100
+ "Organisation",
101
+ "PEOPLE_ONLY",
102
+ "Producer",
103
+ "App",
104
+ "Caller",
105
+ "CallerKind",
106
+ "Person",
107
+ "Space",
108
+ "SqlKeyStore",
109
+ "SqlWebSessionStore",
110
+ "StoredKey",
111
+ "Subject",
112
+ "Target",
113
+ "TokenRefused",
114
+ "WebSession",
115
+ "WebSessionStore",
116
+ "WebSignIn",
117
+ ]
@@ -0,0 +1,172 @@
1
+ """The wire behind `Agent`: uploads, items and statuses at igni server (service-identity §15)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import mimetypes
6
+ from datetime import datetime
7
+ from pathlib import Path
8
+ from typing import Any, Literal
9
+
10
+ from pydantic import BaseModel, ConfigDict, Field, ValidationError
11
+
12
+ from igni_service.errors import EventRefused, IgniUnavailable
13
+ from igni_service.events import (
14
+ MAX_KEY,
15
+ EventAccepted,
16
+ EventSender,
17
+ Producer,
18
+ ServiceEventRequest,
19
+ )
20
+ from igni_service.service_tokens import ServiceTokens
21
+ from igni_service.urls import IgniPaths
22
+
23
+ #: igni's limits, mirrored so a mistake is caught where it is made.
24
+ MAX_TEXT = 65536
25
+ MAX_THREAD = 200
26
+ MAX_ATTACHMENTS = 10
27
+ MAX_TITLE = 200
28
+ #: What a person may attach in igni's composer.
29
+ MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024
30
+
31
+ ItemKind = Literal["event", "message", "chat", "action"]
32
+ ItemState = Literal["pending", "delivered", "not_handled", "expired", "dropped", "failed"]
33
+
34
+
35
+ class Attachment(BaseModel):
36
+ """A file to send with an item: any type igni's composer takes, at most 5 MiB."""
37
+
38
+ model_config = ConfigDict(frozen=True)
39
+
40
+ filename: str = Field(min_length=1, max_length=200)
41
+ content_type: str = "application/octet-stream"
42
+ data: bytes = Field(min_length=1, max_length=MAX_ATTACHMENT_BYTES)
43
+
44
+ @classmethod
45
+ def from_bytes(cls, filename: str, data: bytes, content_type: str | None = None) -> Attachment:
46
+ guessed = content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
47
+ return cls(filename=filename, content_type=guessed, data=data)
48
+
49
+ @classmethod
50
+ def from_path(cls, path: str | Path, content_type: str | None = None) -> Attachment:
51
+ source = Path(path)
52
+ return cls.from_bytes(source.name, source.read_bytes(), content_type)
53
+
54
+
55
+ class AttachmentStored(BaseModel):
56
+ """igni kept the file; an item names it by `attachment_id`."""
57
+
58
+ attachment_id: str
59
+ filename: str
60
+ content_type: str
61
+ size: int
62
+ sha256: str
63
+ expires_at: datetime
64
+
65
+
66
+ class ChatAction(BaseModel):
67
+ """What an `action` item does to its thread's chat."""
68
+
69
+ model_config = ConfigDict(frozen=True, extra="forbid")
70
+
71
+ op: Literal["show", "rename", "cancel"]
72
+ view: dict[str, Any] | None = None
73
+ title: str | None = Field(default=None, min_length=1, max_length=MAX_TITLE)
74
+
75
+
76
+ class ServiceItemRequest(BaseModel):
77
+ """`POST /v1/service-items`, as it goes on the wire."""
78
+
79
+ model_config = ConfigDict(frozen=True, extra="forbid")
80
+
81
+ producer: Producer
82
+ kind: ItemKind
83
+ thread: str | None = Field(default=None, min_length=1, max_length=MAX_THREAD)
84
+ text: str | None = Field(default=None, min_length=1, max_length=MAX_TEXT)
85
+ title: str | None = Field(default=None, min_length=1, max_length=MAX_TITLE)
86
+ start_run: bool = True
87
+ action: ChatAction | None = None
88
+ attachments: list[str] = Field(default_factory=list, max_length=MAX_ATTACHMENTS)
89
+ event_key: str | None = Field(default=None, min_length=1, max_length=MAX_KEY)
90
+ expires_at: datetime | None = None
91
+
92
+
93
+ class ItemStatus(BaseModel):
94
+ """What became of an item: `GET /v1/service-events/{event_id}`."""
95
+
96
+ model_config = ConfigDict(extra="ignore")
97
+
98
+ event_id: str
99
+ producer: Producer
100
+ kind: ItemKind = "event"
101
+ type: str
102
+ thread: str | None = None
103
+ event_key: str | None = None
104
+ state: ItemState
105
+ dropped_reason: str | None = None
106
+ failed_reason: str | None = None
107
+ #: An event no handler took: why.
108
+ not_handled_reason: str | None = None
109
+ created_at: datetime
110
+ expires_at: datetime | None = None
111
+ delivered_at: datetime | None = None
112
+ updated_at: datetime
113
+
114
+
115
+ class AgentWire:
116
+ """The calls behind an `Agent`: uploads, items, statuses. One per service."""
117
+
118
+ def __init__(self, tokens: ServiceTokens, sender: EventSender) -> None:
119
+ self._tokens = tokens
120
+ self._sender = sender
121
+
122
+ async def upload(self, org_id: str, attachment: Attachment) -> AttachmentStored:
123
+ response = await self._tokens.request(
124
+ "POST",
125
+ IgniPaths.SERVICE_ATTACHMENTS,
126
+ org_id=org_id,
127
+ params={"filename": attachment.filename},
128
+ content=attachment.data,
129
+ headers={"Content-Type": attachment.content_type},
130
+ )
131
+ if response.status_code in (200, 201):
132
+ try:
133
+ return AttachmentStored.model_validate(response.json())
134
+ except (ValidationError, ValueError) as exc:
135
+ raise IgniUnavailable("igni answered the upload with something else") from exc
136
+ if response.status_code != 429 and 400 <= response.status_code < 500:
137
+ raise EventRefused(response.status_code, response.text)
138
+ raise IgniUnavailable(f"igni answered the upload {response.status_code}")
139
+
140
+ async def uploaded(self, org_id: str, attachments: list[Attachment]) -> list[str]:
141
+ return [(await self.upload(org_id, a)).attachment_id for a in attachments]
142
+
143
+ async def item(self, org_id: str, item: ServiceItemRequest) -> EventAccepted:
144
+ return await self._sender.post(org_id, IgniPaths.SERVICE_ITEMS, item, what=item.kind)
145
+
146
+ async def event(self, org_id: str, event: ServiceEventRequest) -> EventAccepted:
147
+ return await self._sender.send(org_id, event)
148
+
149
+ async def status(self, org_id: str, event_id: str) -> ItemStatus:
150
+ response = await self._tokens.request(
151
+ "GET", IgniPaths.service_event(event_id), org_id=org_id
152
+ )
153
+ if response.status_code == 200:
154
+ try:
155
+ return ItemStatus.model_validate(response.json())
156
+ except (ValidationError, ValueError) as exc:
157
+ raise IgniUnavailable("igni answered the status with something else") from exc
158
+ if 400 <= response.status_code < 500:
159
+ raise EventRefused(response.status_code, response.text)
160
+ raise IgniUnavailable(f"igni answered the status {response.status_code}")
161
+
162
+
163
+ __all__ = [
164
+ "AgentWire",
165
+ "Attachment",
166
+ "AttachmentStored",
167
+ "ChatAction",
168
+ "ItemKind",
169
+ "ItemState",
170
+ "ItemStatus",
171
+ "ServiceItemRequest",
172
+ ]
igni_service/agents.py ADDED
@@ -0,0 +1,228 @@
1
+ """A producer's agent, as a service reaches it: messages, files, chats (service-identity §15).
2
+
3
+ agent = igni.host(org_id).agent(Producer.person("u-marieke"))
4
+ await agent.send_message(
5
+ "Claim CL-20431 arrived; assess the damage.",
6
+ attachments=[Attachment.from_path("damage.jpg"), Attachment.from_bytes("form.pdf", pdf)],
7
+ thread="claim:CL-20431",
8
+ )
9
+ chat = await agent.new_chat("Claim CL-20431", thread="claim:CL-20431")
10
+ await chat.show({"root": "r", "elements": {...}}) # shown, never sent to the model
11
+ status = await agent.status(accepted.event_id) # pending, delivered, expired, failed
12
+
13
+ Everything goes through igni server, which stores it until the
14
+ producer's igni — on their desktop, or in their Fleet VM, woken for it —
15
+ takes it, at least once, for at most 14 days. A **thread** is this
16
+ service's own key for a conversation: the first item of a thread opens a
17
+ chat for it in the producer's igni, and every later one goes there.
18
+ Without one an item goes to this extension's own chat. Nothing a service
19
+ sends lands in the chat a person has open, and nothing answers an
20
+ approval: that decision stays a person's.
21
+
22
+ What a service may send beyond a plain event is what its extension
23
+ declares in `permissions.service` — `messages`, `attachments`, `chats` —
24
+ and igni refuses the rest with `EventRefused` (403).
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import uuid
30
+ from datetime import datetime
31
+ from typing import Any
32
+
33
+ from igni_service.agent_wire import (
34
+ AgentWire,
35
+ Attachment,
36
+ ChatAction,
37
+ ItemKind,
38
+ ItemStatus,
39
+ ServiceItemRequest,
40
+ )
41
+ from igni_service.events import EventAccepted, Producer, ServiceEventRequest
42
+
43
+
44
+ class Agent:
45
+ """One producer's agent — a person's or an app's — in one organisation."""
46
+
47
+ def __init__(self, org_id: str, producer: Producer, wire: AgentWire) -> None:
48
+ self._org_id = org_id
49
+ self._producer = producer
50
+ self._wire = wire
51
+
52
+ @property
53
+ def producer(self) -> Producer:
54
+ return self._producer
55
+
56
+ async def send_message(
57
+ self,
58
+ text: str,
59
+ *,
60
+ attachments: list[Attachment] | None = None,
61
+ thread: str | None = None,
62
+ title: str | None = None,
63
+ start_run: bool = True,
64
+ event_key: str | None = None,
65
+ expires_at: datetime | None = None,
66
+ ) -> EventAccepted:
67
+ """Post `text` as this extension's message: it starts a run, or waits for the run going.
68
+
69
+ `start_run=False` waits for the chat's next run instead. `title`
70
+ names the chat if this message opens its thread's. Needs
71
+ `service.messages` (and `service.attachments`, `service.chats`
72
+ for files and a thread).
73
+ """
74
+ return await self.send_item(
75
+ "message",
76
+ text=text,
77
+ attachments=attachments,
78
+ thread=thread,
79
+ title=title,
80
+ start_run=start_run,
81
+ event_key=event_key,
82
+ expires_at=expires_at,
83
+ )
84
+
85
+ async def send_event(
86
+ self,
87
+ type: str,
88
+ payload: dict[str, object] | None = None,
89
+ *,
90
+ event_key: str | None = None,
91
+ expires_at: datetime | None = None,
92
+ ) -> EventAccepted:
93
+ """Hand this extension an event. igni posts nothing for it: the extension's handler acts.
94
+
95
+ One no handler took reads `not_handled` (`status`). Needs no grant.
96
+ """
97
+ event = ServiceEventRequest(
98
+ producer=self._producer,
99
+ type=type,
100
+ payload=payload or {},
101
+ event_key=event_key,
102
+ expires_at=expires_at,
103
+ )
104
+ return await self._wire.event(self._org_id, event)
105
+
106
+ async def new_chat(
107
+ self,
108
+ title: str,
109
+ *,
110
+ thread: str | None = None,
111
+ text: str | None = None,
112
+ attachments: list[Attachment] | None = None,
113
+ event_key: str | None = None,
114
+ expires_at: datetime | None = None,
115
+ ) -> Chat:
116
+ """Open a chat titled `title` — for `thread`, or a thread of its own — optionally with a first message."""
117
+ chat = self.chat(thread or f"chat:{uuid.uuid4()}")
118
+ await self.send_item(
119
+ "chat",
120
+ text=text,
121
+ attachments=attachments,
122
+ thread=chat.thread,
123
+ title=title,
124
+ event_key=event_key,
125
+ expires_at=expires_at,
126
+ )
127
+ return chat
128
+
129
+ def chat(self, thread: str) -> Chat:
130
+ """The chat of `thread`: opened by its first item, whichever that is."""
131
+ return Chat(self, thread)
132
+
133
+ async def status(self, event_id: str) -> ItemStatus:
134
+ """`pending`, `delivered`, `expired`, `dropped` or `failed`, with the reason."""
135
+ return await self._wire.status(self._org_id, event_id)
136
+
137
+ async def send_item(
138
+ self,
139
+ kind: ItemKind,
140
+ *,
141
+ text: str | None = None,
142
+ attachments: list[Attachment] | None = None,
143
+ thread: str | None = None,
144
+ title: str | None = None,
145
+ start_run: bool = True,
146
+ action: ChatAction | None = None,
147
+ event_key: str | None = None,
148
+ expires_at: datetime | None = None,
149
+ ) -> EventAccepted:
150
+ """Any item: the methods above and `Chat`'s are this, spelled for one kind."""
151
+ item = ServiceItemRequest(
152
+ producer=self._producer,
153
+ kind=kind,
154
+ thread=thread,
155
+ text=text,
156
+ title=title,
157
+ start_run=start_run,
158
+ action=action,
159
+ attachments=[],
160
+ event_key=event_key,
161
+ expires_at=expires_at,
162
+ )
163
+ ids = await self._wire.uploaded(self._org_id, list(attachments or []))
164
+ return await self._wire.item(self._org_id, item.model_copy(update={"attachments": ids}))
165
+
166
+
167
+ class Chat:
168
+ """The chat of one thread in one producer's igni."""
169
+
170
+ def __init__(self, agent: Agent, thread: str) -> None:
171
+ self._agent = agent
172
+ self.thread = thread
173
+
174
+ async def send_message(
175
+ self,
176
+ text: str,
177
+ *,
178
+ attachments: list[Attachment] | None = None,
179
+ event_key: str | None = None,
180
+ expires_at: datetime | None = None,
181
+ ) -> EventAccepted:
182
+ """Post it: a run starts, or it waits for the run going."""
183
+ return await self._agent.send_message(
184
+ text,
185
+ attachments=attachments,
186
+ thread=self.thread,
187
+ event_key=event_key,
188
+ expires_at=expires_at,
189
+ )
190
+
191
+ async def queue(
192
+ self,
193
+ text: str,
194
+ *,
195
+ attachments: list[Attachment] | None = None,
196
+ event_key: str | None = None,
197
+ expires_at: datetime | None = None,
198
+ ) -> EventAccepted:
199
+ """For the chat's next run; starts nothing."""
200
+ return await self._agent.send_message(
201
+ text,
202
+ attachments=attachments,
203
+ thread=self.thread,
204
+ start_run=False,
205
+ event_key=event_key,
206
+ expires_at=expires_at,
207
+ )
208
+
209
+ async def show(
210
+ self, view: dict[str, Any], *, title: str | None = None, event_key: str | None = None
211
+ ) -> EventAccepted:
212
+ """A json-render view in the chat — `{root, elements}` — shown, never sent to the model."""
213
+ return await self._act(ChatAction(op="show", view=view, title=title), event_key)
214
+
215
+ async def rename(self, title: str, *, event_key: str | None = None) -> EventAccepted:
216
+ return await self._act(ChatAction(op="rename", title=title), event_key)
217
+
218
+ async def cancel(self, *, event_key: str | None = None) -> EventAccepted:
219
+ """Stop the chat's working run. A run waiting on a person's approval is left alone."""
220
+ return await self._act(ChatAction(op="cancel"), event_key)
221
+
222
+ async def _act(self, action: ChatAction, event_key: str | None) -> EventAccepted:
223
+ return await self._agent.send_item(
224
+ "action", thread=self.thread, action=action, event_key=event_key
225
+ )
226
+
227
+
228
+ __all__ = ["Agent", "Attachment", "Chat"]