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&times;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}&times;
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(() -&gt; <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}