Coverage for kilter/service/options.py: 100.00%

1# Copyright 2023-2024 Dominik Sekotill <dom.sekotill@kodo.org.uk> 

2# 

3# This Source Code Form is subject to the terms of the Mozilla Public 

4# License, v. 2.0. If a copy of the MPL was not distributed with this 

5# file, You can obtain one at http://mozilla.org/MPL/2.0/. 

6 

7""" 

8Filter decorators for marking the requested protocol options and actions used 

9""" 

10 

11from __future__ import annotations (empty)

12 

13from collections import defaultdict (empty)

14from enum import Flag (empty)

15from enum import auto (empty)

16from typing import Callable (empty)

17from typing import Literal (empty)

18from typing import NamedTuple (empty)

19 

20from kilter.protocol.messages import ActionFlags (empty)

21from kilter.protocol.messages import ProtocolFlags (empty)

22from kilter.protocol.messages import Stage (empty)

23 

24from .session import Filter (empty)

25 

26__all__ = [ (empty)

27 "CanRespond", "NEVER", "BEFORE", "DURING", "AFTER", 

28 "responds_to_connect", "examine_helo", 

29 "examine_sender", "examine_recipients", 

30 "examine_headers", "examine_body", 

31 "get_flags", "modify_flags", 

32 "get_macros", "request_macros", 

33] 

34 

35Decorator = Callable[[Filter], Filter] (empty)

36SIZES = Literal[ProtocolFlags.NONE, ProtocolFlags.MDS_256K, ProtocolFlags.MDS_1M] (empty)

37 

38FLAGS_ATTRIBUTE = "filter_flags" (empty)

39MACRO_ATTRIBUTE = "filter_macros" (empty)

40 

41DEFAULT_UNSET = \ (empty)

42 ProtocolFlags.NO_CONNECT | ProtocolFlags.NO_HELO | \ 

43 ProtocolFlags.NO_SENDER | ProtocolFlags.NO_RECIPIENT | \ 

44 ProtocolFlags.NO_DATA | ProtocolFlags.NO_BODY | \ 

45 ProtocolFlags.NO_HEADERS | ProtocolFlags.NO_END_OF_HEADERS | \ 

46 ProtocolFlags.NO_UNKNOWN | \ 

47 ProtocolFlags.NR_CONNECT | ProtocolFlags.NR_HELO | \ 

48 ProtocolFlags.NR_SENDER | ProtocolFlags.NR_RECIPIENT | \ 

49 ProtocolFlags.NR_DATA | ProtocolFlags.NR_BODY | \ 

50 ProtocolFlags.NR_HEADER | ProtocolFlags.NR_END_OF_HEADERS | \ 

51 ProtocolFlags.NR_UNKNOWN 

52 

53 

54class CanRespond(Flag): (empty)

55 """ 

56 Flags for fine indication of which stages during message sending a filter may respond at 

57 

58 Used with `examine_headers()` and `examine_body()` to further refine which stages during 

59 message header and body transfer will synchronously block until a response of some kind 

60 is received. 

61 """ 

62 

63 NEVER = 0 (empty)

64 BEFORE = auto() (empty)

65 DURING = auto() (empty)

66 AFTER = auto() (empty)

67 ALL = BEFORE|DURING|AFTER (empty)

68 

69 

70NEVER = CanRespond.NEVER (empty)

71BEFORE = CanRespond.BEFORE (empty)

72DURING = CanRespond.DURING (empty)

73AFTER = CanRespond.AFTER (empty)

74 

75 

76class FlagsTuple(NamedTuple): (empty)

77 

78 unset_options: ProtocolFlags = ProtocolFlags.NONE (empty)

79 set_options: ProtocolFlags = ProtocolFlags.NONE (empty)

80 set_actions: ActionFlags = ActionFlags.NONE (empty)

81 

82 

83def modify_flags( (empty)

84 set_options: ProtocolFlags = ProtocolFlags.NONE, 

85 unset_options: ProtocolFlags = ProtocolFlags.NONE, 

86 set_actions: ActionFlags = ActionFlags.NONE, 

87) -> Decorator: 

88 """ 

89 Return a decorator that modifies the given flags on a decorated filter 

90 """ 

91 def decorator(filtr: Filter) -> Filter: (empty)

92 _set_flags(filtr, set_options, unset_options, set_actions) (empty)

93 return filtr (empty)

94 return decorator (empty)

95 

96 

97def get_flags(filtr: Filter) -> FlagsTuple: (empty)

98 """ 

99 Return the flags attached to a filter 

100 """ 

101 default = FlagsTuple(unset_options=DEFAULT_UNSET, set_actions=ActionFlags.ALL) (empty)

