diff --git a/internal-api/src/main/java/datadog/trace/util/AsciiSequence.java b/internal-api/src/main/java/datadog/trace/util/AsciiSequence.java new file mode 100644 index 00000000000..c1d98e241eb --- /dev/null +++ b/internal-api/src/main/java/datadog/trace/util/AsciiSequence.java @@ -0,0 +1,80 @@ +package datadog.trace.util; + +import static java.nio.charset.StandardCharsets.ISO_8859_1; + +import datadog.trace.api.function.NoEscape; + +/** + * A {@code CharSequence} that is a view of ASCII bytes in an array, without copying or decoding + * them: the byte counterpart of {@link SubSequence}. Lets a value that arrived as bytes (a fetched + * Kafka header, for instance) be parsed in place, for example with {@code LongStringUtils}' range + * parsers, instead of being decoded into a {@code String} first. + * + *

{@link NoEscape}: a view shares its array, and for a fetched record that array is the whole + * fetch buffer, so keeping a view anywhere longer-lived than the call that received it (a field, a + * span, a context, a cache) pins all of it. A value that must be kept is copied with {@link + * #toString()}. + * + *

Only ASCII bytes can be viewed as chars one-for-one, so {@link #ofAscii} returns null when a + * byte isn't, and the caller decodes those bytes as before. Equality is identity, as for any {@code + * CharSequence} that doesn't promise otherwise; compare contents with {@code toString()} or a + * content comparison. + */ +@NoEscape +public final class AsciiSequence implements CharSequence { + private final byte[] bytes; + private final int offset; + private final int length; + + private AsciiSequence(byte[] bytes, int offset, int length) { + this.bytes = bytes; + this.offset = offset; + this.length = length; + } + + /** + * A view of {@code bytes[offset, offset + length)} if every one of those bytes is ASCII, else + * null. + */ + public static AsciiSequence ofAscii(byte[] bytes, int offset, int length) { + if (offset < 0 || length < 0 || offset > bytes.length - length) { + throw new IndexOutOfBoundsException( + "offset " + offset + ", length " + length + ", array length " + bytes.length); + } + for (int i = offset, end = offset + length; i < end; i++) { + if (bytes[i] < 0) { + return null; // not ASCII + } + } + return new AsciiSequence(bytes, offset, length); + } + + @Override + public int length() { + return length; + } + + @Override + public char charAt(int index) { + if (index < 0 || index >= length) { + throw new IndexOutOfBoundsException("index " + index + ", length " + length); + } + return (char) bytes[offset + index]; + } + + /** A view of chars {@code [start, end)} of this one, sharing its array. */ + @Override + public AsciiSequence subSequence(int start, int end) { + if (start < 0 || end > length || start > end) { + throw new IndexOutOfBoundsException("start " + start + ", end " + end + ", length " + length); + } + return new AsciiSequence(bytes, offset + start, end - start); + } + + /** A copy, as a {@code String}: what to keep when the value must outlive the call. */ + @Override + public String toString() { + // the bytes are ASCII, so ISO-8859-1 decodes them one-for-one in a single copy + return new String(bytes, offset, length, ISO_8859_1); + } +} diff --git a/internal-api/src/test/java/datadog/trace/util/AsciiSequenceTest.java b/internal-api/src/test/java/datadog/trace/util/AsciiSequenceTest.java new file mode 100644 index 00000000000..f0fedb38943 --- /dev/null +++ b/internal-api/src/test/java/datadog/trace/util/AsciiSequenceTest.java @@ -0,0 +1,80 @@ +package datadog.trace.util; + +import static java.nio.charset.StandardCharsets.UTF_8; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import datadog.trace.api.internal.util.LongStringUtils; +import org.junit.jupiter.api.Test; + +class AsciiSequenceTest { + + /** {@code value}'s UTF-8 bytes inside a larger array, at offset 3. */ + private static byte[] embedded(String value) { + byte[] inner = value.getBytes(UTF_8); + byte[] outer = new byte[inner.length + 5]; + outer[0] = 'x'; + System.arraycopy(inner, 0, outer, 3, inner.length); + outer[outer.length - 1] = 'y'; + return outer; + } + + @Test + void viewsAsciiBytesAsChars() { + String value = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"; + byte[] bytes = embedded(value); + AsciiSequence view = AsciiSequence.ofAscii(bytes, 3, value.length()); + assertNotNull(view); + assertEquals(value.length(), view.length()); + for (int i = 0; i < value.length(); i++) { + assertEquals(value.charAt(i), view.charAt(i)); + } + assertEquals(value, view.toString()); + assertEquals("0af7651916cd43dd8448eb211c80319c", view.subSequence(3, 35).toString()); + assertEquals("", view.subSequence(5, 5).toString()); + } + + @Test + void nonAsciiBytesAreNotViewed() { + byte[] bytes = embedded("café"); + assertNull(AsciiSequence.ofAscii(bytes, 3, "café".getBytes(UTF_8).length)); + // the ASCII part alone is fine + assertNotNull(AsciiSequence.ofAscii(bytes, 3, 3)); + } + + @Test + void toStringCopies() { + byte[] bytes = embedded("12345"); + AsciiSequence view = AsciiSequence.ofAscii(bytes, 3, 5); + String copy = view.toString(); + bytes[3] = '9'; + assertEquals("12345", copy); + assertEquals('9', view.charAt(0)); // a view sees its array + } + + @Test + void parsesInPlace() { + byte[] bytes = embedded("8264894952805660751"); + AsciiSequence view = AsciiSequence.ofAscii(bytes, 3, 19); + assertEquals( + LongStringUtils.parseUnsignedLong("8264894952805660751"), + LongStringUtils.parseUnsignedLong(view, 0, view.length())); + } + + @Test + void checksBounds() { + byte[] bytes = embedded("abc"); + assertThrows(IndexOutOfBoundsException.class, () -> AsciiSequence.ofAscii(bytes, -1, 1)); + assertThrows(IndexOutOfBoundsException.class, () -> AsciiSequence.ofAscii(bytes, 0, -1)); + assertThrows( + IndexOutOfBoundsException.class, () -> AsciiSequence.ofAscii(bytes, 6, bytes.length)); + AsciiSequence view = AsciiSequence.ofAscii(bytes, 3, 3); + assertThrows(IndexOutOfBoundsException.class, () -> view.charAt(3)); + assertThrows(IndexOutOfBoundsException.class, () -> view.charAt(-1)); + assertThrows(IndexOutOfBoundsException.class, () -> view.subSequence(2, 1)); + assertThrows(IndexOutOfBoundsException.class, () -> view.subSequence(0, 4)); + assertThrows(IndexOutOfBoundsException.class, () -> view.subSequence(-1, 2)); + } +}