tickwire-cli 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.
- tickwire_cli/__init__.py +4 -0
- tickwire_cli/__main__.py +14 -0
- tickwire_cli/_version.py +1 -0
- tickwire_cli/app.py +174 -0
- tickwire_cli/commands/__init__.py +11 -0
- tickwire_cli/commands/accounts.py +51 -0
- tickwire_cli/commands/login.py +81 -0
- tickwire_cli/commands/logs.py +272 -0
- tickwire_cli/commands/sandbox.py +74 -0
- tickwire_cli/commands/trade.py +153 -0
- tickwire_cli/commands/trigger.py +44 -0
- tickwire_cli/commands/webhooks_listen.py +112 -0
- tickwire_cli/credentials.py +259 -0
- tickwire_cli/errors.py +6 -0
- tickwire_cli/output.py +96 -0
- tickwire_cli-0.1.0.dist-info/METADATA +93 -0
- tickwire_cli-0.1.0.dist-info/RECORD +21 -0
- tickwire_cli-0.1.0.dist-info/WHEEL +5 -0
- tickwire_cli-0.1.0.dist-info/entry_points.txt +2 -0
- tickwire_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
- tickwire_cli-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""``tickwire sandbox create``: a free sandbox with one simulated account, no sign-in.
|
|
2
|
+
|
|
3
|
+
Calls ``POST /v1/sandbox/signup`` (anonymous, rate limited per IP) and stores
|
|
4
|
+
the new ``twsk_`` key in the ``sandbox`` profile, so ``tickwire --sandbox …``
|
|
5
|
+
works at once. The key is shown once by the server and is not printed unless
|
|
6
|
+
you ask (``--show-key``). It is a **restricted** key: accounts, trading,
|
|
7
|
+
streaming and reads. For webhooks (``listen``, ``trigger``), sign in and create
|
|
8
|
+
a sandbox key with ``POST /v1/sandbox/keys``, then ``tickwire login --sandbox``.
|
|
9
|
+
|
|
10
|
+
A lost reply is reported as ``unknown`` and never retried: a retry could create
|
|
11
|
+
a second sandbox.
|
|
12
|
+
"""
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from tickwire import OutcomeUnknown, sandbox_signup
|
|
16
|
+
|
|
17
|
+
from ..credentials import SANDBOX_PROFILE
|
|
18
|
+
from ..errors import UsageError
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def register(sub, common) -> None:
|
|
22
|
+
p = sub.add_parser("sandbox", parents=[common], help="the free sandbox")
|
|
23
|
+
ss = p.add_subparsers(dest="sandbox_command", metavar="<subcommand>")
|
|
24
|
+
ss.required = True
|
|
25
|
+
c = ss.add_parser("create", parents=[common], help="create a sandbox and store its key",
|
|
26
|
+
description=__doc__.split("\n\n")[1] if __doc__ else None)
|
|
27
|
+
c.add_argument("--platform", choices=["mt5", "mt4"], default="mt5")
|
|
28
|
+
c.add_argument("--no-save", action="store_true", help="do not store the key (needs --show-key)")
|
|
29
|
+
c.add_argument("--show-key", action="store_true", help="print the key (shown once by the server)")
|
|
30
|
+
c.add_argument("--force", action="store_true", help="replace the key already stored in the profile")
|
|
31
|
+
c.set_defaults(func=create)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def create(ctx) -> int:
|
|
35
|
+
args = ctx.args
|
|
36
|
+
if args.no_save and not args.show_key:
|
|
37
|
+
raise UsageError("--no-save would lose the key (the server shows it once): add --show-key")
|
|
38
|
+
name = args.profile or SANDBOX_PROFILE
|
|
39
|
+
existing = ctx.store.profile(name)
|
|
40
|
+
if not args.no_save and existing is not None and existing.storage and not args.force:
|
|
41
|
+
raise UsageError(f"profile {name!r} already holds a key ({existing.key_hint}); pass --force to "
|
|
42
|
+
f"replace it, or --profile <new name>")
|
|
43
|
+
if existing is not None and not existing.sandbox:
|
|
44
|
+
raise UsageError(f"profile {name!r} is a live profile; use another --profile")
|
|
45
|
+
url = ctx.api_url(sandbox=True)
|
|
46
|
+
try:
|
|
47
|
+
body = sandbox_signup(url, platform=args.platform, transport=ctx.transport)
|
|
48
|
+
except OutcomeUnknown as e:
|
|
49
|
+
ctx.out.error("unknown", f"{e.message}. Not retried; run `tickwire sandbox create` again only "
|
|
50
|
+
f"if you want another sandbox")
|
|
51
|
+
return 5
|
|
52
|
+
key = body.get("apiKey", "")
|
|
53
|
+
stored = None
|
|
54
|
+
if not args.no_save:
|
|
55
|
+
stored = ctx.store.save(name, key, api_url=url, sandbox=True)
|
|
56
|
+
account = body.get("account") or {}
|
|
57
|
+
data = {"sandbox": True, "restricted": bool(body.get("restricted")), "tenantId": body.get("tenantId"),
|
|
58
|
+
"account": account, "profile": name if stored else None,
|
|
59
|
+
"storage": stored.storage if stored else None,
|
|
60
|
+
"key": stored.key_hint if stored else None}
|
|
61
|
+
if args.show_key:
|
|
62
|
+
data["apiKey"] = key
|
|
63
|
+
lines = [f"Sandbox created at {url}.",
|
|
64
|
+
f"Account {account.get('id')} ({account.get('platform')}, login {account.get('login')}, "
|
|
65
|
+
f"server {account.get('server')}): {account.get('state')}, {account.get('connectionStatus')}."]
|
|
66
|
+
if stored:
|
|
67
|
+
lines.append(f"Key {stored.key_hint} stored in profile {name!r}: use `tickwire --sandbox …`.")
|
|
68
|
+
if args.show_key:
|
|
69
|
+
lines.append(f"API key (shown once): {key}")
|
|
70
|
+
if body.get("restricted"):
|
|
71
|
+
lines.append("This key is restricted (accounts, trading, reads). For webhooks, create a sandbox key "
|
|
72
|
+
"from your live key: POST /v1/sandbox/keys.")
|
|
73
|
+
ctx.out.result(data, "\n".join(lines))
|
|
74
|
+
return 0
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
"""``tickwire trade open|close``: guarded, idempotent trades with a truthful outcome.
|
|
2
|
+
|
|
3
|
+
Every trade goes through ``POST /v1/execution/accounts/{id}/trade`` (the
|
|
4
|
+
account's pre-trade hooks apply), needs ``--reason`` (kept in the audit log)
|
|
5
|
+
and carries an ``Idempotency-Key``: generated when you do not pass one, and
|
|
6
|
+
always printed so you can repeat the *same* request safely.
|
|
7
|
+
|
|
8
|
+
The answer is one of:
|
|
9
|
+
|
|
10
|
+
``applied`` the terminal confirmed it (exit 0)
|
|
11
|
+
``no_change`` nothing needed doing, e.g. already closed (exit 0)
|
|
12
|
+
``rejected`` not executed (exit 3)
|
|
13
|
+
``held`` a pre-trade hook holds it for approval; nothing executed yet (exit 4)
|
|
14
|
+
``unknown`` it MAY have executed (exit 5)
|
|
15
|
+
|
|
16
|
+
``unknown`` is never retried, by the SDK or by this command. Check the account
|
|
17
|
+
first; to try again, pass the printed key with ``--idempotency-key`` so the
|
|
18
|
+
server can refuse a second execution. A server error (5xx) without an outcome
|
|
19
|
+
is reported as ``unknown`` too, never as a failure that is safe to repeat.
|
|
20
|
+
"""
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import math
|
|
24
|
+
|
|
25
|
+
from tickwire import OutcomeUnknown, TickwireError, TradeResult, new_idempotency_key
|
|
26
|
+
|
|
27
|
+
from ..errors import UsageError
|
|
28
|
+
|
|
29
|
+
EXIT = {"applied": 0, "no_change": 0, "rejected": 3, "held": 4, "unknown": 5}
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def register(sub, common) -> None:
|
|
33
|
+
p = sub.add_parser("trade", parents=[common], help="open or close a position (needs --reason)",
|
|
34
|
+
description=__doc__.split("\n\n")[1] if __doc__ else None)
|
|
35
|
+
ss = p.add_subparsers(dest="trade_command", metavar="<subcommand>")
|
|
36
|
+
ss.required = True
|
|
37
|
+
|
|
38
|
+
o = ss.add_parser("open", parents=[common], help="market order")
|
|
39
|
+
o.add_argument("account_id")
|
|
40
|
+
o.add_argument("--side", choices=["buy", "sell"], required=True)
|
|
41
|
+
o.add_argument("--symbol", required=True)
|
|
42
|
+
o.add_argument("--volume", type=float, required=True, help="lots, e.g. 0.01")
|
|
43
|
+
o.add_argument("--sl", type=float, help="stop loss price")
|
|
44
|
+
o.add_argument("--tp", type=float, help="take profit price")
|
|
45
|
+
o.add_argument("--comment")
|
|
46
|
+
o.add_argument("--client-id", help="your own order tag")
|
|
47
|
+
_mutation_args(o)
|
|
48
|
+
o.set_defaults(func=trade_open)
|
|
49
|
+
|
|
50
|
+
c = ss.add_parser("close", parents=[common], help="close a position (all of it, or --volume)")
|
|
51
|
+
c.add_argument("account_id")
|
|
52
|
+
c.add_argument("position_id")
|
|
53
|
+
c.add_argument("--volume", type=float, help="close only this many lots")
|
|
54
|
+
_mutation_args(c)
|
|
55
|
+
c.set_defaults(func=trade_close)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _mutation_args(p) -> None:
|
|
59
|
+
p.add_argument("--reason", required=True, help="why (recorded in the audit log)")
|
|
60
|
+
p.add_argument("--idempotency-key", help="repeat an earlier request safely (reuse its key)")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _volume(v: float | None) -> float | None:
|
|
64
|
+
if v is not None and (not math.isfinite(v) or v <= 0):
|
|
65
|
+
raise UsageError("--volume must be a positive number of lots")
|
|
66
|
+
return v
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def trade_open(ctx) -> int:
|
|
70
|
+
a = ctx.args
|
|
71
|
+
body = {"actionType": "ORDER_TYPE_BUY" if a.side == "buy" else "ORDER_TYPE_SELL",
|
|
72
|
+
"symbol": a.symbol, "volume": _volume(a.volume)}
|
|
73
|
+
for field, value in (("stopLoss", a.sl), ("takeProfit", a.tp), ("comment", a.comment),
|
|
74
|
+
("clientId", a.client_id)):
|
|
75
|
+
if value is not None:
|
|
76
|
+
body[field] = value
|
|
77
|
+
return _execute(ctx, body)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def trade_close(ctx) -> int:
|
|
81
|
+
a = ctx.args
|
|
82
|
+
if a.volume is None:
|
|
83
|
+
body = {"actionType": "POSITION_CLOSE_ID", "positionId": str(a.position_id)}
|
|
84
|
+
else:
|
|
85
|
+
body = {"actionType": "POSITION_PARTIAL", "positionId": str(a.position_id), "volume": _volume(a.volume)}
|
|
86
|
+
return _execute(ctx, body)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _execute(ctx, body: dict) -> int:
|
|
90
|
+
a = ctx.args
|
|
91
|
+
reason = (a.reason or "").strip()
|
|
92
|
+
if not reason:
|
|
93
|
+
raise UsageError("--reason must say why (it is recorded in the audit log)")
|
|
94
|
+
key = (a.idempotency_key or "").strip() or new_idempotency_key()
|
|
95
|
+
tw = ctx.client()
|
|
96
|
+
try:
|
|
97
|
+
# One call. The CLI never retries on its own; the SDK repeats it (same key)
|
|
98
|
+
# only when nothing ran: the connection never opened, a 409
|
|
99
|
+
# idempotency_in_flight, or a 429/5xx whose body says ``sent: false``.
|
|
100
|
+
# A bare status code never counts, and a lost reply is never retried.
|
|
101
|
+
result = tw.execute_trade(a.account_id, body, reason=reason, idempotency_key=key)
|
|
102
|
+
except OutcomeUnknown as e:
|
|
103
|
+
result = TradeResult.unknown(key, e.message, e.status)
|
|
104
|
+
except TickwireError as e:
|
|
105
|
+
b = e.body if isinstance(e.body, dict) else {}
|
|
106
|
+
if e.status is not None and _says_not_sent(b):
|
|
107
|
+
# The server said explicitly that nothing was sent (retries used up).
|
|
108
|
+
result = TradeResult(outcome="rejected", sent=False, idempotency_key=key, status=e.status,
|
|
109
|
+
body={**b, "error": e.code or b.get("error"), "message": e.message})
|
|
110
|
+
elif e.status is not None and e.status >= 500:
|
|
111
|
+
result = TradeResult.unknown(key, f"HTTP {e.status} with no outcome: {e.message}", e.status)
|
|
112
|
+
elif e.status is not None and 400 <= e.status < 500:
|
|
113
|
+
result = TradeResult(outcome="rejected", sent=False, idempotency_key=key, status=e.status,
|
|
114
|
+
body={**b, "error": e.code or b.get("error"), "message": e.message})
|
|
115
|
+
else:
|
|
116
|
+
raise # not sent (no connection): exit 1 with the SDK's message
|
|
117
|
+
_report(ctx, a.account_id, body, result)
|
|
118
|
+
return EXIT[result.outcome]
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _says_not_sent(body: dict) -> bool:
|
|
122
|
+
"""The SDK's rule: ``sent: false`` or ``outcome: "not_sent"`` (top level or metadata)."""
|
|
123
|
+
meta = body.get("metadata") if isinstance(body.get("metadata"), dict) else {}
|
|
124
|
+
sent = body.get("sent", meta.get("sent"))
|
|
125
|
+
if sent is not None:
|
|
126
|
+
return sent is False
|
|
127
|
+
return body.get("outcome", meta.get("outcome")) == "not_sent"
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _report(ctx, account_id: str, request: dict, r: TradeResult) -> None:
|
|
131
|
+
data = {"accountId": account_id, "request": request, "outcome": r.outcome, "sent": r.sent,
|
|
132
|
+
"idempotencyKey": r.idempotency_key, "status": r.status, "error": r.error, "message": r.message,
|
|
133
|
+
"evidence": r.evidence, "holdId": r.hold_id, "replayed": r.replayed, "body": r.body}
|
|
134
|
+
|
|
135
|
+
def human() -> str:
|
|
136
|
+
lines = [f"outcome: {r.outcome.upper()} (sent: {str(r.sent).lower()})",
|
|
137
|
+
f"idempotency key: {r.idempotency_key}"]
|
|
138
|
+
if r.replayed:
|
|
139
|
+
lines.append("replayed: the server returned the answer to the first request with this key")
|
|
140
|
+
if r.error or r.message:
|
|
141
|
+
lines.append(f"{r.error or 'message'}: {r.message or ''}".rstrip(": "))
|
|
142
|
+
if r.evidence:
|
|
143
|
+
lines.append(f"evidence: {r.evidence}")
|
|
144
|
+
if r.outcome == "held":
|
|
145
|
+
lines.append(f"hold: {r.hold_id}. A pre-trade hook holds this order for approval; nothing has "
|
|
146
|
+
f"executed yet.")
|
|
147
|
+
if r.outcome == "unknown":
|
|
148
|
+
lines.append("The order MAY have executed. It was NOT re-sent. Check the account's positions "
|
|
149
|
+
"before doing anything else. To try again safely, repeat this exact command with "
|
|
150
|
+
f"--idempotency-key {r.idempotency_key} (the server will not execute it twice).")
|
|
151
|
+
return "\n".join(lines)
|
|
152
|
+
|
|
153
|
+
ctx.out.result(data, human)
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""``tickwire trigger <event>``: publish one test event (``POST /v1/webhook-events/trigger``).
|
|
2
|
+
|
|
3
|
+
The event carries the catalog's example data plus ``"test": true`` and goes to
|
|
4
|
+
your real webhook endpoints and to running ``tickwire listen`` sessions. With a
|
|
5
|
+
sandbox key any catalog type works; with a live key only ``webhook.test``, so a
|
|
6
|
+
test trade never reaches a production handler. ``tickwire trigger --list``
|
|
7
|
+
shows the types.
|
|
8
|
+
"""
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from ..errors import UsageError
|
|
12
|
+
from ..output import clean, table
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def register(sub, common) -> None:
|
|
16
|
+
p = sub.add_parser("trigger", parents=[common], help="send a test webhook event",
|
|
17
|
+
description=__doc__.split("\n\n")[1] if __doc__ else None)
|
|
18
|
+
p.add_argument("event", nargs="?", help="event type, e.g. trade.outcome (see --list)")
|
|
19
|
+
p.add_argument("--account", help="put this account id in the event (must be yours)")
|
|
20
|
+
p.add_argument("--list", action="store_true", help="list the event types")
|
|
21
|
+
p.add_argument("--idempotency-key", help="repeat an earlier trigger without sending it twice")
|
|
22
|
+
p.set_defaults(func=trigger)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def trigger(ctx) -> int:
|
|
26
|
+
a = ctx.args
|
|
27
|
+
tw = ctx.client()
|
|
28
|
+
if a.list:
|
|
29
|
+
types = tw.webhook_event_types()
|
|
30
|
+
rows = types.get("data", types) if isinstance(types, dict) else types
|
|
31
|
+
ctx.out.result(rows, lambda: table([[t.get("type"), t.get("description")] for t in rows],
|
|
32
|
+
["TYPE", "DESCRIPTION"]))
|
|
33
|
+
return 0
|
|
34
|
+
if not a.event:
|
|
35
|
+
raise UsageError("name an event type (tickwire trigger --list shows them)")
|
|
36
|
+
body = {"type": a.event}
|
|
37
|
+
if a.account:
|
|
38
|
+
body["accountId"] = a.account
|
|
39
|
+
out = tw.request("POST", "/webhook-events/trigger", control=True, json=body,
|
|
40
|
+
idempotency_key=a.idempotency_key, reason="tickwire trigger")
|
|
41
|
+
ctx.out.result(out, f"Triggered test event {clean(out.get('type'))} (seq {clean(out.get('seq'))}, "
|
|
42
|
+
f"{'sandbox' if out.get('sandbox') else 'live'}). It goes to your webhook endpoints "
|
|
43
|
+
f"and to running `tickwire listen` sessions.")
|
|
44
|
+
return 0
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
"""``tickwire listen --forward-to <url>``: receive your webhook events on localhost.
|
|
2
|
+
|
|
3
|
+
How it works (``docs/public/cli.md`` has the full story):
|
|
4
|
+
|
|
5
|
+
1. ``POST /v1/webhook-listeners`` creates a listener and returns its signing
|
|
6
|
+
secret (printed on start: configure your local handler with it).
|
|
7
|
+
2. The CLI polls ``GET /v1/webhook-listeners/{id}/events``. The control plane
|
|
8
|
+
signs each event with the listener secret, exactly as it signs real
|
|
9
|
+
deliveries (``X-Tickwire-Signature`` and the Standard Webhooks headers).
|
|
10
|
+
3. The CLI verifies both signatures and the timestamp before forwarding. An
|
|
11
|
+
event that fails verification is never forwarded: the command stops.
|
|
12
|
+
4. It POSTs the exact signed bytes and headers to ``--forward-to`` and prints
|
|
13
|
+
the status. A failed forward is reported and not retried.
|
|
14
|
+
|
|
15
|
+
Events published while nothing was listening are not replayed, and a listener
|
|
16
|
+
that falls behind the server's event buffer is told so (``truncated``).
|
|
17
|
+
"""
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import time
|
|
21
|
+
from urllib.parse import quote, urlsplit
|
|
22
|
+
|
|
23
|
+
import httpx
|
|
24
|
+
from tickwire import WebhookVerificationError, verify_standard_webhook, verify_webhook
|
|
25
|
+
|
|
26
|
+
from ..errors import UsageError
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def register(sub, common) -> None:
|
|
30
|
+
p = sub.add_parser("listen", parents=[common], help="forward your webhook events to a local URL",
|
|
31
|
+
description=__doc__.split("\n\n")[1] if __doc__ else None)
|
|
32
|
+
p.add_argument("--forward-to", required=True, metavar="URL", help="e.g. http://localhost:3000/webhooks")
|
|
33
|
+
p.add_argument("--events", default="", help="comma-separated types or families (trade.*); default all")
|
|
34
|
+
p.add_argument("--interval", type=float, default=2.0, help="seconds between polls when idle (default 2)")
|
|
35
|
+
p.add_argument("--timeout", type=float, default=10.0, help="seconds to wait for your handler (default 10)")
|
|
36
|
+
p.add_argument("--once", action="store_true", help="poll once, forward what is there, and exit")
|
|
37
|
+
p.set_defaults(func=listen)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _check_url(url: str) -> str:
|
|
41
|
+
parts = urlsplit(url)
|
|
42
|
+
if parts.scheme not in ("http", "https") or not parts.netloc:
|
|
43
|
+
raise UsageError(f"--forward-to must be an http(s) URL, e.g. http://localhost:3000/webhooks (got {url!r})")
|
|
44
|
+
return url
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def verify_event(secret: str, headers: dict, body: bytes) -> None:
|
|
48
|
+
"""Both signature schemes must match the listener secret; raises on any mismatch."""
|
|
49
|
+
verify_webhook(secret, headers, body)
|
|
50
|
+
verify_standard_webhook(secret, headers, body)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def listen(ctx) -> int:
|
|
54
|
+
a = ctx.args
|
|
55
|
+
target = _check_url(a.forward_to)
|
|
56
|
+
if a.interval <= 0 or a.timeout <= 0:
|
|
57
|
+
raise UsageError("--interval and --timeout must be positive")
|
|
58
|
+
types = [t.strip() for t in a.events.split(",") if t.strip()]
|
|
59
|
+
tw = ctx.client()
|
|
60
|
+
lst = tw.request("POST", "/webhook-listeners", control=True, reason="tickwire listen")
|
|
61
|
+
lid, secret, cursor = lst["id"], lst["secret"], str(lst.get("cursor") or "") # opaque "<boot>:<seq>"
|
|
62
|
+
ctx.out.line({"ready": True, "listener": lid, "secret": secret, "forwardTo": target, "events": types or ["*"]},
|
|
63
|
+
[f"Ready. Forwarding {'events ' + ','.join(types) if types else 'all events'} to {target}.",
|
|
64
|
+
f"Listener signing secret: {secret}",
|
|
65
|
+
"(verify deliveries with it locally; it is not your API key). Ctrl-C to stop."])
|
|
66
|
+
params: dict = {"limit": 100}
|
|
67
|
+
if types:
|
|
68
|
+
params["types"] = ",".join(types)
|
|
69
|
+
with httpx.Client(transport=ctx.forward_transport, timeout=a.timeout) as http:
|
|
70
|
+
while True:
|
|
71
|
+
page = tw.request("GET", f"/webhook-listeners/{quote(lid, safe='')}/events", control=True,
|
|
72
|
+
params={**params, "after": cursor})
|
|
73
|
+
if page.get("reset"):
|
|
74
|
+
ctx.out.note("warning: the control plane restarted; showing its event buffer from the "
|
|
75
|
+
"start (events from before the restart, or that already left the buffer, "
|
|
76
|
+
"are missing)")
|
|
77
|
+
elif page.get("truncated"):
|
|
78
|
+
ctx.out.note("warning: this listener fell behind the server's event buffer; some events "
|
|
79
|
+
"were skipped")
|
|
80
|
+
for ev in page.get("events") or []:
|
|
81
|
+
code = _forward(ctx, http, target, secret, ev)
|
|
82
|
+
if code is not None:
|
|
83
|
+
return code
|
|
84
|
+
cursor = str(page.get("cursor") or cursor)
|
|
85
|
+
if a.once:
|
|
86
|
+
return 0
|
|
87
|
+
if not page.get("events"):
|
|
88
|
+
ctx.sleep(a.interval)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _forward(ctx, http: httpx.Client, target: str, secret: str, ev: dict) -> int | None:
|
|
92
|
+
body = str(ev.get("body", "")).encode()
|
|
93
|
+
headers = {str(k): str(v) for k, v in (ev.get("headers") or {}).items()}
|
|
94
|
+
base = {"seq": ev.get("seq"), "id": ev.get("id"), "type": ev.get("type")}
|
|
95
|
+
try:
|
|
96
|
+
verify_event(secret, headers, body)
|
|
97
|
+
except WebhookVerificationError as e:
|
|
98
|
+
ctx.out.error("signature_invalid", f"event {ev.get('id')} failed signature verification ({e}); "
|
|
99
|
+
f"nothing was forwarded. Stopping.", **base)
|
|
100
|
+
return 1
|
|
101
|
+
started = time.monotonic()
|
|
102
|
+
try:
|
|
103
|
+
resp = http.post(target, content=body, headers=headers)
|
|
104
|
+
except httpx.HTTPError as e:
|
|
105
|
+
ms = int((time.monotonic() - started) * 1000)
|
|
106
|
+
ctx.out.line({**base, "forwarded": False, "error": f"{type(e).__name__}: {e}", "latencyMs": ms},
|
|
107
|
+
f"{ev.get('type')} {ev.get('id')} -> not delivered ({type(e).__name__}); not retried")
|
|
108
|
+
return None
|
|
109
|
+
ms = int((time.monotonic() - started) * 1000)
|
|
110
|
+
ctx.out.line({**base, "forwarded": True, "status": resp.status_code, "latencyMs": ms},
|
|
111
|
+
f"{ev.get('type')} {ev.get('id')} -> [{resp.status_code}] {ms} ms")
|
|
112
|
+
return None
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
"""Where the CLI keeps profiles and API keys.
|
|
2
|
+
|
|
3
|
+
* ``config.json`` (in the config directory): one entry per profile, the API URL,
|
|
4
|
+
whether it is the sandbox, where its key is stored and a short hint of the key
|
|
5
|
+
(``twsk_…a1b2``). Never the key itself.
|
|
6
|
+
* The key: the OS keychain (``keyring``, service ``tickwire-cli``, user = the
|
|
7
|
+
profile) when the ``keyring`` package is installed and has a working backend;
|
|
8
|
+
otherwise ``credentials.json``, created with mode ``0600`` in a ``0700``
|
|
9
|
+
directory. A credentials file other users can read is refused, as ``ssh``
|
|
10
|
+
does, instead of used.
|
|
11
|
+
|
|
12
|
+
The config directory is ``$TICKWIRE_CONFIG_DIR``, else
|
|
13
|
+
``$XDG_CONFIG_HOME/tickwire``, else ``~/.config/tickwire``.
|
|
14
|
+
|
|
15
|
+
``TICKWIRE_API_KEY`` in the environment always wins over a stored key, so CI
|
|
16
|
+
jobs need no login.
|
|
17
|
+
"""
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import json
|
|
21
|
+
import os
|
|
22
|
+
import secrets
|
|
23
|
+
import stat
|
|
24
|
+
from collections.abc import Mapping
|
|
25
|
+
from dataclasses import dataclass
|
|
26
|
+
from pathlib import Path
|
|
27
|
+
from typing import Any
|
|
28
|
+
|
|
29
|
+
KEYRING_SERVICE = "tickwire-cli"
|
|
30
|
+
CONFIG_FILE = "config.json"
|
|
31
|
+
CREDENTIALS_FILE = "credentials.json"
|
|
32
|
+
DEFAULT_PROFILE = "default"
|
|
33
|
+
SANDBOX_PROFILE = "sandbox"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class CredentialError(Exception):
|
|
37
|
+
"""No usable credential, or an unsafe credentials file."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def config_dir(env: Mapping[str, str] | None = None) -> Path:
|
|
41
|
+
env = os.environ if env is None else env
|
|
42
|
+
if env.get("TICKWIRE_CONFIG_DIR"):
|
|
43
|
+
return Path(env["TICKWIRE_CONFIG_DIR"]).expanduser()
|
|
44
|
+
base = env.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
|
|
45
|
+
return Path(base).expanduser() / "tickwire"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def key_hint(key: str) -> str:
|
|
49
|
+
"""Enough to recognise a key, never enough to use it."""
|
|
50
|
+
prefix = key.split("_", 1)[0] + "_" if "_" in key[:12] else ""
|
|
51
|
+
return f"{prefix}…{key[-4:]}" if len(key) >= 12 else "…"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def load_keyring(module: Any = "auto") -> Any | None:
|
|
55
|
+
"""The ``keyring`` module when it has a working backend, else ``None``."""
|
|
56
|
+
if module is None:
|
|
57
|
+
return None
|
|
58
|
+
if module != "auto":
|
|
59
|
+
return module
|
|
60
|
+
try:
|
|
61
|
+
import keyring # type: ignore[import-not-found]
|
|
62
|
+
from keyring.backends import fail # type: ignore[import-not-found]
|
|
63
|
+
except Exception: # noqa: BLE001 - not installed or broken: use the file
|
|
64
|
+
return None
|
|
65
|
+
try:
|
|
66
|
+
backend = keyring.get_keyring()
|
|
67
|
+
if isinstance(backend, fail.Keyring) or getattr(backend, "priority", 1) <= 0:
|
|
68
|
+
return None
|
|
69
|
+
except Exception: # noqa: BLE001
|
|
70
|
+
return None
|
|
71
|
+
return keyring
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
@dataclass
|
|
75
|
+
class Profile:
|
|
76
|
+
name: str
|
|
77
|
+
api_url: str = ""
|
|
78
|
+
sandbox: bool = False
|
|
79
|
+
storage: str = "" # "keyring" | "file" | "" (no key stored)
|
|
80
|
+
key_hint: str = ""
|
|
81
|
+
|
|
82
|
+
def public(self) -> dict:
|
|
83
|
+
return {"profile": self.name, "apiUrl": self.api_url, "sandbox": self.sandbox,
|
|
84
|
+
"storage": self.storage or None, "key": self.key_hint or None}
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class CredentialStore:
|
|
88
|
+
def __init__(self, directory: Path | None = None, *, keyring_module: Any = "auto",
|
|
89
|
+
env: Mapping[str, str] | None = None) -> None:
|
|
90
|
+
self.env = os.environ if env is None else env
|
|
91
|
+
self.dir = directory or config_dir(self.env)
|
|
92
|
+
self._keyring_arg = keyring_module
|
|
93
|
+
self._keyring: Any = "unset"
|
|
94
|
+
|
|
95
|
+
# ---- keyring
|
|
96
|
+
@property
|
|
97
|
+
def keyring(self) -> Any | None:
|
|
98
|
+
if self._keyring == "unset":
|
|
99
|
+
self._keyring = load_keyring(self._keyring_arg)
|
|
100
|
+
return self._keyring
|
|
101
|
+
|
|
102
|
+
# ---- files
|
|
103
|
+
def _ensure_dir(self) -> None:
|
|
104
|
+
"""Create the config directory 0700. A directory that already exists is never
|
|
105
|
+
chmod-ed (it may be one the user chose, e.g. ``$HOME``); it must not be a
|
|
106
|
+
symlink and must belong to us."""
|
|
107
|
+
if not self.dir.exists():
|
|
108
|
+
self.dir.parent.mkdir(parents=True, exist_ok=True)
|
|
109
|
+
try:
|
|
110
|
+
self.dir.mkdir(mode=0o700)
|
|
111
|
+
except FileExistsError:
|
|
112
|
+
pass
|
|
113
|
+
else:
|
|
114
|
+
if os.name != "nt":
|
|
115
|
+
os.chmod(self.dir, 0o700) # umask-proof, on the directory we just made
|
|
116
|
+
self._check_dir()
|
|
117
|
+
|
|
118
|
+
def _check_dir(self) -> None:
|
|
119
|
+
st = os.lstat(self.dir)
|
|
120
|
+
if stat.S_ISLNK(st.st_mode) or not stat.S_ISDIR(st.st_mode):
|
|
121
|
+
raise CredentialError(f"{self.dir} is not a plain directory (a symlink?); refusing to use it")
|
|
122
|
+
if os.name != "nt" and st.st_uid != os.getuid():
|
|
123
|
+
raise CredentialError(f"{self.dir} belongs to another user; refusing to use it")
|
|
124
|
+
|
|
125
|
+
def _read_json(self, name: str, *, private: bool) -> dict:
|
|
126
|
+
path = self.dir / name
|
|
127
|
+
try:
|
|
128
|
+
st = os.lstat(path)
|
|
129
|
+
except FileNotFoundError:
|
|
130
|
+
return {}
|
|
131
|
+
if stat.S_ISLNK(st.st_mode) or not stat.S_ISREG(st.st_mode):
|
|
132
|
+
raise CredentialError(f"{path} is not a regular file (a symlink?); refusing to use it")
|
|
133
|
+
if private and os.name != "nt":
|
|
134
|
+
self._check_dir()
|
|
135
|
+
if st.st_uid != os.getuid():
|
|
136
|
+
raise CredentialError(f"{path} belongs to another user; refusing to use it")
|
|
137
|
+
mode = stat.S_IMODE(st.st_mode)
|
|
138
|
+
if mode & 0o077:
|
|
139
|
+
raise CredentialError(
|
|
140
|
+
f"{path} can be read by other users (mode {mode:o}); refusing to use it. "
|
|
141
|
+
f"Run: chmod 600 {path}")
|
|
142
|
+
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
|
|
143
|
+
fd = os.open(path, flags)
|
|
144
|
+
try:
|
|
145
|
+
with os.fdopen(fd, "r", encoding="utf-8") as fh:
|
|
146
|
+
text = fh.read()
|
|
147
|
+
except OSError:
|
|
148
|
+
raise CredentialError(f"cannot read {path}") from None
|
|
149
|
+
try:
|
|
150
|
+
data = json.loads(text or "{}")
|
|
151
|
+
except ValueError:
|
|
152
|
+
raise CredentialError(f"{path} is not valid JSON; fix or delete it") from None
|
|
153
|
+
return data if isinstance(data, dict) else {}
|
|
154
|
+
|
|
155
|
+
def _write_json(self, name: str, data: dict, *, private: bool) -> None:
|
|
156
|
+
"""Write a fresh, exclusively created temp file (never following a symlink),
|
|
157
|
+
then rename it over the target atomically."""
|
|
158
|
+
self._ensure_dir()
|
|
159
|
+
path = self.dir / name
|
|
160
|
+
mode = 0o600 if private else 0o644
|
|
161
|
+
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
|
|
162
|
+
for _ in range(10):
|
|
163
|
+
tmp = path.with_name(f".{path.name}.{secrets.token_hex(6)}.tmp")
|
|
164
|
+
try:
|
|
165
|
+
fd = os.open(tmp, flags, mode)
|
|
166
|
+
break
|
|
167
|
+
except FileExistsError:
|
|
168
|
+
continue
|
|
169
|
+
else:
|
|
170
|
+
raise CredentialError(f"cannot create a temporary file in {self.dir}")
|
|
171
|
+
try:
|
|
172
|
+
try:
|
|
173
|
+
if os.name != "nt":
|
|
174
|
+
os.fchmod(fd, mode) # umask-proof
|
|
175
|
+
os.write(fd, (json.dumps(data, indent=2, sort_keys=True) + "\n").encode())
|
|
176
|
+
os.fsync(fd)
|
|
177
|
+
finally:
|
|
178
|
+
os.close(fd)
|
|
179
|
+
os.replace(tmp, path)
|
|
180
|
+
except BaseException:
|
|
181
|
+
try:
|
|
182
|
+
os.unlink(tmp)
|
|
183
|
+
except OSError:
|
|
184
|
+
pass
|
|
185
|
+
raise
|
|
186
|
+
|
|
187
|
+
# ---- profiles
|
|
188
|
+
def profiles(self) -> dict[str, Profile]:
|
|
189
|
+
raw = self._read_json(CONFIG_FILE, private=False).get("profiles", {})
|
|
190
|
+
out = {}
|
|
191
|
+
for name, p in raw.items():
|
|
192
|
+
if isinstance(p, dict):
|
|
193
|
+
out[name] = Profile(name=name, api_url=p.get("api_url", ""), sandbox=bool(p.get("sandbox")),
|
|
194
|
+
storage=p.get("storage", ""), key_hint=p.get("key_hint", ""))
|
|
195
|
+
return out
|
|
196
|
+
|
|
197
|
+
def profile(self, name: str) -> Profile | None:
|
|
198
|
+
return self.profiles().get(name)
|
|
199
|
+
|
|
200
|
+
def _save_profiles(self, profiles: dict[str, Profile]) -> None:
|
|
201
|
+
self._write_json(CONFIG_FILE, {"profiles": {
|
|
202
|
+
n: {"api_url": p.api_url, "sandbox": p.sandbox, "storage": p.storage, "key_hint": p.key_hint}
|
|
203
|
+
for n, p in profiles.items()}}, private=False)
|
|
204
|
+
|
|
205
|
+
# ---- keys
|
|
206
|
+
def save(self, name: str, key: str, *, api_url: str, sandbox: bool, use_keyring: bool = True) -> Profile:
|
|
207
|
+
"""Store ``key`` for profile ``name``; returns the profile (with where it went)."""
|
|
208
|
+
key = key.strip()
|
|
209
|
+
if not key:
|
|
210
|
+
raise CredentialError("empty key")
|
|
211
|
+
storage = "file"
|
|
212
|
+
kr = self.keyring if use_keyring else None
|
|
213
|
+
if kr is not None:
|
|
214
|
+
try:
|
|
215
|
+
kr.set_password(KEYRING_SERVICE, name, key)
|
|
216
|
+
storage = "keyring"
|
|
217
|
+
except Exception: # noqa: BLE001 - locked or unavailable keychain: fall back to the file
|
|
218
|
+
storage = "file"
|
|
219
|
+
creds = self._read_json(CREDENTIALS_FILE, private=True)
|
|
220
|
+
if storage == "file":
|
|
221
|
+
creds[name] = key
|
|
222
|
+
else:
|
|
223
|
+
creds.pop(name, None)
|
|
224
|
+
if creds or (self.dir / CREDENTIALS_FILE).exists():
|
|
225
|
+
self._write_json(CREDENTIALS_FILE, creds, private=True)
|
|
226
|
+
profiles = self.profiles()
|
|
227
|
+
profiles[name] = Profile(name=name, api_url=api_url, sandbox=sandbox, storage=storage,
|
|
228
|
+
key_hint=key_hint(key))
|
|
229
|
+
self._save_profiles(profiles)
|
|
230
|
+
return profiles[name]
|
|
231
|
+
|
|
232
|
+
def key(self, name: str) -> str | None:
|
|
233
|
+
p = self.profile(name)
|
|
234
|
+
if p is None:
|
|
235
|
+
return None
|
|
236
|
+
if p.storage == "keyring":
|
|
237
|
+
kr = self.keyring
|
|
238
|
+
if kr is None:
|
|
239
|
+
raise CredentialError(f"profile {name!r} keeps its key in the OS keychain, but no keychain "
|
|
240
|
+
f"is available now (install the keyring package, or log in again)")
|
|
241
|
+
return kr.get_password(KEYRING_SERVICE, name)
|
|
242
|
+
return self._read_json(CREDENTIALS_FILE, private=True).get(name)
|
|
243
|
+
|
|
244
|
+
def delete(self, name: str) -> bool:
|
|
245
|
+
profiles = self.profiles()
|
|
246
|
+
p = profiles.pop(name, None)
|
|
247
|
+
if p is None:
|
|
248
|
+
return False
|
|
249
|
+
if p.storage == "keyring" and self.keyring is not None:
|
|
250
|
+
try:
|
|
251
|
+
self.keyring.delete_password(KEYRING_SERVICE, name)
|
|
252
|
+
except Exception: # noqa: BLE001 - already gone
|
|
253
|
+
pass
|
|
254
|
+
creds = self._read_json(CREDENTIALS_FILE, private=True)
|
|
255
|
+
if name in creds:
|
|
256
|
+
creds.pop(name)
|
|
257
|
+
self._write_json(CREDENTIALS_FILE, creds, private=True)
|
|
258
|
+
self._save_profiles(profiles)
|
|
259
|
+
return True
|