passageway-connector-confluence 0.3.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.
@@ -0,0 +1,3 @@
1
+ from passageway_connector_confluence.connector import main
2
+
3
+ main()
@@ -0,0 +1,307 @@
1
+ """passageway connector for Confluence Data Center: the current pages of chosen spaces, read through the REST API with GET only.
2
+
3
+ Written from the public REST documentation. Settings come from the environment and are documented in README.md.
4
+ """
5
+
6
+ import hashlib
7
+ import re
8
+ import sys
9
+ import time
10
+ from collections.abc import Iterator, Mapping
11
+ from dataclasses import dataclass
12
+ from datetime import UTC, datetime, timedelta
13
+ from urllib.parse import urlparse
14
+
15
+ from passageway_sdk import Connector, SettingsError, SourceError
16
+ from passageway_sdk.web import HttpError, Reply, Retry, Web
17
+ from passageway_sdk.settings import names
18
+
19
+ from passageway_connector_confluence.html import html_to_sections
20
+
21
+ PAGE = 100 # results per request (the API's usual maximum)
22
+ RETRY_BUDGET = 900 # seconds of waiting per request before giving up: a throttled Data Center takes minutes
23
+ MAX_BACKOFF = 60 # the longest wait the connector picks itself
24
+ MAX_RETRY_AFTER = 300 # the longest wait a Retry-After may ask for
25
+ SAY_WAITS_FROM = 10 # seconds: a wait this long is said in the log, shorter ones stay quiet
26
+ RETRY_STATUS = (429, 500, 502, 503, 504)
27
+ FETCH_EXPAND = "body.storage,version,space,ancestors,metadata.labels"
28
+ @dataclass(frozen=True)
29
+ class Settings:
30
+ url: str
31
+ spaces: tuple[str, ...]
32
+ token: str
33
+ include: frozenset[str]
34
+ exclude: frozenset[str]
35
+ max_pages: int
36
+ timeout: float
37
+ pause: float
38
+ verify: bool
39
+
40
+
41
+ def parse_settings(env: Mapping[str, str]) -> Settings:
42
+ url = env.get("URL", "").strip().rstrip("/")
43
+ parsed = urlparse(url)
44
+ if not url or parsed.scheme not in ("http", "https") or not parsed.hostname:
45
+ raise SettingsError(f"URL must be the Confluence site's http(s) address, got {url!r}")
46
+ spaces = names(env, "SPACES")
47
+ if not spaces or not all(re.fullmatch(r"[A-Za-z0-9_~.-]+", s) for s in spaces):
48
+ raise SettingsError("SPACES must list the space keys to index, separated by |, e.g. OPS|HR")
49
+ token = env.get("TOKEN", "").strip()
50
+ if not token:
51
+ raise SettingsError("TOKEN is required: a personal access token from your Confluence profile, as a secret reference")
52
+ raw = env.get("MAX_PAGES", "").strip()
53
+ if raw and (not raw.isdecimal() or int(raw) < 1):
54
+ raise SettingsError(f"MAX_PAGES must be a whole number from 1, got {raw!r}")
55
+ try:
56
+ timeout = float(env.get("TIMEOUT", "").strip() or 30)
57
+ pause = float(env.get("PAUSE_SECONDS", "").strip() or 0)
58
+ except ValueError:
59
+ raise SettingsError("TIMEOUT and PAUSE_SECONDS must be numbers of seconds") from None
60
+ if timeout <= 0 or pause < 0:
61
+ raise SettingsError("TIMEOUT must be greater than 0 and PAUSE_SECONDS not negative")
62
+ verify = env.get("VERIFY_TLS", "").strip().lower() or "true"
63
+ if verify not in ("true", "false"):
64
+ raise SettingsError("VERIFY_TLS must be true or false")
65
+ return Settings(url, spaces, token, frozenset(names(env, "INCLUDE_LABELS")), frozenset(names(env, "EXCLUDE_LABELS")),
66
+ int(raw) if raw else 5000, timeout, pause, verify == "true")
67
+
68
+
69
+ class ApiError(SourceError):
70
+ def __init__(self, status: int, message: str):
71
+ super().__init__(message)
72
+ self.status = status
73
+
74
+
75
+ class Api:
76
+ """Read-only: only GET requests, by construction."""
77
+
78
+ def __init__(self, s: Settings, sleep=time.sleep):
79
+ self.s = s
80
+ retry = Retry(statuses=RETRY_STATUS, network=True, budget=RETRY_BUDGET, max_backoff=MAX_BACKOFF, max_after=MAX_RETRY_AFTER,
81
+ say_from=SAY_WAITS_FROM)
82
+ # on stderr, which the core logs as it comes: a waiting sync does not look hung
83
+ say = lambda message: print(f"confluence connector: {message}", file=sys.stderr, flush=True) # noqa: E731
84
+ self._web = Web(base_url=s.url, headers={"Authorization": f"Bearer {s.token}"}, timeout=s.timeout, verify=s.verify,
85
+ follow_redirects=False, pause=s.pause, max_bytes=256_000_000, retry=retry, log=say, sleep=sleep)
86
+
87
+ def get(self, path: str, **params) -> dict:
88
+ try:
89
+ reply = self._web.get(path, params=params)
90
+ except HttpError as e:
91
+ if e.attempts > 1: # the retry policy gave up, and its message says how long it waited
92
+ raise
93
+ reply = Reply(e.status, "", "") # a 5xx that is not worth retrying
94
+ if reply.status == 401:
95
+ raise ApiError(401, "Confluence answered HTTP 401: check TOKEN (a personal access token) and its permissions")
96
+ if 300 <= reply.status < 400:
97
+ raise ApiError(reply.status, f"Confluence answered GET {path} with a redirect to "
98
+ f"{reply.headers.get('location', '?')}: check URL (and whether a login page is in the way)")
99
+ if reply.status >= 400:
100
+ raise ApiError(reply.status, f"Confluence answered HTTP {reply.status} to GET {path}")
101
+ data = reply.json()
102
+ if not isinstance(data, dict):
103
+ raise SourceError(f"Confluence did not answer GET {path} with a JSON object")
104
+ return data
105
+
106
+ def paged(self, path: str, **params) -> Iterator[dict]:
107
+ start, seen = 0, set()
108
+ while True:
109
+ data = self.get(path, limit=str(PAGE), start=str(start), **params)
110
+ results = data.get("results")
111
+ if not isinstance(results, list):
112
+ raise SourceError(f"Confluence answered GET {path} without a results list")
113
+ fresh = [r for r in results if str(r.get("id")) not in seen]
114
+ seen.update(str(r.get("id")) for r in results)
115
+ yield from fresh
116
+ # the server caps `limit` as it likes: follow `next`; a server that ignores `start` repeats itself: stop then
117
+ if not fresh or not data.get("_links", {}).get("next"):
118
+ return
119
+ start += len(results)
120
+
121
+
122
+ def _iso(when: str) -> str:
123
+ try:
124
+ return datetime.fromisoformat(when.replace("Z", "+00:00")).astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
125
+ except ValueError:
126
+ return when
127
+
128
+
129
+ _ENTITIES = re.compile(r"&([A-Za-z][A-Za-z0-9]*);")
130
+ _KEEP_ENTITIES = {"amp", "lt", "gt", "quot", "apos"}
131
+
132
+
133
+ def _entities(storage: str) -> str:
134
+ """Named HTML entities as characters, so that the XML parser accepts them; the five XML ones stay."""
135
+ from html.entities import html5
136
+
137
+ def one(m):
138
+ name = m.group(1)
139
+ return m.group(0) if name in _KEEP_ENTITIES else html5.get(name + ";", m.group(0))
140
+ return _ENTITIES.sub(one, storage)
141
+
142
+
143
+ def _macro_param(node, name: str) -> str:
144
+ for child in node:
145
+ if child.tag == "{ac}parameter" and child.get("{ac}name") == name:
146
+ return "".join(child.itertext()).strip()
147
+ return ""
148
+
149
+
150
+ def _walk(node, out: list[str]) -> None:
151
+ """Serialise a storage-format element as plain HTML: ac:/ri: elements become their readable part."""
152
+ from xml.sax.saxutils import escape, quoteattr
153
+
154
+ tag = node.tag
155
+ if tag == "{ac}structured-macro":
156
+ name = node.get("{ac}name", "")
157
+ if name in ("code", "noformat"):
158
+ body = next((c for c in node if c.tag == "{ac}plain-text-body"), None)
159
+ out.append("<pre>" + escape("".join(body.itertext()) if body is not None else "") + "</pre>")
160
+ elif name == "status":
161
+ out.append(escape(_macro_param(node, "title")))
162
+ else: # a box, an expand, a section, a column, an excerpt: what it holds; a toc, a jira macro: nothing
163
+ for child in node:
164
+ if child.tag == "{ac}rich-text-body":
165
+ for grandchild in child:
166
+ _walk(grandchild, out)
167
+ out.append(escape(child.tail or ""))
168
+ out.append(escape(node.tail or ""))
169
+ return
170
+ if tag == "{ac}link":
171
+ body = next((c for c in node if c.tag in ("{ac}link-body", "{ac}plain-text-link-body")), None)
172
+ if body is not None:
173
+ out.append(escape("".join(body.itertext())))
174
+ else:
175
+ page = next((c for c in node if c.tag == "{ri}page"), None)
176
+ out.append(escape(page.get("{ri}content-title", "")) if page is not None else "")
177
+ out.append(escape(node.tail or ""))
178
+ return
179
+ if tag == "{ac}task-list":
180
+ items = ["".join(b.itertext()) for task in node if task.tag == "{ac}task"
181
+ for b in task if b.tag == "{ac}task-body"]
182
+ out.append("<ul>" + "".join(f"<li>{escape(i)}</li>" for i in items) + "</ul>" + escape(node.tail or ""))
183
+ return
184
+ if tag in ("{ac}placeholder", "{ac}image", "{ac}emoticon", "{ac}parameter", "{ac}task-id", "{ac}task-status") \
185
+ or (isinstance(tag, str) and tag.startswith("{ri}")):
186
+ out.append(escape(node.tail or ""))
187
+ return
188
+ if isinstance(tag, str) and tag.startswith("{ac}"): # layouts, inline-comment markers, rich-text bodies: transparent
189
+ out.append(escape(node.text or ""))
190
+ for child in node:
191
+ _walk(child, out)
192
+ out.append(escape(node.tail or ""))
193
+ return
194
+ if not isinstance(tag, str): # a comment
195
+ out.append(escape(node.tail or ""))
196
+ return
197
+ attrs = "".join(f" {k}={quoteattr(v)}" for k, v in node.attrib.items() if not k.startswith("{"))
198
+ out.append(f"<{tag}{attrs}>{escape(node.text or '')}")
199
+ for child in node:
200
+ _walk(child, out)
201
+ out.append(f"</{tag}>{escape(node.tail or '')}")
202
+
203
+
204
+ def storage_to_html(storage: str) -> str:
205
+ """Confluence's storage format as plain HTML: code macros become <pre>, boxes and expands keep what they hold, task
206
+ lists become lists, links keep their text or the linked page's title; images, emoticons, placeholders, a table of
207
+ contents, Jira and other macros without a body disappear. Storage that is not well-formed XML is read as HTML with
208
+ the ac:/ri: markup stripped."""
209
+ import xml.etree.ElementTree as ET
210
+
211
+ wrapped = f'<root xmlns:ac="ac" xmlns:ri="ri">{_entities(storage)}</root>'
212
+ try:
213
+ root = ET.fromstring(wrapped)
214
+ except ET.ParseError:
215
+ return re.sub(r"</?(?:ac|ri):[^>]*>", "", storage)
216
+ out: list[str] = [root.text or ""]
217
+ for child in root:
218
+ _walk(child, out)
219
+ return "".join(out)
220
+
221
+
222
+ class Confluence(Connector):
223
+ name = "confluence connector"
224
+ expected_errors = (ValueError, KeyError, TypeError)
225
+
226
+ def __init__(self, env: Mapping[str, str], *, sleep=time.sleep):
227
+ self.s = parse_settings(env)
228
+ self.api = Api(self.s, sleep)
229
+ if not self.s.verify:
230
+ self.warn("VERIFY_TLS is false: the server's certificate is not checked")
231
+
232
+ def _wanted(self, labels: set[str]) -> bool:
233
+ if self.s.include and not labels & self.s.include:
234
+ return False
235
+ return not (labels & self.s.exclude)
236
+
237
+ @staticmethod
238
+ def _labels(page: dict) -> set[str]:
239
+ return {lb.get("name", "") for lb in page.get("metadata", {}).get("labels", {}).get("results", []) if lb.get("name")}
240
+
241
+ def _version(self, page: dict) -> str:
242
+ labels = hashlib.sha256(",".join(sorted(self._labels(page))).encode()).hexdigest()[:8]
243
+ return f"{page['version']['number']}:{labels}"
244
+
245
+ def _listing(self, pages: Iterator[dict]) -> dict[str, dict]:
246
+ found: dict[str, dict] = {}
247
+ for page in pages:
248
+ if page.get("status", "current") != "current" or not self._wanted(self._labels(page)):
249
+ continue
250
+ found[str(page["id"])] = page
251
+ if len(found) > self.s.max_pages:
252
+ raise SourceError(f"the spaces hold more than {self.s.max_pages} pages: narrow them or raise MAX_PAGES")
253
+ return found
254
+
255
+ def _item(self, page: dict) -> dict | None:
256
+ if page.get("status", "current") != "current" or not self._wanted(self._labels(page)):
257
+ return None
258
+ html = storage_to_html(page.get("body", {}).get("storage", {}).get("value", ""))
259
+ sections = [{"heading": " › ".join(s.heading_path) or None, "text": s.text} for s in html_to_sections(html)]
260
+ item = {"id": str(page["id"]), "title": page["title"], "url": self.s.url + page["_links"]["webui"],
261
+ "version": self._version(page), "sections": sections, "weight": 1.0,
262
+ "labels": [f"space:{page['space']['key']}", *sorted(self._labels(page))],
263
+ "updated": _iso(page["version"]["when"])}
264
+ if ancestors := [a["title"] for a in page.get("ancestors", [])][-4:]:
265
+ item["path"] = ancestors
266
+ return item
267
+
268
+ # -- the protocol --------------------------------------------------------------------------------
269
+
270
+ def versions(self) -> dict[str, str]:
271
+ found: dict[str, dict] = {}
272
+ for space in self.s.spaces:
273
+ pages = self._listing(self.api.paged("/rest/api/content", spaceKey=space, type="page", status="current",
274
+ expand="version,metadata.labels"))
275
+ if not pages:
276
+ self.warn(f"the space {space!r} lists no pages: check the key and the token's permissions")
277
+ found.update(pages)
278
+ if len(found) > self.s.max_pages:
279
+ raise SourceError(f"the spaces hold more than {self.s.max_pages} pages: narrow them or raise MAX_PAGES")
280
+ return {pid: self._version(p) for pid, p in found.items()}
281
+
282
+ def fetch(self, ids: list[str]) -> Iterator[dict]:
283
+ for pid in ids:
284
+ if not pid.isdecimal():
285
+ continue
286
+ try:
287
+ page = self.api.get(f"/rest/api/content/{pid}", expand=FETCH_EXPAND)
288
+ except ApiError as e:
289
+ if e.status == 404: # gone since the listing: the next reconcile settles it
290
+ continue
291
+ raise
292
+ if page.get("space", {}).get("key") in self.s.spaces and (item := self._item(page)):
293
+ yield item
294
+
295
+ def changed(self, since: datetime) -> Iterator[dict]:
296
+ # CQL reads the time in the server's (or the user's) zone, not UTC: ask 14 hours early, which covers every
297
+ # zone; pages whose version is unchanged are dropped by the core anyway
298
+ stamp = (since.astimezone(UTC) - timedelta(hours=14)).strftime("%Y-%m-%d %H:%M")
299
+ keys = ",".join(f'"{s}"' for s in self.s.spaces)
300
+ cql = f'space in ({keys}) and type = page and lastModified >= "{stamp}"'
301
+ for page in self.api.paged("/rest/api/content/search", cql=cql, expand=FETCH_EXPAND):
302
+ if item := self._item(page):
303
+ yield item
304
+
305
+
306
+ def main() -> None:
307
+ Confluence.main()
@@ -0,0 +1,160 @@
1
+ """Confluence storage format (XHTML with ac:/ri: macros) → plain-text sections split at h1/h2/h3 headings."""
2
+
3
+ import math
4
+ import re
5
+ from dataclasses import dataclass
6
+
7
+ from selectolax.lexbor import LexborHTMLParser as HTMLParser, LexborNode as Node
8
+
9
+ SECTION_TAGS = {"h1", "h2", "h3"}
10
+ LIST_TAGS = {"ul", "ol"}
11
+ # Containers whose children are blocks in their own right.
12
+ CONTAINER_TAGS = {"body", "div", "section", "article", "figure", "blockquote", "main", "details"}
13
+ SKIP_TAGS = {"script", "style", "img", "svg", "head"}
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class Section:
18
+ heading_path: tuple[str, ...]
19
+ text: str
20
+ ordinal: int
21
+
22
+
23
+ def approx_tokens(s: str) -> int:
24
+ return math.ceil(len(s.split()) * 1.3)
25
+
26
+
27
+ BLOCK_TAGS = {"p", "div", "li", "ul", "ol", "table", "tr", "td", "th", "h1", "h2", "h3", "h4", "h5", "h6",
28
+ "pre", "blockquote", "section", "article", "figure", "details", "summary"}
29
+
30
+
31
+ def _text(node: Node) -> str:
32
+ """Text of a node, with a space wherever a block element or <br> separates words."""
33
+ parts = []
34
+ for child in node.iter(include_text=True):
35
+ if child.tag == "-text":
36
+ parts.append(child.text_content or "")
37
+ elif child.tag == "br":
38
+ parts.append(" ")
39
+ elif child.tag in SKIP_TAGS:
40
+ continue
41
+ elif child.tag in BLOCK_TAGS:
42
+ parts.append(f" {_text(child)} ")
43
+ else:
44
+ parts.append(_text(child))
45
+ return "".join(parts)
46
+
47
+
48
+ def _inline(node: Node) -> str:
49
+ return re.sub(r"\s+", " ", _text(node)).strip()
50
+
51
+
52
+ def _list_lines(node: Node, depth: int = 0) -> list[str]:
53
+ lines = []
54
+ for li in node.iter():
55
+ if li.tag != "li":
56
+ continue
57
+ own, nested = [], []
58
+ for child in li.iter(include_text=True):
59
+ if child.tag in LIST_TAGS:
60
+ nested.extend(_list_lines(child, depth + 1))
61
+ elif child.tag == "-text":
62
+ own.append(child.text_content or "")
63
+ elif child.tag in BLOCK_TAGS:
64
+ own.append(f" {_text(child)} ")
65
+ else:
66
+ own.append(_text(child))
67
+ text = re.sub(r"\s+", " ", "".join(own)).strip()
68
+ if text:
69
+ lines.append(" " * depth + "- " + text)
70
+ lines.extend(nested)
71
+ return lines
72
+
73
+
74
+ def _table_lines(node: Node) -> list[str]:
75
+ lines = []
76
+ for tr in node.css("tr"):
77
+ cells = [_inline(c) for c in tr.iter() if c.tag in ("td", "th")]
78
+ if any(cells):
79
+ lines.append(" | ".join(cells))
80
+ return lines
81
+
82
+
83
+ def _blocks(node: Node):
84
+ """Yield ("heading", level, text) and ("text", None, text) in document order."""
85
+ pending_inline: list[str] = []
86
+
87
+ def flush():
88
+ text = re.sub(r"\s+", " ", "".join(pending_inline)).strip()
89
+ pending_inline.clear()
90
+ return text
91
+
92
+ for child in node.iter(include_text=True):
93
+ tag = child.tag
94
+ if tag == "-text" or tag in ("span", "a", "strong", "em", "b", "i", "code", "u", "s", "sub", "sup", "mark", "br"):
95
+ pending_inline.append(child.text_content if tag == "-text" else " " if tag == "br" else _text(child))
96
+ continue
97
+ if (text := flush()):
98
+ yield ("text", None, text)
99
+ if tag in SKIP_TAGS:
100
+ continue
101
+ if tag in SECTION_TAGS:
102
+ yield ("heading", int(tag[1]), _inline(child))
103
+ elif tag in LIST_TAGS:
104
+ if (lines := _list_lines(child)):
105
+ yield ("text", None, "\n".join(lines))
106
+ elif tag == "table":
107
+ if (lines := _table_lines(child)):
108
+ yield ("text", None, "\n".join(lines))
109
+ elif tag == "pre":
110
+ raw = child.text(deep=True, separator="").strip("\n")
111
+ if raw.strip():
112
+ yield ("text", None, raw)
113
+ elif tag in CONTAINER_TAGS:
114
+ yield from _blocks(child)
115
+ else:
116
+ if (text := _inline(child)):
117
+ yield ("text", None, text)
118
+ if (text := flush()):
119
+ yield ("text", None, text)
120
+
121
+
122
+ def _split_words(text: str, max_tokens: int) -> list[str]:
123
+ words = text.split()
124
+ per = max(1, int(max_tokens / 1.3))
125
+ return [" ".join(words[i:i + per]) for i in range(0, len(words), per)]
126
+
127
+
128
+ def _chunk(paragraphs: list[str], max_tokens: int) -> list[str]:
129
+ chunks, current = [], []
130
+ for para in paragraphs:
131
+ pieces = [para] if approx_tokens(para) <= max_tokens else _split_words(para, max_tokens)
132
+ for piece in pieces:
133
+ if current and approx_tokens("\n".join(current + [piece])) > max_tokens:
134
+ chunks.append("\n".join(current))
135
+ current = []
136
+ current.append(piece)
137
+ if current:
138
+ chunks.append("\n".join(current))
139
+ return chunks
140
+
141
+
142
+ def html_to_sections(html: str, max_tokens: int = 350) -> list[Section]:
143
+ if not html or not html.strip():
144
+ return []
145
+ body = HTMLParser(html).body
146
+ if body is None:
147
+ return []
148
+ groups: list[tuple[tuple[str, ...], list[str]]] = [((), [])]
149
+ trail: list[tuple[int, str]] = []
150
+ for kind, level, text in _blocks(body):
151
+ if kind == "heading":
152
+ trail = [t for t in trail if t[0] < level] + [(level, text)]
153
+ groups.append((tuple(t[1] for t in trail), []))
154
+ else:
155
+ groups[-1][1].append(text)
156
+ sections = []
157
+ for path, paragraphs in groups:
158
+ for chunk in _chunk(paragraphs, max_tokens):
159
+ sections.append(Section(path, chunk, len(sections)))
160
+ return sections
@@ -0,0 +1,58 @@
1
+ Metadata-Version: 2.5
2
+ Name: passageway-connector-confluence
3
+ Version: 0.3.0
4
+ Summary: passageway connector for Confluence Data Center: the pages of chosen spaces, read-only
5
+ License-Expression: PolyForm-Noncommercial-1.0.0
6
+ Requires-Python: >=3.12
7
+ Requires-Dist: passageway-sdk[web]~=0.3.0
8
+ Requires-Dist: selectolax>=0.3.21
9
+ Description-Content-Type: text/markdown
10
+
11
+ # passageway-connector-confluence
12
+
13
+ A [passageway](https://github.com/getpassageway/passageway#readme) connector for **Confluence Data Center** (and Server): the current pages of the spaces you name, read through the REST API with GET requests only, using a personal access token. Written from the public REST documentation.
14
+
15
+ ## What it does
16
+
17
+ - **Each page is one item.** Its id is the content id, its version changes with every page version and with its labels, and its link opens the page in Confluence.
18
+ - **Headings become sections:** `h1`, `h2` and `h3` split a page into passages with their heading trail (`Setup › Linux`); lists, tables and code macros are kept readable; long sections are cut at about 350 tokens.
19
+ - **Labels become labels** (`space:OPS` plus the page's own), **ancestors become the path** (nearest last, up to four), and every page weighs 1.0.
20
+ - **Macros:** code and noformat macros keep their text; boxes, expands, sections, columns, excerpts and every other macro with a body keep what they hold; a status macro keeps its title; a table of contents, Jira issues, images, emoticons and other macros without a body are left out. Task lists become lists. Links keep their text, or the linked page's title. Blog posts and attachments are not indexed.
21
+ - **Edits appear within a minute:** `changed` asks Confluence with CQL for the pages modified since the last poll (fourteen hours early, because CQL reads the time in the server's zone; unchanged versions cost nothing). Deletions, moves out of the spaces and labels that take a page out of scope are settled at the next reconcile. A space that lists no pages is reported as a warning, so a wrong key or a token without permission does not pass in silence.
22
+
23
+ ## Configure
24
+
25
+ Create a personal access token under your profile in Confluence (Data Center and Server 7.9 and later). The connector only ever sends GET requests.
26
+
27
+ ```toml
28
+ [[connector]]
29
+ name = "wiki"
30
+ command = ["/path/to/python", "-m", "passageway_connector_confluence"]
31
+ env = { URL = "https://wiki.example.org", SPACES = "OPS|HR" }
32
+ secrets = { TOKEN = "env:CONFLUENCE_TOKEN" }
33
+ ```
34
+
35
+ | Setting | Default | Meaning |
36
+ |---|---|---|
37
+ | `URL` | required | The Confluence site, e.g. `https://wiki.example.org` (with its context path, if any) |
38
+ | `SPACES` | required | Space keys to index, separated by `\|` |
39
+ | `TOKEN` | required | A personal access token, as a secret reference such as `env:CONFLUENCE_TOKEN` |
40
+ | `INCLUDE_LABELS` | | Only pages carrying one of these labels, separated by `\|` |
41
+ | `EXCLUDE_LABELS` | | Pages carrying one of these labels are left out |
42
+ | `MAX_PAGES` | `5000` | Upper bound on the spaces together; more fails with a message instead of indexing a subset |
43
+ | `TIMEOUT` | `30` | Seconds per request |
44
+ | `PAUSE_SECONDS` | `0` | Pause between requests, for a busy server |
45
+ | `VERIFY_TLS` | `true` | `false` turns certificate checking off. A CA your operating system trusts already works without it (see [Certificates](https://passageway.marceltov.de/configuration/#certificates)), so prefer adding the CA there |
46
+
47
+ ## Behaviour
48
+
49
+ - **Retries:** 429 and 5xx answers and network errors are retried with a growing wait (1 s, doubling up to 60 s; a longer `Retry-After` is honoured up to 300 s) until a request has waited 15 minutes in total; the error then says how many attempts and how long it waited. Every wait of 10 s or more is logged as it starts (`HTTP 429 … waiting 16 s (15 s of 900 s waited)`), so a sync that waits does not look hung. A 401 says to check the token; any other error fails the call and nothing is stored.
50
+ - **A throttled or large space** needs more than the core's default `timeout = 300` for the whole `list` or `fetch`: waiting out one rate limit can take minutes. Raise `timeout` in its `[[connector]]` entry (`3600` is a start), or set `PAUSE_SECONDS` so fewer requests are throttled in the first place.
51
+ - **Cloud:** Atlassian Cloud authenticates with an e-mail address and an API token and serves the API under `/wiki`; it is not supported yet ([ADR 0005](https://passageway.marceltov.de/adr/0005-confluence-data-center-first/)).
52
+ - **Tested against a fake** of the Data Center API in this repository, not against a live Confluence.
53
+
54
+ ## Test
55
+
56
+ ```bash
57
+ uv run pytest connectors/confluence # offline, against an in-test Confluence
58
+ ```
@@ -0,0 +1,7 @@
1
+ passageway_connector_confluence/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
2
+ passageway_connector_confluence/__main__.py,sha256=S8_ZHOtMBl_PBepEoqsuZQ96_HdYKnsxk6Wm8a9SHBc,67
3
+ passageway_connector_confluence/connector.py,sha256=A1hFdsUwHsS2ANiQsL_er_X9eA9KvE_bNo2jtdDtqZY,14492
4
+ passageway_connector_confluence/html.py,sha256=mZvLSQbn3LUfPs2ip2n9uS5bBD4Ke6kZfpvPywjs6YU,5495
5
+ passageway_connector_confluence-0.3.0.dist-info/METADATA,sha256=tLhPc9E1oAP1jKbeTpEBjyalmdgB9eYLBVJVGl_KHSM,4678
6
+ passageway_connector_confluence-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ passageway_connector_confluence-0.3.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any