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 

13COAP_PORT = 5683 

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

15 

16COAPS_PORT = 5684 

17 

18MCAST_IPV4_ALLCOAPNODES = "224.0.1.187" 

19MCAST_IPV6_LINKLOCAL_ALLNODES = "ff02::1" 

20MCAST_IPV6_LINKLOCAL_ALLCOAPNODES = "ff02::fd" 

21MCAST_IPV6_SITELOCAL_ALLNODES = "ff05::1" 

22MCAST_IPV6_SITELOCAL_ALLCOAPNODES = "ff05::fd" 

23MCAST_ALL = ( 

24 MCAST_IPV4_ALLCOAPNODES, 

25 MCAST_IPV6_LINKLOCAL_ALLNODES, 

26 MCAST_IPV6_LINKLOCAL_ALLCOAPNODES, 

27 MCAST_IPV6_SITELOCAL_ALLNODES, 

28 MCAST_IPV6_SITELOCAL_ALLCOAPNODES, 

29) 

30 

31MAX_REGULAR_BLOCK_SIZE_EXP = 6 

32 

33 

34class TransportTuning: 

35 """Base parameters that guide CoAP transport behaviors 

36 

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

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

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

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

41 especially with respect to congestion control. 

42 """ 

43 

44 # +-------------------+---------------+ 

45 # | name | default value | 

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

47 # | ACK_TIMEOUT | 2 seconds | 

48 # | ACK_RANDOM_FACTOR | 1.5 | 

49 # | MAX_RETRANSMIT | 4 | 

50 # | NSTART | 1 | 

51 # | DEFAULT_LEISURE | 5 seconds | 

52 # | PROBING_RATE | 1 Byte/second | 

53 # +-------------------+---------------+ 

54 

55 ACK_TIMEOUT = 2.0 

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

57 confirmable message. The inter-transmission time doubles 

58 for each retransmission.""" 

59 

60 ACK_RANDOM_FACTOR = 1.5 

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

62 

63 MAX_RETRANSMIT = 4 

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

65 non-multicast endpoints before the infrastructure assumes no 

66 acknowledgement will be received.""" 

67 

68 NSTART = 1 

69 """Maximum number of simultaneous outstanding interactions 

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

71 

72 # +-------------------+---------------+ 

73 # | name | default value | 

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

75 # | MAX_TRANSMIT_SPAN | 45 s | 

76 # | MAX_TRANSMIT_WAIT | 93 s | 

77 # | MAX_LATENCY | 100 s | 

78 # | PROCESSING_DELAY | 2 s | 

79 # | MAX_RTT | 202 s | 

80 # | EXCHANGE_LIFETIME | 247 s | 

81 # | NON_LIFETIME | 145 s | 

82 # +-------------------+---------------+ 

83 

84 @property 

85 def MAX_TRANSMIT_SPAN(self): 

86 """Maximum time from the first transmission 

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

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

89 

90 @property 

91 def MAX_TRANSMIT_WAIT(self): 

92 """Maximum time from the first transmission 

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

94 receiving an acknowledgement or reset.""" 

95 return ( 

96 self.ACK_TIMEOUT 

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

98 * self.ACK_RANDOM_FACTOR 

99 ) 

100 

101 MAX_LATENCY = 100.0 

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

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

104 

105 @property 

106 def PROCESSING_DELAY(self): 

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

108 confirmable message into an acknowledgement.""" 

109 return self.ACK_TIMEOUT 

110 

111 @property 

112 def MAX_RTT(self): 

113 """Maximum round-trip time.""" 

114 return 2 * self.MAX_LATENCY + self.PROCESSING_DELAY 

115 

116 @property 

117 def EXCHANGE_LIFETIME(self): 

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

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

120 message exchange can be purged""" 

121 return self.MAX_TRANSMIT_SPAN + self.MAX_RTT 

122 

123 DEFAULT_BLOCK_SIZE_EXP = MAX_REGULAR_BLOCK_SIZE_EXP 

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

125 

126 EMPTY_ACK_DELAY = 0.1 

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

128 

129 @property 

130 def REQUEST_TIMEOUT(self): 

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

132 It is not defined by IETF documents. 

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

134 (for example 10 seconds) 

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

136 warnings.warn( 

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

138 DeprecationWarning, 

139 stacklevel=2, 

140 ) 

141 return self.MAX_TRANSMIT_WAIT 

142 

143 DEFAULT_LEISURE = 5 

144 

145 @property 

146 def MULTICAST_REQUEST_TIMEOUT(self): 

147 warnings.warn( 

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

149 DeprecationWarning, 

150 stacklevel=2, 

151 ) 

152 return self.REQUEST_TIMEOUT + self.DEFAULT_LEISURE 

153 

154 OBSERVATION_RESET_TIME = 128 

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

156 

157 This number is not explicitly named in RFC7641. 

158 """ 

159 

160 reliability: bool | None = None 

161 """Should the message be sent reliably? 

162 

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

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

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

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

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

168 

169 

170_default_transport_tuning = TransportTuning() 

171 

172 

173class Reliable(TransportTuning): 

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

175 

176 reliability = True 

177 

178 

179class Unreliable(TransportTuning): 

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

181 

182 reliability = False 

183 

184 

185def __getattr__(name): 

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

187 warnings.warn( 

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

189 DeprecationWarning, 

190 stacklevel=2, 

191 ) 

192 return getattr(_default_transport_tuning, name) 

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

194 

195 

196SHUTDOWN_TIMEOUT = 3 

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

198 

199__all__ = [ 

200 k for k in dir() if not k.startswith("_") and k not in ("warnings", "string") 

201]