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 java.io.*; 020import java.util.*; 021 022import org.apache.juneau.http.*; 023import org.apache.juneau.rest.server.*; 024 025/** 026 * Mixin interface that serves the terminal bytes and raw endpoints, plus this module's own JS and CSS. 027 * 028 * <p> 029 * The one abstract method is the application's resolver, which is where authorization lives: an unknown id and a 030 * forbidden id both answer {@code 404}. Ids match {@code ^[A-Za-z0-9_-]{1,128}$}; anything else answers {@code 400} 031 * before the resolver runs. The mixin adds no auth of its own; the host resource's guards apply. 032 * 033 * <p> 034 * Step events are not served here: pair the terminal with {@code TerminalViewMixin} over the same id. 035 * 036 * <h2 class='section'>Example:</h2> 037 * <p class='bjava'> 038 * <ja>@Rest</ja> 039 * <jk>public class</jk> RunsResource <jk>extends</jk> BasicRestServlet <jk>implements</jk> TerminalMixin, TerminalViewMixin { 040 * <ja>@Override</ja> 041 * <jk>public</jk> Optional<TerminalSource> terminalSource(String <jv>id</jv>, RestRequest <jv>req</jv>) { 042 * <jk>return</jk> <jf>runs</jf>.find(<jv>id</jv>).map(Run::terminal); 043 * } 044 * } 045 * </p> 046 */ 047public interface TerminalMixin { 048 049 /** The URL path prefix of the terminal endpoints (relative to the host mount). */ 050 String TERMINAL_PREFIX = "/juneau-terminal"; 051 052 /** The URL path template of the bytes endpoint. */ 053 String BYTES_PATH = TERMINAL_PREFIX + "/{id}/bytes"; 054 055 /** The URL path template of the raw download. */ 056 String RAW_PATH = TERMINAL_PREFIX + "/{id}/raw"; 057 058 /** The URL path of the terminal runtime. */ 059 String JS_PATH = "/juneau-terminal.js"; 060 061 /** The URL path of the terminal stylesheet. */ 062 String CSS_PATH = "/juneau-terminal.css"; 063 064 /** The {@code WebJarResolver} asset id of the xterm.js UMD bundle. */ 065 String XTERM_JS_ASSET = "org.webjars.npm:xterm__xterm:xterm__xterm/{version}/lib/xterm.js"; 066 067 /** The {@code WebJarResolver} asset id of the xterm.js stylesheet. */ 068 String XTERM_CSS_ASSET = "org.webjars.npm:xterm__xterm:xterm__xterm/{version}/css/xterm.css"; 069 070 /** 071 * Resolves the source for a terminal id, applying the application's own access rules. 072 * 073 * @param id The id from the URL path (already checked against the grammar). 074 * @param req The in-flight request. 075 * @return The source, or empty when the id is unknown or the caller may not read it. 076 */ 077 Optional<TerminalSource> terminalSource(String id, RestRequest req); 078 079 /** 080 * The access rules applied to the bytes and raw endpoints before the source is resolved. 081 * 082 * <p> 083 * A caller that may not watch the id is answered {@code 404}, the same as an unknown id. The caller handed to the 084 * rules is the request's principal and request attributes. Override to share one {@link TerminalAccess} with the 085 * bus input path; the default admits every caller and leaves the decision to 086 * {@link #terminalSource(String, RestRequest)}. 087 * 088 * @return The access rules. Never <jk>null</jk>. 089 */ 090 default TerminalAccess terminalAccess() { 091 return (caller, id) -> true; 092 } 093 094 /** 095 * [GET /juneau-terminal/{id}/bytes] — raw bytes from an offset. 096 * 097 * @param id The terminal id. 098 * @param req The request. 099 * @param res The response. 100 * @throws IOException If the response could not be written. 101 */ 102 @RestGet(path=BYTES_PATH, summary="Terminal bytes", swagger=@OpSwagger(ignore=true)) 103 default void terminalBytes(@Path("id") String id, RestRequest req, RestResponse res) throws IOException { 104 TerminalEndpoints.bytes(permitted(TerminalEndpoints.checkId(id), req), req, res); 105 } 106 107 /** 108 * [GET /juneau-terminal/{id}/raw] — the whole log as an attachment. 109 * 110 * @param id The terminal id. 111 * @param req The request. 112 * @param res The response. 113 * @throws IOException If the response could not be written. 114 */ 115 @RestGet(path=RAW_PATH, summary="Terminal raw log", swagger=@OpSwagger(ignore=true)) 116 default void terminalRaw(@Path("id") String id, RestRequest req, RestResponse res) throws IOException { 117 TerminalEndpoints.raw(permitted(TerminalEndpoints.checkId(id), req), id, res); 118 } 119 120 /** 121 * Resolves the source for an id once {@link #terminalAccess()} allows the caller to watch it. 122 * 123 * @param id The checked terminal id. 124 * @param req The request. 125 * @return The source, or empty when the caller is denied or the id is unknown. 126 */ 127 private Optional<TerminalSource> permitted(String id, RestRequest req) { 128 var caller = TerminalEndpoints.caller(req); 129 return terminalAccess().canWatch(caller, id) ? terminalSource(id, req) : Optional.empty(); 130 } 131 132 /** 133 * [GET /juneau-terminal.js] — the terminal runtime. 134 * 135 * @return The script. 136 */ 137 @RestGet(path=JS_PATH, summary="Juneau terminal runtime", swagger=@OpSwagger(ignore=true)) 138 default HttpResource terminalScript() { 139 return TerminalEndpoints.script(); 140 } 141 142 /** 143 * [GET /juneau-terminal.css] — the terminal stylesheet. 144 * 145 * @return The stylesheet. 146 */ 147 @RestGet(path=CSS_PATH, summary="Juneau terminal stylesheet", swagger=@OpSwagger(ignore=true)) 148 default HttpResource terminalStylesheet() { 149 return TerminalEndpoints.stylesheet(); 150 } 151 152 /** 153 * The absolute URL of a terminal asset; the toolkit pack resolver for the {@code terminal} pack. 154 * 155 * @param req The current request. 156 * @param path {@link #JS_PATH} or {@link #CSS_PATH}. 157 * @return The asset URL with its cache-buster. 158 */ 159 static String terminalAssetUrl(RestRequest req, String path) { 160 return TerminalEndpoints.terminalAssetUrl(req, path); 161 } 162}