102 return _get_flags(filtr, default) (empty)

103 

104 

105def _set_flags( (empty)

106 filtr: Filter, 

107 set_options: ProtocolFlags = ProtocolFlags.NONE, 

108 unset_options: ProtocolFlags = ProtocolFlags.NONE, 

109 set_actions: ActionFlags = ActionFlags.NONE, 

110) -> None: 

111 flags = _get_flags(filtr, FlagsTuple()) (empty)

112 flags = FlagsTuple( (empty)

113 flags.unset_options|unset_options, 

114 flags.set_options|set_options, 

115 flags.set_actions|set_actions, 

116 ) 

117 setattr(filtr, FLAGS_ATTRIBUTE, flags) (empty)

118 

119 

120def _get_flags(filtr: Filter, default: FlagsTuple) -> FlagsTuple: (empty)

121 assert isinstance(getattr(filtr, FLAGS_ATTRIBUTE, default), FlagsTuple) (empty)

122 return getattr(filtr, FLAGS_ATTRIBUTE, default) (empty)

123 

124 

125def request_macros(stage: Stage, *names: str) -> Decorator: (empty)

126 """ 

127 Return a decorator that adds the given macro requests to a decorated filter 

128 """ 

129 def decorator(filtr: Filter) -> Filter: (empty)

130 _set_flags(filtr, set_actions=ActionFlags.SETSYMLIST) (empty)

131 macros = get_macros(filtr) (empty)

132 macros[stage].update(names) (empty)

133 return filtr (empty)

134 return decorator (empty)

135 

136 

137def get_macros(filtr: Filter) -> defaultdict[Stage, set[str]]: (empty)

138 """ 

139 Return the requested macros attached to a filter 

140 """ 

141 try: (empty)

142 macros = getattr(filtr, MACRO_ATTRIBUTE) (empty)

143 except AttributeError: (empty)

144 setattr(filtr, MACRO_ATTRIBUTE, (macros := defaultdict(set))) (empty)

145 assert isinstance(macros, defaultdict) (empty)

146 return macros (empty)

147 

148 

149def responds_to_connect() -> Decorator: (empty)

150 """ 

151 Mark a filter as possibly delivering a non-continue response to Connect events 

152 """ 

153 return modify_flags(unset_options=ProtocolFlags.NR_CONNECT) (empty)

154 

155 

156def examine_helo( (empty)

157 can_respond: bool = False, 

158) -> Decorator: 

159 """ 

160 Mark a filter as needing to examine the HELO command 

161 

162 If `can_respond` is `False` the filter runner will attempt to negotiate faster event 

163 delivery by disabling the need to respond to this event. 

164 """ 

165 unset = ProtocolFlags.NO_HELO (empty)

166 if can_respond: (empty)

167 unset |= ProtocolFlags.NR_HELO (empty)

168 return modify_flags(unset_options=unset) (empty)

169 

170 

171def examine_sender( (empty)

172 can_respond: bool = False, 

173 can_replace: bool = False, 

174) -> Decorator: 

175 """ 

176 Mark a filter as needing to examine and optionally replace the RCPT FROM sender 

177 

178 If `can_respond` is `False` the filter runner will attempt to negotiate faster event 

179 delivery by disabling the need to respond to this event. 

180 

181 If `can_replace` is `True` but is not offered by the MTA an exception will be raised 

182 during negotiation and the filter will be disabled. 

183 """ 

184 unset = ProtocolFlags.NO_SENDER (empty)

185 if can_respond: (empty)

186 unset |= ProtocolFlags.NR_SENDER (empty)

187 return modify_flags( (empty)

188 unset_options=unset, 

189 set_actions=ActionFlags.CHANGE_FROM if can_replace else ActionFlags.NONE, 

190 ) 

191 

192 

193def examine_recipients( (empty)

194 can_respond: bool = False, 

195 can_add: bool = False, 

196 can_remove: bool = False, 

197 include_rejected: bool = False, 

198 with_parameters: bool = False, 

199) -> Decorator: 

200 """ 

201 Mark a filter as needing to examine and optionally modify the RCPT TO recipients 

202 

203 If `can_respond` is `False` the filter runner will attempt to negotiate faster event 

204 delivery by disabling the need to respond to this event. 

205 

206 If `include_rejected` is `True` the recipients available to the filter will include any 

207 that the MTA or another filter has already rejected. 

208 

209 The option `with_parameters` enables the use of RFC-1425 [section 6] extensions for 

210 "MAIL" commands (ratified by RFC-5321) when adding recipients. The specific details of 

211 any extension parameters will be dependent on the MTA. 

212 

213 If a requested option or update action is not offered by the MTA an exception will be 

214 raised during negotiation and the filter will be disabled. 

215 """ 

