From 82e63e687dd6e0ea206d816cb942908ddaf3e738 Mon Sep 17 00:00:00 2001 From: Arturo Bernal Date: Sat, 7 Nov 2026 13:45:30 +0100 Subject: [PATCH 01/13] JSPWIKI-1310 Add the search of the REST API version 1, described by an OpenAPI file that a test compares with the answers --- .../api/exceptions/ProviderException.java | 11 + jspwiki-main/pom.xml | 6 + .../org/apache/wiki/rest/ApiV1Servlet.java | 181 +++++++++ .../wiki/search/LuceneSearchProvider.java | 2 +- .../org/apache/wiki/rest/openapi.yaml | 128 +++++++ .../apache/wiki/rest/ApiV1ServletTest.java | 344 ++++++++++++++++++ jspwiki-war/src/main/webapp/WEB-INF/web.xml | 11 + pom.xml | 7 + 8 files changed, 689 insertions(+), 1 deletion(-) create mode 100644 jspwiki-main/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java create mode 100644 jspwiki-main/src/main/resources/org/apache/wiki/rest/openapi.yaml create mode 100644 jspwiki-main/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java index 0fda596a5c..86cb06c900 100644 --- a/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java @@ -37,4 +37,15 @@ public ProviderException( final String msg ) { super( msg ); } + /** + * Creates a ProviderException that tells what caused it. + * + * @param msg exception message. + * @param cause the exception that made the provider fail. + * @since 3.0.1 + */ + public ProviderException( final String msg, final Throwable cause ) { + super( msg, cause ); + } + } diff --git a/jspwiki-main/pom.xml b/jspwiki-main/pom.xml index 0e7da25e61..c41711a0ac 100644 --- a/jspwiki-main/pom.xml +++ b/jspwiki-main/pom.xml @@ -212,6 +212,12 @@ test + + org.yaml + snakeyaml + test + + org.hsqldb hsqldb diff --git a/jspwiki-main/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java b/jspwiki-main/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java new file mode 100644 index 0000000000..c3bd319c23 --- /dev/null +++ b/jspwiki-main/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java @@ -0,0 +1,181 @@ +/* + 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. + */ +package org.apache.wiki.rest; + +import com.google.gson.Gson; +import jakarta.servlet.ServletConfig; +import jakarta.servlet.ServletException; +import jakarta.servlet.http.HttpServlet; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; +import org.apache.commons.lang3.StringUtils; +import org.apache.logging.log4j.LogManager; +import org.apache.logging.log4j.Logger; +import org.apache.lucene.queryparser.classic.ParseException; +import org.apache.wiki.api.core.Context; +import org.apache.wiki.api.core.ContextEnum; +import org.apache.wiki.api.core.Engine; +import org.apache.wiki.api.core.Session; +import org.apache.wiki.api.exceptions.ProviderException; +import org.apache.wiki.api.search.SearchResult; +import org.apache.wiki.api.spi.Wiki; +import org.apache.wiki.auth.AuthorizationManager; +import org.apache.wiki.auth.permissions.PagePermission; +import org.apache.wiki.search.SearchManager; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.util.ArrayList; +import java.util.Collection; +import java.util.List; + +/** + * Version 1 of the REST API of the wiki, described by {@code openapi.yaml} in this package. It answers with JSON, also when it fails. + * A caller that is not allowed to read gets 401 if it is anonymous and 403 if it is logged in. + * + * @since 3.0.1 + */ +public class ApiV1Servlet extends HttpServlet { + + private static final long serialVersionUID = 1L; + private static final Logger LOG = LogManager.getLogger( ApiV1Servlet.class ); + private static final Gson GSON = new Gson(); + + /** Number of entries returned when the request does not say how many it wants. */ + static final int DEFAULT_MAX = 20; + + private transient Engine engine; + + /** {@inheritDoc} */ + @Override + public void init( final ServletConfig config ) throws ServletException { + super.init( config ); + engine = Wiki.engine().find( config ); + } + + /** {@inheritDoc} */ + @Override + protected void doGet( final HttpServletRequest req, final HttpServletResponse resp ) throws IOException { + if( "/search".equals( req.getPathInfo() ) ) { + search( req, resp ); + } else { + error( resp, HttpServletResponse.SC_NOT_FOUND, "No such resource." ); + } + } + + private void search( final HttpServletRequest req, final HttpServletResponse resp ) throws IOException { + final Session session = Wiki.session().find( engine, req ); + if( !engine.getManager( AuthorizationManager.class ).checkPermission( session, PagePermission.VIEW ) ) { + denied( resp, session ); + return; + } + final String query = req.getParameter( "query" ); + if( StringUtils.isBlank( query ) ) { + error( resp, HttpServletResponse.SC_BAD_REQUEST, "The parameter query is required." ); + return; + } + final int max = max( req.getParameter( "max" ) ); + if( max < 1 ) { + error( resp, HttpServletResponse.SC_BAD_REQUEST, "The parameter max must be an integer greater than zero." ); + return; + } + + final Context context = Wiki.context().create( engine, req, ContextEnum.PAGE_VIEW.getRequestContext() ); + try { + final Collection< SearchResult > found = engine.getManager( SearchManager.class ).findPages( query, context ); + if( found == null ) { + // The Lucene provider logs a failure of its index, for instance before it is first built, and returns null + error( resp, HttpServletResponse.SC_SERVICE_UNAVAILABLE, "The search index is not available." ); + return; + } + final List< Hit > hits = new ArrayList<>(); + for( final SearchResult result : found ) { + if( hits.size() == max ) { + break; + } + hits.add( new Hit( result.getPage().getName(), result.getScore() ) ); + } + json( resp, HttpServletResponse.SC_OK, hits ); + } catch( final ProviderException e ) { + if( e.getCause() instanceof ParseException ) { + error( resp, HttpServletResponse.SC_BAD_REQUEST, "The parameter query is not a valid query." ); + } else { + LOG.error( "The search for the REST API failed", e ); + error( resp, HttpServletResponse.SC_INTERNAL_SERVER_ERROR, "The search failed." ); + } + } catch( final IOException e ) { + LOG.error( "The search for the REST API failed", e ); + error( resp, HttpServletResponse.SC_INTERNAL_SERVER_ERROR, "The search failed." ); + } + } + + /** Returns the value of the max parameter, the default when it is absent, and 0 when it is not a positive integer. */ + private static int max( final String value ) { + if( value == null ) { + return DEFAULT_MAX; + } + try { + return Math.max( 0, Integer.parseInt( value.trim() ) ); + } catch( final NumberFormatException e ) { + return 0; + } + } + + private static void denied( final HttpServletResponse resp, final Session session ) throws IOException { + if( session.isAuthenticated() ) { + error( resp, HttpServletResponse.SC_FORBIDDEN, "The permission to read is missing." ); + } else { + error( resp, HttpServletResponse.SC_UNAUTHORIZED, "Authentication is required." ); + } + } + + private static void error( final HttpServletResponse resp, final int status, final String message ) throws IOException { + json( resp, status, new Failure( status, message ) ); + } + + private static void json( final HttpServletResponse resp, final int status, final Object body ) throws IOException { + resp.setStatus( status ); + resp.setContentType( "application/json" ); + resp.setCharacterEncoding( StandardCharsets.UTF_8.name() ); + resp.getWriter().write( GSON.toJson( body ) ); + } + + /** An entry of the answer to a search. */ + private static final class Hit { + private final String page; + private final int score; + + Hit( final String page, final int score ) { + this.page = page; + this.score = score; + } + } + + /** The body of every answer that is not a success. */ + private static final class Failure { + private final int status; + private final String message; + + Failure( final int status, final String message ) { + this.status = status; + this.message = message; + } + } + +} diff --git a/jspwiki-main/src/main/java/org/apache/wiki/search/LuceneSearchProvider.java b/jspwiki-main/src/main/java/org/apache/wiki/search/LuceneSearchProvider.java index 45dfc9676b..ac69b8a3b9 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/search/LuceneSearchProvider.java +++ b/jspwiki-main/src/main/java/org/apache/wiki/search/LuceneSearchProvider.java @@ -526,7 +526,7 @@ public Collection< SearchResult > findPages( final String query, final int flags LOG.error( "Failed during lucene search", e ); } catch( final ParseException e ) { LOG.error( "Broken query; cannot parse query: {}", query, e ); - throw new ProviderException( "You have entered a query Lucene cannot process [" + query + "]: " + e.getMessage() ); + throw new ProviderException( "You have entered a query Lucene cannot process [" + query + "]: " + e.getMessage(), e ); } catch( final InvalidTokenOffsetsException e ) { LOG.error( "Tokens are incompatible with provided text ", e ); } diff --git a/jspwiki-main/src/main/resources/org/apache/wiki/rest/openapi.yaml b/jspwiki-main/src/main/resources/org/apache/wiki/rest/openapi.yaml new file mode 100644 index 0000000000..fc418fb642 --- /dev/null +++ b/jspwiki-main/src/main/resources/org/apache/wiki/rest/openapi.yaml @@ -0,0 +1,128 @@ +# 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. + +# Description of the REST API of the wiki, JSPWIKI-1310. A test compares it with the answers of ApiV1Servlet. +openapi: 3.0.3 +info: + title: JSPWiki API + version: 1.0.0 + description: Search of the pages the caller may view. + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +servers: + - url: /api/v1 +security: + - sessionCookie: [] +paths: + /search: + get: + operationId: searchPages + summary: Search the pages the caller may view. + parameters: + - name: query + in: query + required: true + schema: + type: string + minLength: 1 + - $ref: '#/components/parameters/max' + responses: + '200': + description: Matching pages, best match first. Empty when nothing matches. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SearchResult' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '500': + $ref: '#/components/responses/InternalError' + '503': + $ref: '#/components/responses/Unavailable' +components: + securitySchemes: + sessionCookie: + type: apiKey + in: cookie + name: JSESSIONID + parameters: + max: + name: max + in: query + required: false + description: Maximum number of entries to return. + schema: + type: integer + minimum: 1 + default: 20 + schemas: + SearchResult: + type: object + required: [page, score] + properties: + page: + type: string + description: Name of the page. + score: + type: integer + description: Relevance of the page for the query. Higher is better. + Error: + type: object + required: [status, message] + properties: + status: + type: integer + message: + type: string + responses: + BadRequest: + description: A required parameter is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + Unauthorized: + description: The caller is not authenticated and anonymous access is not allowed. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + Forbidden: + description: The caller is authenticated but lacks the permission. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + InternalError: + description: The request could not be served because of an error of the wiki. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + Unavailable: + description: The search index is not available, for instance right after the wiki has started. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' diff --git a/jspwiki-main/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java b/jspwiki-main/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java new file mode 100644 index 0000000000..c34652bd57 --- /dev/null +++ b/jspwiki-main/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java @@ -0,0 +1,344 @@ +/* + 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. + */ +package org.apache.wiki.rest; + +import com.google.gson.Gson; +import com.google.gson.JsonElement; +import com.google.gson.JsonObject; +import jakarta.servlet.ServletConfig; +import jakarta.servlet.ServletContext; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; +import org.apache.wiki.HttpMockFactory; +import org.apache.wiki.TestEngine; +import org.apache.wiki.api.core.Session; +import org.apache.wiki.api.spi.Wiki; +import org.apache.wiki.auth.AuthenticationManager; +import org.apache.wiki.auth.AuthorizationManager; +import org.apache.wiki.auth.Users; +import org.apache.wiki.search.SearchManager; +import org.awaitility.Awaitility; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.mockito.Mockito; +import org.yaml.snakeyaml.Yaml; + +import java.io.InputStream; +import java.io.PrintWriter; +import java.io.StringWriter; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.Map; +import java.util.Properties; + +class ApiV1ServletTest { + + private static final Gson GSON = new Gson(); + private static final Map< String, Object > CONTRACT = contract(); + + private TestEngine engine; + + @AfterEach + void tearDown() { + if( engine != null ) { + engine.stop(); + } + } + + @Test + void searchAnswersWithTheContract() throws Exception { + startEngine( null ); + engine.saveText( "ApiSearchPage", "The dawn of the third age of mankind." ); + engine.saveText( "ApiSearchOther", "Another page about mankind." ); + + final Reply[] reply = new Reply[ 1 ]; + Awaitility.await( "both pages are indexed" ).until( () -> { + reply[ 0 ] = search( null, "query", "mankind" ); + return reply[ 0 ].json().getAsJsonArray().size() == 2; + } ); + + assertMatchesContract( "/search", reply[ 0 ] ); + Assertions.assertEquals( 200, reply[ 0 ].status ); + final JsonObject first = reply[ 0 ].json().getAsJsonArray().get( 0 ).getAsJsonObject(); + Assertions.assertTrue( first.get( "page" ).getAsString().startsWith( "ApiSearch" ) ); + } + + @Test + void searchWithoutMatchesAnswersWithAnEmptyList() throws Exception { + startEngine( null ); + + final Reply reply = search( null, "query", "nothingwillmatchthis" ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 200, reply.status ); + Assertions.assertEquals( 0, reply.json().getAsJsonArray().size() ); + } + + @Test + void searchReturnsAtMostMaxEntries() throws Exception { + startEngine( null ); + engine.saveText( "ApiMaxOne", "common words here" ); + engine.saveText( "ApiMaxTwo", "common words there" ); + Awaitility.await( "both pages are indexed" ).until( () -> search( null, "query", "common" ).json().getAsJsonArray().size() == 2 ); + + final Reply reply = search( null, "query", "common", "max", "1" ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 1, reply.json().getAsJsonArray().size() ); + } + + @Test + void searchWithoutQueryIsABadRequest() throws Exception { + startEngine( null ); + + final Reply reply = search( null ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 400, reply.status ); + } + + @Test + void searchWithAQueryThatCannotBeParsedIsABadRequest() throws Exception { + startEngine( null ); + + final Reply reply = search( null, "query", "\"unbalanced" ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 400, reply.status ); + } + + @Test + void searchWithAMaxThatIsNotAPositiveIntegerIsABadRequest() throws Exception { + startEngine( null ); + + for( final String max : new String[] { "0", "-3", "many", "" } ) { + final Reply reply = search( null, "query", "mankind", "max", max ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 400, reply.status, "max=" + max ); + } + } + + @Test + void searchByAnAnonymousCallerWithoutPermissionIs401( @TempDir final Path dir ) throws Exception { + startEngine( policy( dir, "Authenticated" ) ); + + final Reply reply = search( null, "query", "mankind" ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 401, reply.status ); + } + + @Test + void searchByALoggedInCallerWithoutPermissionIs403( @TempDir final Path dir ) throws Exception { + startEngine( policy( dir, "Admin" ) ); + final HttpServletRequest request = request( "query", "mankind" ); + final Session session = Wiki.session().find( engine, request ); + engine.getManager( AuthenticationManager.class ).login( session, request, Users.JANNE, Users.JANNE_PASS ); + Assertions.assertTrue( session.isAuthenticated() ); + + final Reply reply = call( request ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 403, reply.status ); + } + + @Test + void searchBeforeTheIndexIsBuiltIs503() throws Exception { + startEngine( null, "600" ); + + final Reply reply = search( null, "query", "mankind" ); + + assertMatchesContract( "/search", reply ); + Assertions.assertEquals( 503, reply.status ); + } + + @Test + void anUnknownResourceIs404() throws Exception { + startEngine( null ); + final HttpServletRequest request = request(); + Mockito.doReturn( "/nothing" ).when( request ).getPathInfo(); + + final Reply reply = call( request ); + + Assertions.assertEquals( 404, reply.status ); + Assertions.assertEquals( 404, reply.json().getAsJsonObject().get( "status" ).getAsInt() ); + } + + @Test + void contractDeclaresTheParametersTheServletEnforces() { + final Map< String, Object > get = map( map( map( CONTRACT, "paths" ), "/search" ), "get" ); + final List< Object > parameters = list( get, "parameters" ); + + final Map< String, Object > query = map( parameters.get( 0 ), null ); + Assertions.assertEquals( "query", query.get( "name" ) ); + Assertions.assertEquals( Boolean.TRUE, query.get( "required" ) ); + + final Map< String, Object > max = resolve( parameters.get( 1 ) ); + Assertions.assertEquals( "max", max.get( "name" ) ); + Assertions.assertEquals( ApiV1Servlet.DEFAULT_MAX, map( max, "schema" ).get( "default" ) ); + Assertions.assertEquals( 1, map( max, "schema" ).get( "minimum" ) ); + } + + private void startEngine( final String policy ) { + startEngine( policy, "0" ); + } + + private void startEngine( final String policy, final String initialIndexDelay ) { + final Properties props = TestEngine.getTestProperties(); + props.setProperty( SearchManager.PROP_SEARCHPROVIDER, "LuceneSearchProvider" ); + props.setProperty( "jspwiki.lucene.indexdelay", "0" ); + props.setProperty( "jspwiki.lucene.initialdelay", initialIndexDelay ); + props.setProperty( "jspwiki.workDir", props.getProperty( "jspwiki.workDir" ) + System.currentTimeMillis() ); + props.setProperty( "jspwiki.fileSystemProvider.pageDir", props.getProperty( "jspwiki.fileSystemProvider.pageDir" ) + System.currentTimeMillis() ); + if( policy != null ) { + props.setProperty( AuthorizationManager.POLICY, policy ); + } + engine = TestEngine.build( props ); + } + + /** Writes a policy file that lets only the given role view the pages. */ + private static String policy( final Path dir, final String role ) throws Exception { + final Path file = dir.resolve( "api.policy" ); + Files.write( file, ( "grant principal org.apache.wiki.auth.authorize.Role \"" + role + "\" {\n" + + " permission org.apache.wiki.auth.permissions.PagePermission \"*:*\", \"view\";\n" + + "};\n" ).getBytes( StandardCharsets.UTF_8 ) ); + return file.toAbsolutePath().toString(); + } + + private HttpServletRequest request( final String... parameters ) { + final HttpServletRequest request = HttpMockFactory.createHttpRequest( "/JSPWiki", "/api/v1/search" ); + Mockito.doReturn( "GET" ).when( request ).getMethod(); + Mockito.doReturn( "/search" ).when( request ).getPathInfo(); + for( int i = 0; i < parameters.length; i += 2 ) { + Mockito.doReturn( parameters[ i + 1 ] ).when( request ).getParameter( parameters[ i ] ); + } + return request; + } + + private Reply search( final HttpServletRequest request, final String... parameters ) throws Exception { + return call( request != null ? request : request( parameters ) ); + } + + private Reply call( final HttpServletRequest request ) throws Exception { + // The context is a mock, so the engine that TestEngine stashed in it has to be handed over again + final ServletContext context = engine.getServletContext(); + Mockito.doReturn( engine ).when( context ).getAttribute( "org.apache.wiki.WikiEngine" ); + final ServletConfig config = Mockito.mock( ServletConfig.class ); + Mockito.doReturn( context ).when( config ).getServletContext(); + final ApiV1Servlet servlet = new ApiV1Servlet(); + servlet.init( config ); + + final Reply reply = new Reply(); + final HttpServletResponse response = Mockito.mock( HttpServletResponse.class ); + Mockito.doAnswer( invocation -> reply.status = invocation.getArgument( 0 ) ).when( response ).setStatus( Mockito.anyInt() ); + Mockito.doAnswer( invocation -> reply.contentType = invocation.getArgument( 0 ) ).when( response ).setContentType( Mockito.anyString() ); + Mockito.doReturn( new PrintWriter( reply.body ) ).when( response ).getWriter(); + servlet.service( request, response ); + return reply; + } + + /** Checks the status, the content type and the shape of the body against what the contract declares for the operation. */ + private static void assertMatchesContract( final String path, final Reply reply ) { + final Map< String, Object > responses = map( map( map( map( CONTRACT, "paths" ), path ), "get" ), "responses" ); + final Object declared = responses.get( String.valueOf( reply.status ) ); + Assertions.assertNotNull( declared, "the contract has no response " + reply.status + " for " + path ); + + final Map< String, Object > content = map( resolve( declared ), "content" ); + Assertions.assertTrue( content.containsKey( reply.contentType ), "content type " + reply.contentType + " is not declared" ); + assertMatchesSchema( resolve( map( content, reply.contentType ).get( "schema" ) ), reply.json(), "body" ); + } + + private static void assertMatchesSchema( final Map< String, Object > schema, final JsonElement value, final String where ) { + switch( String.valueOf( schema.get( "type" ) ) ) { + case "array": + Assertions.assertTrue( value.isJsonArray(), where + " must be an array" ); + value.getAsJsonArray().forEach( item -> assertMatchesSchema( resolve( schema.get( "items" ) ), item, where + "[]" ) ); + break; + case "object": + Assertions.assertTrue( value.isJsonObject(), where + " must be an object" ); + final JsonObject object = value.getAsJsonObject(); + for( final Object required : list( schema, "required" ) ) { + Assertions.assertTrue( object.has( required.toString() ), where + " lacks " + required ); + } + final Map< String, Object > properties = map( schema, "properties" ); + for( final String name : object.keySet() ) { + Assertions.assertTrue( properties.containsKey( name ), where + "." + name + " is not in the contract" ); + assertMatchesSchema( resolve( properties.get( name ) ), object.get( name ), where + "." + name ); + } + break; + case "string": + Assertions.assertTrue( value.isJsonPrimitive() && value.getAsJsonPrimitive().isString(), where + " must be a string" ); + break; + case "integer": + Assertions.assertTrue( value.isJsonPrimitive() && value.getAsJsonPrimitive().isNumber() + && value.getAsDouble() == Math.rint( value.getAsDouble() ), where + " must be an integer" ); + break; + default: + Assertions.fail( "the test does not know the type of " + where ); + } + } + + private static Map< String, Object > contract() { + try( InputStream in = ApiV1Servlet.class.getResourceAsStream( "openapi.yaml" ) ) { + return new Yaml().load( in ); + } catch( final java.io.IOException e ) { + throw new IllegalStateException( e ); + } + } + + /** Follows a local reference such as #/components/schemas/Error. */ + private static Map< String, Object > resolve( final Object node ) { + Map< String, Object > current = map( node, null ); + while( current.containsKey( "$ref" ) ) { + Object target = CONTRACT; + for( final String part : current.get( "$ref" ).toString().substring( 2 ).split( "/" ) ) { + target = map( target, null ).get( part ); + } + current = map( target, null ); + } + return current; + } + + @SuppressWarnings( "unchecked" ) + private static Map< String, Object > map( final Object node, final String key ) { + return ( Map< String, Object > )( key == null ? node : ( ( Map< String, Object > )node ).get( key ) ); + } + + @SuppressWarnings( "unchecked" ) + private static List< Object > list( final Map< String, Object > node, final String key ) { + return ( List< Object > )node.get( key ); + } + + /** What the servlet wrote to a mock response. */ + private static final class Reply { + int status; + String contentType; + final StringWriter body = new StringWriter(); + + JsonElement json() { + return GSON.fromJson( body.toString(), JsonElement.class ); + } + } + +} diff --git a/jspwiki-war/src/main/webapp/WEB-INF/web.xml b/jspwiki-war/src/main/webapp/WEB-INF/web.xml index 86bf0d69ae..7b3cf9a849 100644 --- a/jspwiki-war/src/main/webapp/WEB-INF/web.xml +++ b/jspwiki-war/src/main/webapp/WEB-INF/web.xml @@ -184,6 +184,12 @@ 1 + + + ApiV1Servlet + org.apache.wiki.rest.ApiV1Servlet + + ATOM @@ -222,6 +228,11 @@ /admin/ajax/* + + ApiV1Servlet + /api/v1/* + + +**2026-11-20 Arturo Bernal (abernal AT apache DOT org)** + +* _3.0.2-git-2_ + +* [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/search` is the first endpoint of a versioned REST API, described by the OpenAPI file `openapi.yaml` ([PR#589](https://github.com/apache/jspwiki/pull/589)) + **2026-11-19 Arturo Bernal (abernal AT apache DOT org)** * _3.0.2-git-1_ diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/Release.java b/jspwiki-api/src/main/java/org/apache/wiki/api/Release.java index 26cb6a0efa..ad73c8ffa7 100644 --- a/jspwiki-api/src/main/java/org/apache/wiki/api/Release.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/Release.java @@ -69,7 +69,7 @@ public final class Release { *

* If the build identifier is empty, it is not added. */ - public static final String BUILD = "1"; + public static final String BUILD = "2"; /** * This is the generic version string you should use when printing out the version. It is of From 6c49f1e87db2148f3715b154b6f553737de22d49 Mon Sep 17 00:00:00 2001 From: Arturo Bernal Date: Fri, 20 Nov 2026 06:12:49 +0100 Subject: [PATCH 10/13] ChangeLog of JSPWIKI-1310 after the merge of master --- ChangeLog.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index b241271f28..7bc52be8ef 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -21,6 +21,7 @@ under the License. * _3.0.2-git-2_ * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/search` is the first endpoint of a versioned REST API, described by the OpenAPI file `openapi.yaml` ([PR#589](https://github.com/apache/jspwiki/pull/589)) +* [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/search/suggestions` and `GET /api/v1/plugins` are added to the REST API; the suggestions leave out the pages the caller may not view ([PR#590](https://github.com/apache/jspwiki/pull/590)) **2026-11-19 Arturo Bernal (abernal AT apache DOT org)** * _3.0.2-git-1_ @@ -144,8 +145,6 @@ under the License. * [JSPWIKI-530](https://issues.apache.org/jira/browse/JSPWIKI-530): new `LanguagePlugin` that shows the block of its body that matches the `Accept-Language` header of the visitor, based on the code that Ulf Dittmer attached to the issue ([PR#596](https://github.com/apache/jspwiki/pull/596)) * Fix for [JSPWIKI-90](https://issues.apache.org/jira/browse/JSPWIKI-90): the "More..." menu of the default template has an entry to be notified of the changes of the page, or to stop being notified. It posts, with the anti-CSRF token, to the new `Subscribe.jsp`, which needs a logged-in user with an e-mail address in the profile. * Fix for [JSPWIKI-90](https://issues.apache.org/jira/browse/JSPWIKI-90): the editors of the default template have a "Notify me of changes" box, so a user can subscribe to a page while writing it, also when it is a new page. `Edit.jsp` subscribes the user after the save, when the profile has an e-mail address. -* [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/search` is the first endpoint of a versioned REST API, described by the OpenAPI file `openapi.yaml` ([PR#589](https://github.com/apache/jspwiki/pull/589)) -* [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/search/suggestions` and `GET /api/v1/plugins` are added to the REST API; the suggestions leave out the pages the caller may not view ([PR#590](https://github.com/apache/jspwiki/pull/590)) **2026-10-29 Arturo Bernal (abernal AT apache DOT org)** From a86149b0b47b8a68f8e917cc2fed39a76ec3a54a Mon Sep 17 00:00:00 2001 From: Arturo Bernal Date: Fri, 20 Nov 2026 06:34:16 +0100 Subject: [PATCH 11/13] JSPWIKI-1310 Move the REST API to the module jspwiki-rest-api and write its JSON with Jackson --- ChangeLog.md | 1 + jspwiki-bom/pom.xml | 6 + jspwiki-rest-api/pom.xml | 116 ++++++++++++++++++ .../org/apache/wiki/rest/ApiV1Servlet.java | 101 ++++----------- .../org/apache/wiki/rest/openapi.yaml | 0 .../apache/wiki/rest/ApiV1ServletTest.java | 100 ++++++++------- .../src/test/resources/groupdatabase.xml | 35 ++++++ .../src/test/resources/userdatabase.xml | 32 +++++ jspwiki-war/pom.xml | 6 + pom.xml | 1 + 10 files changed, 273 insertions(+), 125 deletions(-) create mode 100644 jspwiki-rest-api/pom.xml rename {jspwiki-main => jspwiki-rest-api}/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java (87%) rename {jspwiki-main => jspwiki-rest-api}/src/main/resources/org/apache/wiki/rest/openapi.yaml (100%) rename {jspwiki-main => jspwiki-rest-api}/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java (87%) create mode 100644 jspwiki-rest-api/src/test/resources/groupdatabase.xml create mode 100644 jspwiki-rest-api/src/test/resources/userdatabase.xml diff --git a/ChangeLog.md b/ChangeLog.md index 45b54ee575..185abdb6d3 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -24,6 +24,7 @@ under the License. * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/search/suggestions` and `GET /api/v1/plugins` are added to the REST API; the suggestions leave out the pages the caller may not view ([PR#590](https://github.com/apache/jspwiki/pull/590)) * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/pages/{name}`, `GET /api/v1/pages/{name}/history` and `GET /api/v1/pages/{name}/attachments` are added to the REST API, to read a page, its versions and its attachments if the caller may view the page * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/pages`, `GET /api/v1/pages/{name}/references` and `GET /api/v1/pages/{name}/html` are added to the REST API, to list the pages in chunks, to read the links of a page and to read a page rendered to HTML +* [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): the REST API is in its own module `jspwiki-rest-api` and writes its JSON with Jackson, which the wiki already uses, and not with Gson **2026-11-19 Arturo Bernal (abernal AT apache DOT org)** * _3.0.2-git-1_ diff --git a/jspwiki-bom/pom.xml b/jspwiki-bom/pom.xml index 2b27e4d5a7..18cc094686 100644 --- a/jspwiki-bom/pom.xml +++ b/jspwiki-bom/pom.xml @@ -97,6 +97,12 @@ ${jspwiki.version} + + org.apache.jspwiki + jspwiki-rest-api + ${jspwiki.version} + + org.apache.jspwiki jspwiki-portable diff --git a/jspwiki-rest-api/pom.xml b/jspwiki-rest-api/pom.xml new file mode 100644 index 0000000000..a0fd5d7723 --- /dev/null +++ b/jspwiki-rest-api/pom.xml @@ -0,0 +1,116 @@ + + + + + + org.apache.jspwiki + jspwiki-builder + 3.0.2-SNAPSHOT + + + jspwiki-rest-api + 4.0.0 + Apache JSPWiki REST API + Version 1 of the REST API of Apache JSPWiki, described by an OpenAPI file + + + + ${project.groupId} + jspwiki-api + ${project.version} + + + + ${project.groupId} + jspwiki-main + ${project.version} + provided + + + + ${project.groupId} + jspwiki-main + ${project.version} + test-jar + test + + + + tools.jackson.core + jackson-databind + + + + org.apache.commons + commons-lang3 + + + + org.apache.lucene + lucene-queryparser + + + + org.apache.logging.log4j + log4j-api + + + + org.apache.logging.log4j + log4j-core + + + + jakarta.servlet + jakarta.servlet-api + provided + + + + org.junit.jupiter + junit-jupiter-api + test + + + + org.junit.jupiter + junit-jupiter-engine + test + + + + org.mockito + mockito-core + test + + + + org.awaitility + awaitility + test + + + + org.yaml + snakeyaml + test + + + diff --git a/jspwiki-main/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java b/jspwiki-rest-api/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java similarity index 87% rename from jspwiki-main/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java rename to jspwiki-rest-api/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java index bcc897fb46..1d92e38ecc 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java +++ b/jspwiki-rest-api/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java @@ -18,7 +18,7 @@ Licensed to the Apache Software Foundation (ASF) under one */ package org.apache.wiki.rest; -import com.google.gson.Gson; +import com.fasterxml.jackson.annotation.JsonInclude; import jakarta.servlet.ServletConfig; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServlet; @@ -48,6 +48,8 @@ Licensed to the Apache Software Foundation (ASF) under one import org.apache.wiki.references.ReferenceManager; import org.apache.wiki.render.RenderingManager; import org.apache.wiki.search.SearchManager; +import tools.jackson.core.JacksonException; +import tools.jackson.databind.json.JsonMapper; import java.io.IOException; import java.nio.charset.StandardCharsets; @@ -69,7 +71,10 @@ public class ApiV1Servlet extends HttpServlet { private static final long serialVersionUID = 1L; private static final Logger LOG = LogManager.getLogger( ApiV1Servlet.class ); - private static final Gson GSON = new Gson(); + /** Leaves out the fields without a value, as the page that has no author. */ + private static final JsonMapper JSON = JsonMapper.builder() + .changeDefaultPropertyInclusion( value -> value.withValueInclusion( JsonInclude.Include.NON_NULL ) ) + .build(); /** Number of entries returned when the request does not say how many it wants. */ static final int DEFAULT_MAX = 20; @@ -297,7 +302,7 @@ private void history( final HttpServletResponse resp, final Page page ) throws I // A page that was put in the page directory by hand has no history, but it still has its current version revisions.add( new Revision( page ) ); } - revisions.sort( Comparator.comparingInt( ( Revision revision ) -> revision.version ).reversed() ); + revisions.sort( Comparator.comparingInt( ( Revision revision ) -> revision.version() ).reversed() ); json( resp, HttpServletResponse.SC_OK, revisions ); } @@ -398,113 +403,61 @@ private static void json( final HttpServletResponse resp, final int status, fina resp.setStatus( status ); resp.setContentType( "application/json" ); resp.setCharacterEncoding( StandardCharsets.UTF_8.name() ); - resp.getWriter().write( GSON.toJson( body ) ); + try { + resp.getWriter().write( JSON.writeValueAsString( body ) ); + } catch( final JacksonException e ) { + // the bodies are built here, so this is a bug and not a failure of the caller + throw new IOException( e ); + } } /** An entry of the answer to a search. */ - private static final class Hit { - private final String page; - private final int score; - - Hit( final String page, final int score ) { - this.page = page; - this.score = score; - } + private record Hit( String page, int score ) { } /** An entry of the list of plugins. */ - private static final class PluginEntry { - private final String displayName; - private final String snip; - - PluginEntry( final String displayName, final String snip ) { - this.displayName = displayName; - this.snip = snip; - } + private record PluginEntry( String displayName, String snip ) { } /** The content of a page. */ - private static final class PageContent { - private final String name; - private final int version; - private final String author; - private final String lastModified; - private final String text; + private record PageContent( String name, int version, String author, String lastModified, String text ) { PageContent( final Page page, final String text ) { - this.name = page.getName(); - this.version = number( page.getVersion() ); - this.author = page.getAuthor(); - this.lastModified = instant( page.getLastModified() ); - this.text = text; + this( page.getName(), number( page.getVersion() ), page.getAuthor(), instant( page.getLastModified() ), text ); } } /** The page rendered to HTML. */ - private static final class Rendered { - private final String name; - private final int version; - private final String html; + private record Rendered( String name, int version, String html ) { Rendered( final Page page, final String html ) { - this.name = page.getName(); - this.version = number( page.getVersion() ); - this.html = html; + this( page.getName(), number( page.getVersion() ), html ); } } /** The links of a page. */ - private static final class References { - private final List< String > referredBy; - private final List< String > refersTo; - - References( final List< String > referredBy, final List< String > refersTo ) { - this.referredBy = referredBy; - this.refersTo = refersTo; - } + private record References( List< String > referredBy, List< String > refersTo ) { } /** An entry of the history of a page. */ - private static final class Revision { - private final int version; - private final String author; - private final String lastModified; - private final String changeNote; + private record Revision( int version, String author, String lastModified, String changeNote ) { Revision( final Page page ) { - this.version = number( page.getVersion() ); - this.author = page.getAuthor(); - this.lastModified = instant( page.getLastModified() ); - this.changeNote = page.getAttribute( Page.CHANGENOTE ); + this( number( page.getVersion() ), page.getAuthor(), instant( page.getLastModified() ), page.getAttribute( Page.CHANGENOTE ) ); } } /** An entry of the list of attachments of a page. */ - private static final class AttachmentEntry { - private final String name; - private final int version; - private final long size; - private final String author; - private final String lastModified; + private record AttachmentEntry( String name, int version, long size, String author, String lastModified ) { AttachmentEntry( final Attachment attachment ) { - this.name = attachment.getFileName(); - this.version = number( attachment.getVersion() ); - this.size = attachment.getSize(); - this.author = attachment.getAuthor(); - this.lastModified = instant( attachment.getLastModified() ); + this( attachment.getFileName(), number( attachment.getVersion() ), attachment.getSize(), attachment.getAuthor(), + instant( attachment.getLastModified() ) ); } } /** The body of every answer that is not a success. */ - private static final class Failure { - private final int status; - private final String message; - - Failure( final int status, final String message ) { - this.status = status; - this.message = message; - } + private record Failure( int status, String message ) { } } diff --git a/jspwiki-main/src/main/resources/org/apache/wiki/rest/openapi.yaml b/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml similarity index 100% rename from jspwiki-main/src/main/resources/org/apache/wiki/rest/openapi.yaml rename to jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml diff --git a/jspwiki-main/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java b/jspwiki-rest-api/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java similarity index 87% rename from jspwiki-main/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java rename to jspwiki-rest-api/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java index 7c69640c25..a549e364d2 100644 --- a/jspwiki-main/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java +++ b/jspwiki-rest-api/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java @@ -18,10 +18,6 @@ Licensed to the Apache Software Foundation (ASF) under one */ package org.apache.wiki.rest; -import com.google.gson.Gson; -import com.google.gson.JsonArray; -import com.google.gson.JsonElement; -import com.google.gson.JsonObject; import jakarta.servlet.ServletConfig; import jakarta.servlet.ServletContext; import jakarta.servlet.http.HttpServletRequest; @@ -44,6 +40,8 @@ Licensed to the Apache Software Foundation (ASF) under one import org.junit.jupiter.api.io.TempDir; import org.mockito.Mockito; import org.yaml.snakeyaml.Yaml; +import tools.jackson.databind.JsonNode; +import tools.jackson.databind.json.JsonMapper; import java.io.ByteArrayInputStream; import java.io.InputStream; @@ -61,7 +59,7 @@ Licensed to the Apache Software Foundation (ASF) under one class ApiV1ServletTest { - private static final Gson GSON = new Gson(); + private static final JsonMapper JSON = JsonMapper.builder().build(); private static final Map< String, Object > CONTRACT = contract(); private TestEngine engine; @@ -82,13 +80,13 @@ void searchAnswersWithTheContract() throws Exception { final Reply[] reply = new Reply[ 1 ]; Awaitility.await( "both pages are indexed" ).ignoreExceptions().until( () -> { reply[ 0 ] = search( null, "query", "mankind" ); - return reply[ 0 ].json().getAsJsonArray().size() == 2; + return reply[ 0 ].json().size() == 2; } ); assertMatchesContract( "/search", reply[ 0 ] ); Assertions.assertEquals( 200, reply[ 0 ].status ); - final JsonObject first = reply[ 0 ].json().getAsJsonArray().get( 0 ).getAsJsonObject(); - Assertions.assertTrue( first.get( "page" ).getAsString().startsWith( "ApiSearch" ) ); + final JsonNode first = reply[ 0 ].json().get( 0 ); + Assertions.assertTrue( first.get( "page" ).asString().startsWith( "ApiSearch" ) ); } @Test @@ -104,7 +102,7 @@ void searchWithoutMatchesAnswersWithAnEmptyList() throws Exception { assertMatchesContract( "/search", reply ); Assertions.assertEquals( 200, reply.status ); - Assertions.assertEquals( 0, reply.json().getAsJsonArray().size() ); + Assertions.assertEquals( 0, reply.json().size() ); } @Test @@ -112,12 +110,12 @@ void searchReturnsAtMostMaxEntries() throws Exception { startEngine( null ); engine.saveText( "ApiMaxOne", "common words here" ); engine.saveText( "ApiMaxTwo", "common words there" ); - Awaitility.await( "both pages are indexed" ).ignoreExceptions().until( () -> search( null, "query", "common" ).json().getAsJsonArray().size() == 2 ); + Awaitility.await( "both pages are indexed" ).ignoreExceptions().until( () -> search( null, "query", "common" ).json().size() == 2 ); final Reply reply = search( null, "query", "common", "max", "1" ); assertMatchesContract( "/search", reply ); - Assertions.assertEquals( 1, reply.json().getAsJsonArray().size() ); + Assertions.assertEquals( 1, reply.json().size() ); } @Test @@ -214,7 +212,7 @@ void suggestionsReturnAtMostMaxEntries() throws Exception { final Reply reply = call( requestTo( "/search/suggestions", "query", "ApiSug", "max", "1" ) ); assertMatchesContract( "/search/suggestions", reply ); - Assertions.assertEquals( 1, reply.json().getAsJsonArray().size() ); + Assertions.assertEquals( 1, reply.json().size() ); } @Test @@ -258,7 +256,7 @@ void pluginsAnswerWithTheContractSortedByDisplayName() throws Exception { assertMatchesContract( "/plugins", reply ); Assertions.assertEquals( 200, reply.status ); final List< String > displayNames = new ArrayList<>(); - reply.json().getAsJsonArray().forEach( entry -> displayNames.add( entry.getAsJsonObject().get( "displayName" ).getAsString() ) ); + reply.json().forEach( entry -> displayNames.add( entry.get( "displayName" ).asString() ) ); Assertions.assertFalse( displayNames.isEmpty(), "the wiki has plugins" ); final List< String > sorted = new ArrayList<>( displayNames ); sorted.sort( null ); @@ -287,7 +285,7 @@ void anUnknownResourceIs404() throws Exception { final Reply reply = call( request ); Assertions.assertEquals( 404, reply.status ); - Assertions.assertEquals( 404, reply.json().getAsJsonObject().get( "status" ).getAsInt() ); + Assertions.assertEquals( 404, reply.json().get( "status" ).asInt() ); } @Test @@ -299,10 +297,10 @@ void pageAnswersWithTheContract() throws Exception { assertMatchesContract( "/pages/{name}", reply ); Assertions.assertEquals( 200, reply.status ); - final JsonObject page = reply.json().getAsJsonObject(); - Assertions.assertEquals( "ApiReadPage", page.get( "name" ).getAsString() ); - Assertions.assertEquals( 1, page.get( "version" ).getAsInt() ); - Assertions.assertTrue( page.get( "text" ).getAsString().contains( "Some *markup* here." ) ); + final JsonNode page = reply.json(); + Assertions.assertEquals( "ApiReadPage", page.get( "name" ).asString() ); + Assertions.assertEquals( 1, page.get( "version" ).asInt() ); + Assertions.assertTrue( page.get( "text" ).asString().contains( "Some *markup* here." ) ); } @Test @@ -315,10 +313,10 @@ void pageInAnOlderVersionAnswersWithThatText() throws Exception { final Reply first = call( requestTo( "/pages/ApiReadVersions", "version", "1" ) ); assertMatchesContract( "/pages/{name}", first ); - Assertions.assertEquals( 2, latest.json().getAsJsonObject().get( "version" ).getAsInt() ); - Assertions.assertTrue( latest.json().getAsJsonObject().get( "text" ).getAsString().contains( "second text" ) ); - Assertions.assertEquals( 1, first.json().getAsJsonObject().get( "version" ).getAsInt() ); - Assertions.assertTrue( first.json().getAsJsonObject().get( "text" ).getAsString().contains( "first text" ) ); + Assertions.assertEquals( 2, latest.json().get( "version" ).asInt() ); + Assertions.assertTrue( latest.json().get( "text" ).asString().contains( "second text" ) ); + Assertions.assertEquals( 1, first.json().get( "version" ).asInt() ); + Assertions.assertTrue( first.json().get( "text" ).asString().contains( "first text" ) ); } @Test @@ -375,7 +373,7 @@ void historyAnswersWithTheVersionsLatestFirst() throws Exception { assertMatchesContract( "/pages/{name}/history", reply ); Assertions.assertEquals( 200, reply.status ); final List< Integer > versions = new ArrayList<>(); - reply.json().getAsJsonArray().forEach( entry -> versions.add( entry.getAsJsonObject().get( "version" ).getAsInt() ) ); + reply.json().forEach( entry -> versions.add( entry.get( "version" ).asInt() ) ); Assertions.assertEquals( List.of( 3, 2, 1 ), versions ); } @@ -389,8 +387,8 @@ void historyOfAPageWithoutOldVersionsListsTheCurrentOne() throws Exception { assertMatchesContract( "/pages/{name}/history", reply ); Assertions.assertEquals( 200, reply.status ); - Assertions.assertEquals( 1, reply.json().getAsJsonArray().size() ); - Assertions.assertEquals( 1, reply.json().getAsJsonArray().get( 0 ).getAsJsonObject().get( "version" ).getAsInt() ); + Assertions.assertEquals( 1, reply.json().size() ); + Assertions.assertEquals( 1, reply.json().get( 0 ).get( "version" ).asInt() ); } @Test @@ -427,11 +425,11 @@ void attachmentsAnswerWithTheContract() throws Exception { assertMatchesContract( "/pages/{name}/attachments", reply ); Assertions.assertEquals( 200, reply.status ); - final JsonArray entries = reply.json().getAsJsonArray(); + final JsonNode entries = reply.json(); Assertions.assertEquals( 2, entries.size() ); - Assertions.assertEquals( "a.txt", entries.get( 0 ).getAsJsonObject().get( "name" ).getAsString() ); - Assertions.assertEquals( 2, entries.get( 0 ).getAsJsonObject().get( "size" ).getAsInt() ); - Assertions.assertEquals( "b.txt", entries.get( 1 ).getAsJsonObject().get( "name" ).getAsString() ); + Assertions.assertEquals( "a.txt", entries.get( 0 ).get( "name" ).asString() ); + Assertions.assertEquals( 2, entries.get( 0 ).get( "size" ).asInt() ); + Assertions.assertEquals( "b.txt", entries.get( 1 ).get( "name" ).asString() ); } @Test @@ -443,7 +441,7 @@ void attachmentsOfAPageWithoutAttachmentsAreAnEmptyList() throws Exception { assertMatchesContract( "/pages/{name}/attachments", reply ); Assertions.assertEquals( 200, reply.status ); - Assertions.assertEquals( 0, reply.json().getAsJsonArray().size() ); + Assertions.assertEquals( 0, reply.json().size() ); } @Test @@ -479,7 +477,7 @@ void pagesListTheNamesSortedAndLeaveOutTheOnesTheCallerMayNotView() throws Excep assertMatchesContract( "/pages", reply ); Assertions.assertEquals( 200, reply.status ); final List< String > names = new ArrayList<>(); - reply.json().getAsJsonArray().forEach( name -> names.add( name.getAsString() ) ); + reply.json().forEach( name -> names.add( name.asString() ) ); Assertions.assertTrue( names.indexOf( "ApiListA" ) >= 0 && names.indexOf( "ApiListA" ) < names.indexOf( "ApiListB" ) ); Assertions.assertFalse( names.contains( "ApiListSecret" ) ); } @@ -491,16 +489,16 @@ void pagesListInChunksWithMaxAndOffset() throws Exception { engine.saveText( "ApiChunkB", "b" ); engine.saveText( "ApiChunkC", "c" ); final List< String > all = new ArrayList<>(); - call( requestTo( "/pages", "max", "1000" ) ).json().getAsJsonArray().forEach( name -> all.add( name.getAsString() ) ); + call( requestTo( "/pages", "max", "1000" ) ).json().forEach( name -> all.add( name.asString() ) ); final Reply second = call( requestTo( "/pages", "max", "2", "offset", "1" ) ); assertMatchesContract( "/pages", second ); final List< String > chunk = new ArrayList<>(); - second.json().getAsJsonArray().forEach( name -> chunk.add( name.getAsString() ) ); + second.json().forEach( name -> chunk.add( name.asString() ) ); Assertions.assertEquals( all.subList( 1, 3 ), chunk ); final Reply beyond = call( requestTo( "/pages", "offset", "100000" ) ); - Assertions.assertEquals( 0, beyond.json().getAsJsonArray().size() ); + Assertions.assertEquals( 0, beyond.json().size() ); } @Test @@ -538,10 +536,10 @@ void referencesListTheLinksInBothDirectionsWithoutTheSecretOnes() throws Excepti assertMatchesContract( "/pages/{name}/references", target ); assertMatchesContract( "/pages/{name}/references", source ); final List< String > referredBy = new ArrayList<>(); - target.json().getAsJsonObject().getAsJsonArray( "referredBy" ).forEach( name -> referredBy.add( name.getAsString() ) ); + target.json().get( "referredBy" ).forEach( name -> referredBy.add( name.asString() ) ); Assertions.assertEquals( List.of( "ApiRefSource" ), referredBy ); final List< String > refersTo = new ArrayList<>(); - source.json().getAsJsonObject().getAsJsonArray( "refersTo" ).forEach( name -> refersTo.add( name.getAsString() ) ); + source.json().get( "refersTo" ).forEach( name -> refersTo.add( name.asString() ) ); Assertions.assertEquals( List.of( "ApiRefNotWritten", "ApiRefTarget" ), refersTo ); } @@ -568,9 +566,9 @@ void htmlAnswersWithThePageRendered() throws Exception { assertMatchesContract( "/pages/{name}/html", reply ); Assertions.assertEquals( 200, reply.status ); - final JsonObject page = reply.json().getAsJsonObject(); - Assertions.assertEquals( "ApiHtmlPage", page.get( "name" ).getAsString() ); - Assertions.assertTrue( page.get( "html" ).getAsString().contains( "bold" ), page.get( "html" ).getAsString() ); + final JsonNode page = reply.json(); + Assertions.assertEquals( "ApiHtmlPage", page.get( "name" ).asString() ); + Assertions.assertTrue( page.get( "html" ).asString().contains( "bold" ), page.get( "html" ).asString() ); } @Test @@ -706,30 +704,30 @@ private static void assertMatchesContract( final String path, final Reply reply assertMatchesSchema( resolve( map( content, reply.contentType ).get( "schema" ) ), reply.json(), "body" ); } - private static void assertMatchesSchema( final Map< String, Object > schema, final JsonElement value, final String where ) { + private static void assertMatchesSchema( final Map< String, Object > schema, final JsonNode value, final String where ) { switch( String.valueOf( schema.get( "type" ) ) ) { case "array": - Assertions.assertTrue( value.isJsonArray(), where + " must be an array" ); - value.getAsJsonArray().forEach( item -> assertMatchesSchema( resolve( schema.get( "items" ) ), item, where + "[]" ) ); + Assertions.assertTrue( value.isArray(), where + " must be an array" ); + value.forEach( item -> assertMatchesSchema( resolve( schema.get( "items" ) ), item, where + "[]" ) ); break; case "object": - Assertions.assertTrue( value.isJsonObject(), where + " must be an object" ); - final JsonObject object = value.getAsJsonObject(); + Assertions.assertTrue( value.isObject(), where + " must be an object" ); + final JsonNode object = value; for( final Object required : list( schema, "required" ) ) { Assertions.assertTrue( object.has( required.toString() ), where + " lacks " + required ); } final Map< String, Object > properties = map( schema, "properties" ); - for( final String name : object.keySet() ) { + for( final String name : object.propertyNames() ) { Assertions.assertTrue( properties.containsKey( name ), where + "." + name + " is not in the contract" ); assertMatchesSchema( resolve( properties.get( name ) ), object.get( name ), where + "." + name ); } break; case "string": - Assertions.assertTrue( value.isJsonPrimitive() && value.getAsJsonPrimitive().isString(), where + " must be a string" ); + Assertions.assertTrue( value.isString(), where + " must be a string" ); break; case "integer": - Assertions.assertTrue( value.isJsonPrimitive() && value.getAsJsonPrimitive().isNumber() - && value.getAsDouble() == Math.rint( value.getAsDouble() ), where + " must be an integer" ); + Assertions.assertTrue( value.isNumber() + && value.asDouble() == Math.rint( value.asDouble() ), where + " must be an integer" ); break; default: Assertions.fail( "the test does not know the type of " + where ); @@ -769,7 +767,7 @@ private static List< Object > list( final Map< String, Object > node, final Stri private static Set< String > names( final Reply reply ) { final Set< String > names = new HashSet<>(); - reply.json().getAsJsonArray().forEach( name -> names.add( name.getAsString() ) ); + reply.json().forEach( name -> names.add( name.asString() ) ); return names; } @@ -779,8 +777,8 @@ private static final class Reply { String contentType; final StringWriter body = new StringWriter(); - JsonElement json() { - return GSON.fromJson( body.toString(), JsonElement.class ); + JsonNode json() { + return JSON.readTree( body.toString() ); } } diff --git a/jspwiki-rest-api/src/test/resources/groupdatabase.xml b/jspwiki-rest-api/src/test/resources/groupdatabase.xml new file mode 100644 index 0000000000..0166d16ff8 --- /dev/null +++ b/jspwiki-rest-api/src/test/resources/groupdatabase.xml @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/jspwiki-rest-api/src/test/resources/userdatabase.xml b/jspwiki-rest-api/src/test/resources/userdatabase.xml new file mode 100644 index 0000000000..5d095f88d1 --- /dev/null +++ b/jspwiki-rest-api/src/test/resources/userdatabase.xml @@ -0,0 +1,32 @@ + + + + + + rO0ABXNyABFqYXZhLnV0aWwuSGFzaE1hcAUH2sHDFmDRAwACRgAKbG9hZEZhY3RvckkACXRocmVzaG9sZHhwP0AAAAAAAAx3CAAAABAAAAACdAAKYXR0cmlidXRlMXQAEXNvbWUgcmFuZG9tIHZhbHVldAAKYXR0cmlidXRlMnQADWFub3RoZXIgdmFsdWV4 + + + + + + + + + diff --git a/jspwiki-war/pom.xml b/jspwiki-war/pom.xml index 2c0ec67cf8..ab65a3e02a 100644 --- a/jspwiki-war/pom.xml +++ b/jspwiki-war/pom.xml @@ -49,6 +49,12 @@ ${project.version} + + ${project.groupId} + jspwiki-rest-api + ${project.version} + + ${project.groupId} jspwiki-210-adapters diff --git a/pom.xml b/pom.xml index 583e82d074..604c83c1d0 100644 --- a/pom.xml +++ b/pom.xml @@ -148,6 +148,7 @@ jspwiki-wysiwyg jspwiki-main jspwiki-markdown + jspwiki-rest-api jspwiki-tika-searchprovider jspwiki-kendra-searchprovider jspwiki-plugins From 330e8e7c244f062030a998748561d04072f22bbe Mon Sep 17 00:00:00 2001 From: Arturo Bernal Date: Sat, 21 Nov 2026 10:59:00 +0100 Subject: [PATCH 12/13] JSPWIKI-1310 Group the operations of openapi.yaml with tags and reword a description that broke the JAX-RS generator --- ChangeLog.md | 1 + .../org/apache/wiki/rest/openapi.yaml | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/ChangeLog.md b/ChangeLog.md index 185abdb6d3..6bde3cd93d 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -25,6 +25,7 @@ under the License. * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/pages/{name}`, `GET /api/v1/pages/{name}/history` and `GET /api/v1/pages/{name}/attachments` are added to the REST API, to read a page, its versions and its attachments if the caller may view the page * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/pages`, `GET /api/v1/pages/{name}/references` and `GET /api/v1/pages/{name}/html` are added to the REST API, to list the pages in chunks, to read the links of a page and to read a page rendered to HTML * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): the REST API is in its own module `jspwiki-rest-api` and writes its JSON with Jackson, which the wiki already uses, and not with Gson +* [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): the operations of `openapi.yaml` are grouped with the tags Search, Plugins and Pages, so that code generators such as openapi-generator make one class per tag, and a description that made the generator for JAX-RS interfaces write code that does not compile is reworded. A client and the JAX-RS interfaces generated with openapi-generator 7.27.0 compile, and the client reads the responses of a running wiki. **2026-11-19 Arturo Bernal (abernal AT apache DOT org)** * _3.0.2-git-1_ diff --git a/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml b/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml index 41deaedebd..fddf495bb3 100644 --- a/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml +++ b/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml @@ -28,10 +28,18 @@ servers: - url: /api/v1 security: - sessionCookie: [] +tags: + - name: Search + description: Finding pages by text or by the start of their name. + - name: Plugins + description: The plugins the wiki offers. + - name: Pages + description: Reading pages, their history, attachments and references. paths: /search: get: operationId: searchPages + tags: [Search] summary: Search the pages the caller may view. parameters: - name: query @@ -63,6 +71,7 @@ paths: /search/suggestions: get: operationId: suggestPages + tags: [Search] summary: Suggest the names of the pages that start with the given text and that the caller may view. parameters: - name: query @@ -90,6 +99,7 @@ paths: /plugins: get: operationId: listPlugins + tags: [Plugins] summary: List the plugins discovered by the wiki, sorted by display name for the locale of the request. responses: '200': @@ -107,6 +117,7 @@ paths: /pages: get: operationId: listPages + tags: [Pages] summary: List the names of the pages the caller may view, sorted by name. parameters: - $ref: '#/components/parameters/max' @@ -138,6 +149,7 @@ paths: /pages/{name}: get: operationId: getPage + tags: [Pages] summary: Read a page the caller may view, in the latest version or in the one asked for. parameters: - $ref: '#/components/parameters/name' @@ -168,6 +180,7 @@ paths: /pages/{name}/history: get: operationId: getPageHistory + tags: [Pages] summary: List the versions of a page the caller may view, the latest first. parameters: - $ref: '#/components/parameters/name' @@ -193,6 +206,7 @@ paths: /pages/{name}/attachments: get: operationId: listPageAttachments + tags: [Pages] summary: List the attachments of a page the caller may view, sorted by name. parameters: - $ref: '#/components/parameters/name' @@ -218,6 +232,7 @@ paths: /pages/{name}/references: get: operationId: getPageReferences + tags: [Pages] summary: List the pages that link to a page and the pages it links to, leaving out the ones the caller may not view. parameters: - $ref: '#/components/parameters/name' @@ -239,6 +254,7 @@ paths: /pages/{name}/html: get: operationId: getPageHtml + tags: [Pages] summary: Read a page rendered to HTML, as the wiki shows it to the caller. parameters: - $ref: '#/components/parameters/name' @@ -277,7 +293,7 @@ components: name: name in: path required: true - description: Name of the page. A name with "..", a backslash or a control character is not valid. + description: Name of the page. A name with two dots in a row, a backslash or a control character is not valid. schema: type: string minLength: 1 From e7c4f016e297b424f0c0ca2225bf903cd85de083 Mon Sep 17 00:00:00 2001 From: Arturo Bernal Date: Sat, 21 Nov 2026 13:23:16 +0100 Subject: [PATCH 13/13] JSPWIKI-1310 Add the download of the content of an attachment to the REST API --- ChangeLog.md | 1 + .../wiki/attachment/AttachmentServlet.java | 2 +- .../org/apache/wiki/rest/ApiV1Servlet.java | 56 ++++++- .../org/apache/wiki/rest/openapi.yaml | 40 +++++ .../apache/wiki/rest/ApiV1ServletTest.java | 145 ++++++++++++++++++ 5 files changed, 237 insertions(+), 7 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 6bde3cd93d..8f647ec43c 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -26,6 +26,7 @@ under the License. * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/pages`, `GET /api/v1/pages/{name}/references` and `GET /api/v1/pages/{name}/html` are added to the REST API, to list the pages in chunks, to read the links of a page and to read a page rendered to HTML * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): the REST API is in its own module `jspwiki-rest-api` and writes its JSON with Jackson, which the wiki already uses, and not with Gson * [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): the operations of `openapi.yaml` are grouped with the tags Search, Plugins and Pages, so that code generators such as openapi-generator make one class per tag, and a description that made the generator for JAX-RS interfaces write code that does not compile is reworded. A client and the JAX-RS interfaces generated with openapi-generator 7.27.0 compile, and the client reads the responses of a running wiki. +* [JSPWIKI-1310](https://issues.apache.org/jira/browse/JSPWIKI-1310): `GET /api/v1/pages/{name}/attachments/{file}` is added to the REST API, to download the content of an attachment of a page the caller may view, as a download and never as a page of the wiki. `AttachmentServlet.encodeFileName` is public, so that the API writes the file name in the header the same way. **2026-11-19 Arturo Bernal (abernal AT apache DOT org)** * _3.0.2-git-1_ diff --git a/jspwiki-main/src/main/java/org/apache/wiki/attachment/AttachmentServlet.java b/jspwiki-main/src/main/java/org/apache/wiki/attachment/AttachmentServlet.java index 70d6be0dae..40ae509f1d 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/attachment/AttachmentServlet.java +++ b/jspwiki-main/src/main/java/org/apache/wiki/attachment/AttachmentServlet.java @@ -324,7 +324,7 @@ String getContentDisposition( final Attachment att, final String mimetype ) { * @return The rest of the header value: the file name, the closing quote and the terminating semicolon. * @since 3.0.1 */ - static String encodeFileName( final String fileName ) { + public static String encodeFileName( final String fileName ) { boolean plain = true; final StringBuilder fallback = new StringBuilder( fileName.length() ); for( int i = 0; i < fileName.length(); i++ ) { diff --git a/jspwiki-rest-api/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java b/jspwiki-rest-api/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java index 1d92e38ecc..8e5d756bfe 100644 --- a/jspwiki-rest-api/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java +++ b/jspwiki-rest-api/src/main/java/org/apache/wiki/rest/ApiV1Servlet.java @@ -41,6 +41,7 @@ Licensed to the Apache Software Foundation (ASF) under one import org.apache.wiki.api.spi.Wiki; import org.apache.wiki.auth.AuthorizationManager; import org.apache.wiki.attachment.AttachmentManager; +import org.apache.wiki.attachment.AttachmentServlet; import org.apache.wiki.auth.permissions.PagePermission; import org.apache.wiki.auth.permissions.PermissionFactory; import org.apache.wiki.pages.PageManager; @@ -52,6 +53,7 @@ Licensed to the Apache Software Foundation (ASF) under one import tools.jackson.databind.json.JsonMapper; import java.io.IOException; +import java.io.InputStream; import java.nio.charset.StandardCharsets; import java.time.Instant; import java.util.ArrayList; @@ -173,16 +175,22 @@ private void plugins( final HttpServletRequest req, final HttpServletResponse re json( resp, HttpServletResponse.SC_OK, entries ); } - /** Serves a page, its history or its attachments. The part of the path before the optional suffix is the page name. */ + /** + * Serves a page, its history, its attachments or the content of one attachment. The part of the path before the optional suffix is + * the page name, and the file name of an attachment follows the last {@code /attachments/}. + */ private void pages( final HttpServletRequest req, final HttpServletResponse resp, final String rest ) throws IOException { - final String suffix = rest.endsWith( HISTORY ) ? HISTORY : rest.endsWith( ATTACHMENTS ) ? ATTACHMENTS + final int download = rest.lastIndexOf( ATTACHMENTS + "/" ); + final String file = download > 0 ? rest.substring( download + ATTACHMENTS.length() + 1 ) : ""; + final boolean content = !file.isEmpty() && file.indexOf( '/' ) < 0; + final String suffix = content ? ATTACHMENTS : rest.endsWith( HISTORY ) ? HISTORY : rest.endsWith( ATTACHMENTS ) ? ATTACHMENTS : rest.endsWith( REFERENCES ) ? REFERENCES : rest.endsWith( HTML ) ? HTML : ""; - final String name = rest.substring( 0, rest.length() - suffix.length() ); + final String name = content ? rest.substring( 0, download ) : rest.substring( 0, rest.length() - suffix.length() ); if( name.isEmpty() ) { error( resp, HttpServletResponse.SC_NOT_FOUND, "No such resource." ); return; } - if( !plausible( name ) ) { + if( !plausible( name ) || content && !plausible( file ) ) { error( resp, HttpServletResponse.SC_BAD_REQUEST, "The name of the page is not valid." ); return; } @@ -195,15 +203,18 @@ private void pages( final HttpServletRequest req, final HttpServletResponse resp denied( resp, session ); return; } - final int version = suffix.isEmpty() || HTML.equals( suffix ) ? version( req, resp ) : WikiProvider.LATEST_VERSION; + // The version parameter is the one of the page, except for the content of an attachment, where it is the one of the attachment + final int version = suffix.isEmpty() || HTML.equals( suffix ) || content ? version( req, resp ) : WikiProvider.LATEST_VERSION; if( version == 0 ) { return; } try { - final Page page = engine.getManager( PageManager.class ).getPageInfo( name, version ); + final Page page = engine.getManager( PageManager.class ).getPageInfo( name, content ? WikiProvider.LATEST_VERSION : version ); if( page == null ) { error( resp, HttpServletResponse.SC_NOT_FOUND, "The page does not exist." ); + } else if( content ) { + content( req, resp, session, page, file, version ); } else if( HISTORY.equals( suffix ) ) { history( resp, page ); } else if( ATTACHMENTS.equals( suffix ) ) { @@ -314,6 +325,39 @@ private void attachments( final HttpServletResponse resp, final Page page ) thro json( resp, HttpServletResponse.SC_OK, entries ); } + /** + * Sends the content of an attachment. It is always sent as a download and never as a page of the wiki, because what the users upload + * can be a page with script, and this servlet answers on the origin of the wiki. + */ + private void content( final HttpServletRequest req, final HttpServletResponse resp, final Session session, final Page page, + final String file, final int version ) throws ProviderException, IOException { + final AttachmentManager manager = engine.getManager( AttachmentManager.class ); + final Attachment attachment = manager.getAttachmentInfo( page.getName() + "/" + file, version ); + if( attachment == null ) { + error( resp, HttpServletResponse.SC_NOT_FOUND, "The attachment does not exist." ); + return; + } + if( !engine.getManager( AuthorizationManager.class ).checkPermission( session, PermissionFactory.getPagePermission( attachment, PagePermission.VIEW_ACTION ) ) ) { + denied( resp, session ); + return; + } + + final String type = getServletContext().getMimeType( attachment.getFileName().toLowerCase( Locale.ROOT ) ); + resp.setStatus( HttpServletResponse.SC_OK ); + resp.setContentType( type == null ? "application/octet-stream" : type ); + resp.setHeader( "Content-Disposition", "attachment; filename=\"" + AttachmentServlet.encodeFileName( attachment.getFileName() ) ); + resp.setHeader( "X-Content-Type-Options", "nosniff" ); + if( attachment.getLastModified() != null ) { + resp.setDateHeader( "Last-Modified", attachment.getLastModified().getTime() ); + } + if( attachment.getSize() >= 0 ) { + resp.setContentLengthLong( attachment.getSize() ); + } + try( InputStream in = manager.getAttachmentStream( Wiki.context().create( engine, req, attachment ), attachment ) ) { + in.transferTo( resp.getOutputStream() ); + } + } + /** * Tells whether the text can be the name of a page. The providers encode the names they turn into files, so this is only an extra * barrier before a name that comes from the caller reaches them: no parent directory, no backslash and no control character. diff --git a/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml b/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml index fddf495bb3..330b03f3ff 100644 --- a/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml +++ b/jspwiki-rest-api/src/main/resources/org/apache/wiki/rest/openapi.yaml @@ -229,6 +229,46 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' + /pages/{name}/attachments/{file}: + get: + operationId: getPageAttachment + tags: [Pages] + summary: Download the content of an attachment of a page the caller may view. + description: The content is always sent as a download, with the header Content-Disposition set to attachment, and never as a page of the wiki. Its type is the one the server knows for the extension of the file, and application/octet-stream when it knows none. + parameters: + - $ref: '#/components/parameters/name' + - name: file + in: path + required: true + description: File name of the attachment. + schema: + type: string + minLength: 1 + - name: version + in: query + required: false + description: Version of the attachment. The latest version when absent. + schema: + type: integer + minimum: 1 + responses: + '200': + description: The content of the attachment. + content: + '*/*': + schema: + type: string + format: binary + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalError' /pages/{name}/references: get: operationId: getPageReferences diff --git a/jspwiki-rest-api/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java b/jspwiki-rest-api/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java index a549e364d2..1d38f78409 100644 --- a/jspwiki-rest-api/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java +++ b/jspwiki-rest-api/src/test/java/org/apache/wiki/rest/ApiV1ServletTest.java @@ -20,6 +20,8 @@ Licensed to the Apache Software Foundation (ASF) under one import jakarta.servlet.ServletConfig; import jakarta.servlet.ServletContext; +import jakarta.servlet.ServletOutputStream; +import jakarta.servlet.WriteListener; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse; import org.apache.wiki.HttpMockFactory; @@ -44,6 +46,7 @@ Licensed to the Apache Software Foundation (ASF) under one import tools.jackson.databind.json.JsonMapper; import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; import java.io.InputStream; import java.io.PrintWriter; import java.io.StringWriter; @@ -51,6 +54,7 @@ Licensed to the Apache Software Foundation (ASF) under one import java.nio.file.Files; import java.nio.file.Path; import java.util.ArrayList; +import java.util.HashMap; import java.util.HashSet; import java.util.List; import java.util.Map; @@ -465,6 +469,125 @@ void attachmentsOfAPageThatDoesNotExistAre404() throws Exception { Assertions.assertEquals( 404, reply.status ); } + private void store( final String page, final String file, final String content ) throws Exception { + final Attachment attachment = Wiki.contents().attachment( engine, page, file ); + engine.getManager( AttachmentManager.class ).storeAttachment( attachment, new ByteArrayInputStream( content.getBytes( StandardCharsets.UTF_8 ) ) ); + } + + @Test + void anAttachmentIsDownloadedWithItsContentAndTypeAsADownload() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownload", "text" ); + store( "ApiDownload", "b.txt", "hello" ); + Mockito.doReturn( "text/plain" ).when( engine.getServletContext() ).getMimeType( "b.txt" ); + + final Reply reply = call( requestTo( "/pages/ApiDownload/attachments/b.txt" ) ); + + Assertions.assertEquals( 200, reply.status ); + Assertions.assertEquals( "text/plain", reply.contentType ); + Assertions.assertEquals( "hello", reply.bytes.toString( StandardCharsets.UTF_8 ) ); + Assertions.assertEquals( 5, reply.length ); + Assertions.assertEquals( "attachment; filename=\"b.txt\";", reply.headers.get( "Content-Disposition" ) ); + Assertions.assertEquals( "nosniff", reply.headers.get( "X-Content-Type-Options" ) ); + } + + @Test + void anAttachmentOfAnUnknownTypeIsSentAsOctetStream() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownloadType", "text" ); + store( "ApiDownloadType", "data.zzzz", "1234" ); + + final Reply reply = call( requestTo( "/pages/ApiDownloadType/attachments/data.zzzz" ) ); + + Assertions.assertEquals( 200, reply.status ); + Assertions.assertEquals( "application/octet-stream", reply.contentType ); + } + + @Test + void aWebPageAsAttachmentIsNeverSentInline() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownloadHtml", "text" ); + store( "ApiDownloadHtml", "x.html", "" ); + Mockito.doReturn( "text/html" ).when( engine.getServletContext() ).getMimeType( "x.html" ); + + final Reply reply = call( requestTo( "/pages/ApiDownloadHtml/attachments/x.html" ) ); + + Assertions.assertEquals( 200, reply.status ); + Assertions.assertTrue( reply.headers.get( "Content-Disposition" ).startsWith( "attachment;" ), reply.headers.toString() ); + Assertions.assertEquals( "nosniff", reply.headers.get( "X-Content-Type-Options" ) ); + } + + @Test + void aVersionOfAnAttachmentCanBeDownloaded() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownloadVersions", "text" ); + store( "ApiDownloadVersions", "v.txt", "first" ); + store( "ApiDownloadVersions", "v.txt", "second" ); + + final Reply latest = call( requestTo( "/pages/ApiDownloadVersions/attachments/v.txt" ) ); + final Reply first = call( requestTo( "/pages/ApiDownloadVersions/attachments/v.txt", "version", "1" ) ); + + Assertions.assertEquals( "second", latest.bytes.toString( StandardCharsets.UTF_8 ) ); + Assertions.assertEquals( "first", first.bytes.toString( StandardCharsets.UTF_8 ) ); + } + + @Test + void anAttachmentThatDoesNotExistIs404() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownloadMissing", "text" ); + + final Reply reply = call( requestTo( "/pages/ApiDownloadMissing/attachments/none.txt" ) ); + + assertMatchesContract( "/pages/{name}/attachments/{file}", reply ); + Assertions.assertEquals( 404, reply.status ); + } + + @Test + void anAttachmentOfAPageThatDoesNotExistIs404() throws Exception { + startEngine( null ); + + final Reply reply = call( requestTo( "/pages/ApiDownloadNoPage/attachments/a.txt" ) ); + + assertMatchesContract( "/pages/{name}/attachments/{file}", reply ); + Assertions.assertEquals( 404, reply.status ); + } + + @Test + void anAttachmentOfAPageTheCallerMayNotViewIs401AndItsContentIsNotSent() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownloadSecret", "[{ALLOW view Admin}] secret" ); + store( "ApiDownloadSecret", "s.txt", "secret content" ); + + final Reply reply = call( requestTo( "/pages/ApiDownloadSecret/attachments/s.txt" ) ); + + assertMatchesContract( "/pages/{name}/attachments/{file}", reply ); + Assertions.assertEquals( 401, reply.status ); + Assertions.assertEquals( 0, reply.bytes.size() ); + } + + @Test + void aFileNameThatLeavesTheDirectoryIs400() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownloadDots", "text" ); + + final Reply reply = call( requestTo( "/pages/ApiDownloadDots/attachments/..", "version", "1" ) ); + + assertMatchesContract( "/pages/{name}/attachments/{file}", reply ); + Assertions.assertEquals( 400, reply.status ); + } + + @Test + void aVersionThatIsNotANumberIs400() throws Exception { + startEngine( null ); + engine.saveText( "ApiDownloadBadVersion", "text" ); + store( "ApiDownloadBadVersion", "a.txt", "a" ); + + final Reply reply = call( requestTo( "/pages/ApiDownloadBadVersion/attachments/a.txt", "version", "x" ) ); + + assertMatchesContract( "/pages/{name}/attachments/{file}", reply ); + Assertions.assertEquals( 400, reply.status ); + } + @Test void pagesListTheNamesSortedAndLeaveOutTheOnesTheCallerMayNotView() throws Exception { startEngine( null ); @@ -689,6 +812,25 @@ private Reply call( final HttpServletRequest request ) throws Exception { Mockito.doAnswer( invocation -> reply.status = invocation.getArgument( 0 ) ).when( response ).setStatus( Mockito.anyInt() ); Mockito.doAnswer( invocation -> reply.contentType = invocation.getArgument( 0 ) ).when( response ).setContentType( Mockito.anyString() ); Mockito.doReturn( new PrintWriter( reply.body ) ).when( response ).getWriter(); + Mockito.doReturn( new ServletOutputStream() { + @Override + public void write( final int b ) { + reply.bytes.write( b ); + } + + @Override + public boolean isReady() { + return true; + } + + @Override + public void setWriteListener( final WriteListener listener ) { + // writes never block here + } + } ).when( response ).getOutputStream(); + Mockito.doAnswer( invocation -> reply.headers.put( invocation.getArgument( 0 ), invocation.getArgument( 1 ) ) ) + .when( response ).setHeader( Mockito.anyString(), Mockito.anyString() ); + Mockito.doAnswer( invocation -> reply.length = invocation.getArgument( 0 ) ).when( response ).setContentLengthLong( Mockito.anyLong() ); servlet.service( request, response ); return reply; } @@ -775,7 +917,10 @@ private static Set< String > names( final Reply reply ) { private static final class Reply { int status; String contentType; + long length = -1; final StringWriter body = new StringWriter(); + final ByteArrayOutputStream bytes = new ByteArrayOutputStream(); + final Map< String, String > headers = new HashMap<>(); JsonNode json() { return JSON.readTree( body.toString() );