001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.terminal.region; 018 019import static org.apache.juneau.commons.utils.Shorts.*; 020import static org.apache.juneau.terminal.report.TerminalViewChecks.*; 021 022import java.io.*; 023import java.nio.*; 024import java.nio.channels.*; 025import java.nio.charset.*; 026import java.nio.file.*; 027import java.nio.file.attribute.*; 028import java.util.*; 029import java.util.concurrent.atomic.*; 030import java.util.function.*; 031import java.util.logging.*; 032 033import org.apache.juneau.marshall.marshaller.Json; 034 035/** 036 * A {@link TerminalSource} that tails one growing log file of raw terminal bytes. 037 * 038 * <p> 039 * <b>Size.</b> The producer's cols×rows come from the sidecar {@code <log>.size}, which holds 040 * {@code {"cols":C,"rows":R}}. While it is missing or malformed the size is {@link #DEFAULT_COLS}× 041 * {@link #DEFAULT_ROWS} and one warning is logged; the first valid read is kept, since the sidecar is written once. 042 * 043 * <p> 044 * <b>Done.</b> The source is done when the {@link Builder#terminal(BooleanSupplier) terminal} supplier says so and 045 * the reader has reached the end. <b>Gone.</b> A log that existed and then disappears answers a {@code gone}, 046 * {@code done}, empty chunk whose {@code next} and {@code end} are the requested offset. 047 * 048 * <p> 049 * <b>Nudges.</b> {@link #nudges(String, TerminalNudgePublisher)} starts a daemon watcher that publishes when the file 050 * grows. A source has no process exit, so it never publishes a {@code done} nudge: the page's polling already sees 051 * {@code done} through the {@link Builder#terminal(BooleanSupplier) terminal} supplier. Call {@link #close()} to stop 052 * the watcher. 053 * 054 * <p> 055 * <b>Path safety.</b> The application supplies the {@link Path}; nothing in a request ever becomes a path. 056 * 057 * <h2 class='section'>Example:</h2> 058 * <p class='bjava'> 059 * FileTerminalSource <jv>src</jv> = FileTerminalSource.<jsm>create</jsm>(<jv>dir</jv>.resolve(<js>"run.log"</js>)) 060 * .terminal(() -> <jv>run</jv>.isFinished()) 061 * .build(); 062 * </p> 063 */ 064public final class FileTerminalSource implements TerminalSource, AutoCloseable { 065 066 /** The width used while the size sidecar is missing or malformed. */ 067 public static final int DEFAULT_COLS = 120; 068 069 /** The height used while the size sidecar is missing or malformed. */ 070 public static final int DEFAULT_ROWS = 40; 071 072 /** How often the nudge thread checks the file size, in milliseconds. */ 073 static final int NUDGE_POLL_MILLIS = 100; 074 075 /** How long {@link #close()} waits for the nudge thread, in milliseconds. */ 076 static final int NUDGE_JOIN_MILLIS = 1000; 077 078 /** The most bytes read from the size sidecar. */ 079 static final int MAX_SIZE_BYTES = 32; 080 081 private static final Logger LOG = Logger.getLogger(FileTerminalSource.class.getName()); 082 083 /** 084 * Builder for {@link FileTerminalSource}. 085 */ 086 public static final class Builder { 087 private final Path file; 088 private BooleanSupplier terminal = () -> false; 089 090 Builder(Path file) { 091 this.file = Objects.requireNonNull(file, "file"); 092 } 093 094 /** 095 * Sets the supplier that reports whether the producer will write no more, called once per read before the 096 * file is sized. 097 * 098 * @param value The supplier. 099 * @return This object. 100 */ 101 public Builder terminal(BooleanSupplier value) { 102 terminal = Objects.requireNonNull(value, "terminal"); 103 return this; 104 } 105 106 /** 107 * Builds the source. 108 * 109 * @return A new source. 110 */ 111 public FileTerminalSource build() { 112 return new FileTerminalSource(this); 113 } 114 } 115 116 private final Path file; 117 private final Path sizeFile; 118 private final BooleanSupplier terminal; 119 private final AtomicReference<int[]> sizeRef = new AtomicReference<>(); 120 private final AtomicReference<Object> fileKey = new AtomicReference<>(); 121 private volatile boolean seen; 122 private volatile boolean warned; 123 124 // Nudges. nudgeThread, nudgeSet and nudgeClosed are guarded by nudgeLock. 125 private final Object nudgeLock = new Object(); 126 private Thread nudgeThread; 127 private boolean nudgeSet; 128 private boolean nudgeClosed; 129 private volatile boolean nudgeStop; 130 131 private FileTerminalSource(Builder b) { 132 file = b.file; 133 sizeFile = file.resolveSibling(file.getFileName() + ".size"); 134 terminal = b.terminal; 135 } 136 137 /** 138 * Creates a builder. 139 * 140 * @param file The log file, supplied by the application. 141 * @return A new builder. 142 */ 143 public static Builder create(Path file) { 144 return new Builder(file); 145 } 146 147 /** 148 * The log file. 149 * 150 * @return The path given to {@link #create(Path)}. 151 */ 152 public Path file() { 153 return file; 154 } 155 156 /** 157 * Reports growth of the file to a publisher. 158 * 159 * <p> 160 * Starts a daemon thread named {@code juneau-terminal-nudge-file-<name>} that checks the file size every 100 ms and 161 * calls the publisher with the new end when it has grown. A file that is missing or has shrunk publishes nothing 162 * and the watcher keeps going. A {@link RuntimeException} thrown by the publisher is logged at {@code FINE} and 163 * otherwise ignored. No {@code done} nudge is ever published, since the source does not know when the producer 164 * finishes; polling covers it. {@link #close()} stops the thread. 165 * 166 * @param terminalId The terminal id passed to the publisher; must be a valid run id. 167 * @param publisher The publisher. 168 * @return This object. 169 * @throws NullPointerException If an argument is <jk>null</jk>. 170 * @throws IllegalArgumentException If the id is not a valid run id. 171 * @throws IllegalStateException If a publisher is already set, or this source has been closed. 172 */ 173 public FileTerminalSource nudges(String terminalId, TerminalNudgePublisher publisher) { 174 Objects.requireNonNull(terminalId, "terminalId"); 175 Objects.requireNonNull(publisher, "publisher"); 176 if (! isRunId(terminalId)) 177 throw iaex("FileTerminalSource nudge id is not a valid run id: '%s'.", terminalId); 178 synchronized (nudgeLock) { 179 if (nudgeClosed) 180 throw new IllegalStateException("FileTerminalSource is closed."); 181 if (nudgeSet) 182 throw new IllegalStateException("FileTerminalSource nudges are already set."); 183 nudgeSet = true; 184 nudgeThread = new Thread(() -> watch(terminalId, publisher), "juneau-terminal-nudge-file-" + file.getFileName()); 185 nudgeThread.setDaemon(true); 186 nudgeThread.start(); 187 } 188 return this; 189 } 190 191 /** The nudge thread: reports file growth until the thread is stopped. */ 192 private void watch(String id, TerminalNudgePublisher publisher) { 193 var last = -1L; 194 while (! nudgeStop) { 195 var size = sizeOrZero(file); 196 if (size > last) { 197 try { 198 publisher.nudge(id, size, false); 199 } catch (RuntimeException e) { 200 LOG.log(Level.FINE, e, () -> "Terminal nudge publisher failed for '" + id + "'."); 201 } 202 last = size; 203 } 204 try { 205 Thread.sleep(NUDGE_POLL_MILLIS); 206 } catch (InterruptedException e) { 207 Thread.currentThread().interrupt(); 208 return; 209 } 210 } 211 } 212 213 private static long sizeOrZero(Path p) { 214 try { 215 return Files.size(p); 216 } catch (IOException e) { 217 return 0; 218 } 219 } 220 221 /** 222 * Stops the nudge thread, if any, and waits up to {@value #NUDGE_JOIN_MILLIS} ms for it. 223 * 224 * <p> 225 * Reads keep working after this; only {@link #nudges(String, TerminalNudgePublisher)} is refused. 226 */ 227 @Override /* AutoCloseable */ 228 public void close() { 229 Thread t; 230 synchronized (nudgeLock) { 231 nudgeClosed = true; 232 nudgeStop = true; 233 t = nudgeThread; 234 } 235 if (t == null) 236 return; 237 t.interrupt(); 238 try { 239 t.join(NUDGE_JOIN_MILLIS); 240 } catch (InterruptedException e) { 241 Thread.currentThread().interrupt(); 242 } 243 if (t.isAlive()) 244 LOG.log(Level.WARNING, () -> "FileTerminalSource nudge thread did not stop for '" + file + "'."); 245 } 246 247 @Override /* TerminalSource */ 248 public TerminalChunk read(long fromOffset, int maxBytes) throws IOException { 249 if (fromOffset < 0) 250 throw iaex("fromOffset must be at least 0; got '%s'.", fromOffset); 251 // Read the flag first: bytes written after this point are simply not done yet, and the next read sees them. 252 var done = terminal.getAsBoolean(); 253 var sz = size(); 254 long end; 255 try { 256 var attrs = Files.readAttributes(file, BasicFileAttributes.class, LinkOption.NOFOLLOW_LINKS); 257 if (! attrs.isRegularFile()) 258 throw new IOException("Terminal log is not a regular file: '" + file + "'."); 259 var key = attrs.fileKey(); 260 if (key != null && ! fileKey.compareAndSet(null, key) && ! key.equals(fileKey.get())) 261 throw new IOException("Terminal log was replaced: '" + file + "'."); 262 end = attrs.size(); 263 } catch (NoSuchFileException e) { 264 if (seen) 265 return gone(fromOffset, sz); 266 return new TerminalChunk(new byte[0], 0, 0, done, sz[0], sz[1], false, false); 267 } 268 seen = true; 269 if (fromOffset >= end) 270 return new TerminalChunk(new byte[0], end, end, done, sz[0], sz[1], false, false); 271 var len = (int)Math.min(Math.max(0, Math.min(maxBytes, MAX_READ_BYTES)), end - fromOffset); 272 var buf = ByteBuffer.allocate(len); 273 try (var ch = FileChannel.open(file, StandardOpenOption.READ, LinkOption.NOFOLLOW_LINKS)) { 274 while (buf.hasRemaining()) { 275 if (ch.read(buf, fromOffset + buf.position()) < 0) 276 break; 277 } 278 } catch (NoSuchFileException e) { 279 return gone(fromOffset, sz); 280 } 281 var bytes = Arrays.copyOf(buf.array(), buf.position()); 282 var next = fromOffset + bytes.length; 283 return new TerminalChunk(bytes, next, end, done && next == end, sz[0], sz[1], false, false); 284 } 285 286 private static TerminalChunk gone(long fromOffset, int[] sz) { 287 return new TerminalChunk(new byte[0], fromOffset, fromOffset, true, sz[0], sz[1], false, true); 288 } 289 290 private int[] size() { 291 var s = sizeRef.get(); 292 if (s != null) 293 return s; 294 s = parseSize(sizeFile); 295 if (s != null) { 296 sizeRef.set(s); 297 return s; 298 } 299 if (! warned) { 300 warned = true; 301 LOG.warning(() -> "Terminal size sidecar '" + sizeFile + "' is missing or malformed; using " + DEFAULT_COLS + "x" + DEFAULT_ROWS + "."); 302 } 303 return new int[] { DEFAULT_COLS, DEFAULT_ROWS }; 304 } 305 306 /** Reads a size sidecar of at most {@value #MAX_SIZE_BYTES} bytes, without following a symlink. */ 307 private static String readCapped(Path p) throws IOException { 308 try (var ch = FileChannel.open(p, StandardOpenOption.READ, LinkOption.NOFOLLOW_LINKS)) { 309 var buf = ByteBuffer.allocate(MAX_SIZE_BYTES + 1); 310 while (buf.hasRemaining() && ch.read(buf) >= 0) { 311 // The condition does the reading; the loop has no body. 312 } 313 if (buf.position() > MAX_SIZE_BYTES) 314 throw new IOException("Size sidecar is over " + MAX_SIZE_BYTES + " bytes: '" + p + "'."); 315 return new String(buf.array(), 0, buf.position(), StandardCharsets.UTF_8); 316 } 317 } 318 319 /** Returns {cols, rows} from a {"cols":C,"rows":R} file, or null when it is missing or malformed. */ 320 @SuppressWarnings({ 321 "java:S1168" // null means the size sidecar is missing or malformed; callers test for it 322 }) 323 static int[] parseSize(Path p) { 324 try { 325 var m = Json.to(readCapped(p), Map.class); 326 if (m.get("cols") instanceof Number c && m.get("rows") instanceof Number r) { 327 var cols = c.doubleValue(); 328 var rows = r.doubleValue(); 329 if (cols == Math.rint(cols) && rows == Math.rint(rows) && cols >= 1 && cols <= 9999 && rows >= 1 && rows <= 9999) 330 return new int[] { (int)cols, (int)rows }; 331 } 332 return null; 333 } catch (Exception e) { 334 return null; 335 } 336 } 337}