Coverage for aiocoap / numbers / constants.py: 91%

1# SPDX-FileCopyrightText: Christian Amsüss and the aiocoap contributors 

2# 

3# SPDX-License-Identifier: MIT 

4 

5"""Constants either defined in the CoAP protocol (often default values for lack 

6of ways to determine eg. the estimated round trip time). Some parameters are 

7invented here for practical purposes of the implementation (eg. 

8DEFAULT_BLOCK_SIZE_EXP, EMPTY_ACK_DELAY).""" 

9 

10import warnings 

11import string 

12 

13from ..util import DeprecationWarning 

14 

15COAP_PORT = 5683 

16"""The IANA-assigned standard port for COAP services.""" 

17 

18COAPS_PORT = 5684 

19 

20MCAST_IPV4_ALLCOAPNODES = "224.0.1.187" 

21MCAST_IPV6_LINKLOCAL_ALLNODES = "ff02::1" 

22MCAST_IPV6_LINKLOCAL_ALLCOAPNODES = "ff02::fd" 

23MCAST_IPV6_SITELOCAL_ALLNODES = "ff05::1" 

24MCAST_IPV6_SITELOCAL_ALLCOAPNODES = "ff05::fd" 

25MCAST_ALL = ( 

26 MCAST_IPV4_ALLCOAPNODES, 

27 MCAST_IPV6_LINKLOCAL_ALLNODES, 

28 MCAST_IPV6_LINKLOCAL_ALLCOAPNODES, 

29 MCAST_IPV6_SITELOCAL_ALLNODES, 

30 MCAST_IPV6_SITELOCAL_ALLCOAPNODES, 

31) 

32 

33MAX_REGULAR_BLOCK_SIZE_EXP = 6 

34 

35 

36class TransportTuning: 

37 """Base parameters that guide CoAP transport behaviors 

38 

39 The values in here are recommended values, often defaults from RFCs. They 

40 can be tuned in subclasses (and then passed into a message as 

41 ``transport_tuning``), although users should be aware that alteing some of 

42 these can cause the library to behave in ways violating the specification, 

43 especially with respect to congestion control. 

44 """ 

45 

46 # +-------------------+---------------+ 

47 # | name | default value | 

48 # +-------------------+---------------+ 

49 # | ACK_TIMEOUT | 2 seconds | 

50 # | ACK_RANDOM_FACTOR | 1.5 | 

51 # | MAX_RETRANSMIT | 4 | 

52 # | NSTART | 1 | 

53 # | DEFAULT_LEISURE | 5 seconds | 

54 # | PROBING_RATE | 1 Byte/second | 

55 # +-------------------+---------------+ 

56 

57 ACK_TIMEOUT = 2.0 

58 """The time, in seconds, to wait for an acknowledgement of a 

59 confirmable message. The inter-transmission time doubles 

60 for each retransmission.""" 

61 

62 ACK_RANDOM_FACTOR = 1.5 

63 """Timeout multiplier for anti-synchronization.""" 

64 

65 MAX_RETRANSMIT = 4 

66 """The number of retransmissions of confirmable messages to 

67 non-multicast endpoints before the infrastructure assumes no 

68 acknowledgement will be received.""" 

69 

70 NSTART = 1 

71 """Maximum number of simultaneous outstanding interactions 

72 that endpoint maintains to a given server (including proxies)""" 

73 

74 # +-------------------+---------------+ 

75 # | name | default value | 

76 # +-------------------+---------------+ 

77 # | MAX_TRANSMIT_SPAN | 45 s | 

78 # | MAX_TRANSMIT_WAIT | 93 s | 

79 # | MAX_LATENCY | 100 s | 

80 # | PROCESSING_DELAY | 2 s | 

81 # | MAX_RTT | 202 s | 

82 # | EXCHANGE_LIFETIME | 247 s | 

83 # | NON_LIFETIME | 145 s | 

84 # +-------------------+---------------+ 

85 

86 @property 

87 def MAX_TRANSMIT_SPAN(self): 

88 """Maximum time from the first transmission 

89 of a confirmable message to its last retransmission.""" 

90 return self.ACK_TIMEOUT * (2**self.MAX_RETRANSMIT - 1) * self.ACK_RANDOM_FACTOR 

91 

92 @property 

93 def MAX_TRANSMIT_WAIT(self): 