216 unset = ProtocolFlags.NO_RECIPIENT (empty)

217 opts = ProtocolFlags.NONE (empty)

218 acts = ActionFlags.NONE (empty)

219 if can_respond: (empty)

220 unset |= ProtocolFlags.NR_RECIPIENT (empty)

221 if can_add: (empty)

222 acts |= ActionFlags.ADD_RECIPIENT (empty)

223 if can_add and with_parameters: (empty)

224 acts |= ActionFlags.ADD_RECIPIENT_PAR (empty)

225 if can_remove: (empty)

226 acts |= ActionFlags.DELETE_RECIPIENT (empty)

227 if include_rejected: (empty)

228 opts |= ProtocolFlags.REJECTED_RECIPIENT (empty)

229 return modify_flags(unset_options=unset, set_options=opts, set_actions=acts) (empty)

230 

231 

232def examine_headers( (empty)

233 can_respond: bool|CanRespond = False, 

234 can_add: bool = False, 

235 can_modify: bool = False, 

236 leading_space: bool = False, 

237) -> Decorator: 

238 """ 

239 Mark a filter as needing to examine and optionally add or modify message headers 

240 

241 If `can_respond` is `False` the filter runner will attempt to negotiate faster event 

242 delivery by disabling the need to respond to this event. 

243 

244 If `leading_space` is `True` the headers will be delivered without any whitespace 

245 removed from values (i.e. after the separating colon). This is for filters which need 

246 the exact bytes contained in message headers. 

247 

248 If a requested option or update action is not offered by the MTA an exception will be 

249 raised during negotiation and the filter will be disabled. 

250 """ 

251 unset = ProtocolFlags.NO_HEADERS (empty)

252 opts = ProtocolFlags.NONE (empty)

253 acts = ActionFlags.NONE (empty)

254 if isinstance(can_respond, bool): (empty)

255 can_respond = CanRespond.ALL if can_respond else CanRespond.NEVER (empty)

256 if CanRespond.BEFORE in can_respond: (empty)

257 unset |= ProtocolFlags.NO_DATA | ProtocolFlags.NR_DATA (empty)

258 if CanRespond.DURING in can_respond: (empty)

259 unset |= ProtocolFlags.NR_HEADER (empty)

260 if CanRespond.AFTER in can_respond: (empty)

261 unset |= ProtocolFlags.NO_END_OF_HEADERS | ProtocolFlags.NR_END_OF_HEADERS (empty)

262 if can_add: (empty)

263 acts |= ActionFlags.ADD_HEADERS (empty)

264 if can_modify: (empty)

265 acts |= ActionFlags.CHANGE_HEADERS (empty)

266 if leading_space: (empty)

267 opts |= ProtocolFlags.HEADER_LEADING_SPACE (empty)

268 return modify_flags(unset_options=unset, set_options=opts, set_actions=acts) (empty)

269 

270 

271def examine_body( (empty)

272 can_respond: bool|CanRespond = False, 

273 can_replace: bool = False, 

274 data_size: SIZES = ProtocolFlags.NONE, 

275) -> Decorator: 

276 """ 

277 Mark a filter as needing to examine and optionally replace message bodies 

278 

279 If `can_respond` is `False` the filter runner will attempt to negotiate faster event 

280 delivery by disabling the need to respond to this event. 

281 

282 The `data_size` option is a hint, and does not guarantee that the message will be 

283 delivered in blocks of that size. If `ProtocolFlags.NONE` (the default) the MTA's 

284 default will be used. 

285 

286 If `can_replace` is `True` but is not offered by the MTA an exception will be raised 

287 during negotiation and the filter will be disabled. 

288 """ 

289 unset = ProtocolFlags.NO_BODY (empty)

290 if isinstance(can_respond, bool): (empty)

291 can_respond = CanRespond.ALL if can_respond else CanRespond.NEVER (empty)

292 if CanRespond.BEFORE in can_respond: (empty)

293 unset |= ProtocolFlags.NO_END_OF_HEADERS | ProtocolFlags.NR_END_OF_HEADERS (empty)

294 if CanRespond.DURING in can_respond: (empty)

295 unset |= ProtocolFlags.NR_BODY (empty)

296 # CanRespond.AFTER is implicit 

297 return modify_flags( (empty)

298 unset_options=unset, set_options=data_size, 

299 set_actions=ActionFlags.CHANGE_BODY if can_replace else ActionFlags.NONE, 

300 )