Copilot commented on code in PR #13383: URL: https://github.com/apache/trafficserver/pull/13383#discussion_r3582496988
########## include/ts/ts.h: ########## @@ -1585,10 +1585,19 @@ TSReturnCode TSHttpSsnClientFdGet(TSHttpSsn ssnp, int *fdp); /* TS-1008 END */ /** Change packet firewall mark for the client side connection - * - @note The change takes effect immediately - @return TS_SUCCESS if the client connection was modified + Sets the entire client-side packet firewall mark to @a mark; the whole mark is replaced. @a mark + is interpreted as a 32-bit unsigned bit pattern. + + @note The firewall mark is only honored on platforms whose OS supports it, specifically Linux via + @c SO_MARK. On platforms without @c SO_MARK support the call still returns TS_SUCCESS when a + client connection is present, but setting the mark has no effect at the OS layer (it is a safe + no-op). + + @note The change takes effect immediately on the live client connection + + @return TS_SUCCESS if the client connection was modified, TS_ERROR if there is no client + connection to modify Review Comment: The return-value documentation currently implies TS_SUCCESS means the client connection was actually modified, but the implementation always returns TS_SUCCESS once a client NetVConnection exists and does not propagate setsockopt(SO_MARK) failure (e.g. insufficient CAP_NET_ADMIN/CAP_NET_RAW). This can mislead plugin authors on Linux where SO_MARK exists but applying it fails; please adjust the wording to describe the current semantics (TS_ERROR only when there is no client connection) and explicitly note that OS-layer application failures are not reported. ########## doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst: ########## @@ -32,11 +32,24 @@ Synopsis Description =========== -Change packet firewall :arg:`mark` for the client side connection. +Change the packet firewall :arg:`mark` for the client side connection. The +entire firewall mark is replaced with :arg:`mark`, which is interpreted as a +32-bit unsigned bit pattern. + +Returns :const:`TS_SUCCESS` when the client connection was modified, and +:const:`TS_ERROR` when there is no client connection to modify. + +.. note:: + + The firewall mark is only honored on platforms whose OS supports it, + specifically Linux via ``SO_MARK``. On platforms without ``SO_MARK`` support + the call still returns :const:`TS_SUCCESS` when a client connection is + present, but setting the mark has no effect at the OS layer (it is a safe + no-op). Review Comment: This doc states TS_SUCCESS is returned when the client connection was modified, but the current implementation does not surface failure from the underlying setsockopt(SO_MARK) call (e.g. due to missing CAP_NET_ADMIN/CAP_NET_RAW). To avoid documenting behavior that isn’t guaranteed, describe TS_SUCCESS as "attempted" when a client connection is present and note that OS-layer failures are not reported. ########## tests/gold_tests/pluginTest/client_packet_mark/client_packet_mark.test.py: ########## @@ -0,0 +1,104 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import socket + +Test.Summary = ''' +Verify TSHttpTxnClientPacketMarkSet sets the client-side firewall mark to the +supplied value, using a test plugin that reads the applied mark back off the +client socket. +''' + + +def _can_set_so_mark() -> bool: + """Probe whether SO_MARK can actually be set on this host. + + Setting SO_MARK is Linux-only and requires CAP_NET_ADMIN or CAP_NET_RAW. + On any host that lacks the capability (or the platform), setsockopt raises, + and the applied value would be unobservable -- so the test is skipped + rather than failed. + """ + if not hasattr(socket, "SO_MARK"): + return False + try: + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe: + probe.setsockopt(socket.SOL_SOCKET, socket.SO_MARK, 0x1) + return True + except (OSError, PermissionError): + return False + + +Test.SkipUnless( + Condition.IsPlatform("linux"), + Condition(_can_set_so_mark, "Setting SO_MARK requires Linux with CAP_NET_ADMIN", True), Review Comment: The SkipUnless message mentions only CAP_NET_ADMIN, but the docstring above correctly notes that setting SO_MARK may require CAP_NET_ADMIN or CAP_NET_RAW. Updating the message will make skip output less confusing on hosts where CAP_NET_RAW is the enabling capability. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