94 """Maximum time from the first transmission 

95 of a confirmable message to the time when the sender gives up on 

96 receiving an acknowledgement or reset.""" 

97 return ( 

98 self.ACK_TIMEOUT 

99 * (2 ** (self.MAX_RETRANSMIT + 1) - 1) 

100 * self.ACK_RANDOM_FACTOR 

101 ) 

102 

103 MAX_LATENCY = 100.0 

104 """Maximum time a datagram is expected to take from the start 

105 of its transmission to the completion of its reception.""" 

106 

107 @property 

108 def PROCESSING_DELAY(self): 

109 """ "Time a node takes to turn around a 

110 confirmable message into an acknowledgement.""" 

111 return self.ACK_TIMEOUT 

112 

113 @property 

114 def MAX_RTT(self): 

115 """Maximum round-trip time.""" 

116 return 2 * self.MAX_LATENCY + self.PROCESSING_DELAY 

117 

118 @property 

119 def EXCHANGE_LIFETIME(self): 

120 """time from starting to send a confirmable message to the time when an 

121 acknowledgement is no longer expected, i.e. message layer information about the 

122 message exchange can be purged""" 

123 return self.MAX_TRANSMIT_SPAN + self.MAX_RTT 

124 

125 DEFAULT_BLOCK_SIZE_EXP = MAX_REGULAR_BLOCK_SIZE_EXP 

126 """Default size exponent for blockwise transfers.""" 

127 

128 EMPTY_ACK_DELAY = 0.1 

129 """After this time protocol sends empty ACK, and separate response""" 

130 

131 @property 

132 def REQUEST_TIMEOUT(self): 

133 """Time after which server assumes it won't receive any answer. 

134 It is not defined by IETF documents. 

135 For human-operated devices it might be preferable to set some small value 

136 (for example 10 seconds) 

137 For M2M it's application dependent.""" 

138 warnings.warn( 

139 "parameter is unused; use asyncio mechanisms to time out requests", 

140 DeprecationWarning, 

141 stacklevel=2, 

142 ) 

143 return self.MAX_TRANSMIT_WAIT 

144 

145 DEFAULT_LEISURE = 5 

146 

147 @property 

148 def MULTICAST_REQUEST_TIMEOUT(self): 

149 warnings.warn( 

150 "parameter is unused; use asyncio mechanisms to time out requests", 

151 DeprecationWarning, 

152 stacklevel=2, 

153 ) 

154 return self.REQUEST_TIMEOUT + self.DEFAULT_LEISURE 

155 

156 OBSERVATION_RESET_TIME = 128 

157 """Time in seconds after which the value of the observe field are ignored. 

158 

159 This number is not explicitly named in RFC7641. 

160 """ 

161 

162 reliability: bool | None = None 

163 """Should the message be sent reliably? 

164 

165 The choice is up to the transport as long as this is None; if set, 

166 transports that make a distinction will use reliable (or unreliable for 

167 False) transmission if the protocol allows it for that request. (For 

168 example, it is ignored on multicast requests which can only be NON, and 

169 in an observation, a CON needs to be sent at least once a day).""" 

170 

171 

172_default_transport_tuning = TransportTuning() 

173 

174 

175class Reliable(TransportTuning): 

176 """TransportTuning to prefer reliable transmission (e.g. CON)""" 

177 

178 reliability = True 

179 

180 

181class Unreliable(TransportTuning): 

182 """TransportTuning to prefer unreliable transmission (e.g. NON)""" 

183 

184 reliability = False 

185 

186 

187def __getattr__(name): 

188 if name[0] in string.ascii_uppercase and hasattr(_default_transport_tuning, name): 

189 warnings.warn( 

190 f"{name} is deprecated, use through the message's transport_tuning instead", 

191 DeprecationWarning, 

192 stacklevel=2, 

193 ) 

194 return getattr(_default_transport_tuning, name) 

195 raise AttributeError(f"module {__name__} has no attribute {name}") 

196 

197 

198SHUTDOWN_TIMEOUT = 3 

199"""Maximum time, in seconds, for which the process is kept around during shutdown""" 

200 

201__all__ = [ 

202 k 

203 for k in dir() 

204 if not k.startswith("_") and k not in ("warnings", "string", "DeprecationWarning") 

205]