Request Matching

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;
import java.util.Map;

public interface RequestMatcher {
    /**
     * Determines if the request matches.
     *
     * @param request the HTTP request
     * @return true if the request matches
     */
    boolean matches(HttpServletRequest request);
    
    /**
     * Returns detailed match result with extracted variables.
     *
     * @param request the HTTP request
     * @return the match result
     */
    default MatchResult matcher(HttpServletRequest request) {
        boolean match = matches(request);
        return match ? MatchResult.match() : MatchResult.notMatch();
    }
    
    /**
     * Represents the result of a match operation.
     */
    interface MatchResult {
        boolean isMatch();
        Map<String, String> getVariables();
        
        static MatchResult match();
        static MatchResult match(Map<String, String> variables);
        static MatchResult notMatch();
    }
}

package org.springframework.security.web.util.matcher;

public final class RequestMatchers {
    /**
     * Creates a RequestMatcher that matches if at least one of the given matchers matches.
     * If matchers are empty, the returned matcher never matches.
     *
     * @param matchers the RequestMatchers to use
     * @return the any-of composed RequestMatcher
     * @see OrRequestMatcher
     */
    public static RequestMatcher anyOf(RequestMatcher... matchers);

    /**
     * Creates a RequestMatcher that matches if all the given matchers match.
     * If matchers are empty, the returned matcher always matches.
     *
     * @param matchers the RequestMatchers to use
     * @return the all-of composed RequestMatcher
     * @see AndRequestMatcher
     */
    public static RequestMatcher allOf(RequestMatcher... matchers);

    /**
     * Creates a RequestMatcher that matches if the given matcher does not match.
     *
     * @param matcher the RequestMatcher to invert
     * @return the inverted RequestMatcher
     */
    public static RequestMatcher not(RequestMatcher matcher);
}

package org.springframework.security.web.servlet.util.matcher;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpMethod;
import org.springframework.security.web.util.matcher.RequestMatcher;
import org.springframework.web.util.pattern.PathPattern;
import org.springframework.web.util.pattern.PathPatternParser;

/**
 * Uses PathPattern to match against HTTP requests. Path patterns are relative
 * to the context path and support placeholders and wildcards.
 *
 * @since 6.5
 */
public final class PathPatternRequestMatcher implements RequestMatcher {
    /**
     * Creates a matcher for any HTTP method using default PathPatternParser.
     *
     * @param pattern the path pattern (e.g., "/admin/**", "/users/{id}")
     * @return a PathPatternRequestMatcher
     * @since 7.0
     */
    public static PathPatternRequestMatcher pathPattern(String pattern);

    /**
     * Creates a matcher for a specific HTTP method using default PathPatternParser.
     *
     * @param method the HTTP method, null indicates any method
     * @param pattern the path pattern
     * @return a PathPatternRequestMatcher
     * @since 7.0
     */
    public static PathPatternRequestMatcher pathPattern(HttpMethod method, String pattern);

    /**
     * Creates a builder with default PathPatternParser.
     *
     * @return a Builder for more configuration options
     */
    public static Builder withDefaults();

    /**
     * Creates a builder with a custom PathPatternParser.
     *
     * @param parser the PathPatternParser to use
     * @return a Builder for more configuration options
     */
    public static Builder withPathPatternParser(PathPatternParser parser);

    public boolean matches(HttpServletRequest request);

    public MatchResult matcher(HttpServletRequest request);

    /**
     * Builder for creating PathPatternRequestMatcher with base path support.
     * Useful for reusing a common path prefix across multiple matchers.
     */
    public static final class Builder {
        /**
         * Sets a base path prefix for all matchers created by this builder.
         *
         * @param basePath the path prefix (e.g., "/api", "/mvc")
         * @return this Builder
         */
        public Builder basePath(String basePath);

        /**
         * Creates a matcher for any HTTP method.
         *
         * @param path the path pattern relative to the base path
         * @return a PathPatternRequestMatcher
         */
        public PathPatternRequestMatcher matcher(String path);

        /**
         * Creates a matcher for a specific HTTP method.
         *
         * @param method the HTTP method, may be null
         * @param path the path pattern relative to the base path
         * @return a PathPatternRequestMatcher
         */
        public PathPatternRequestMatcher matcher(HttpMethod method, String path);
    }
}

import org.springframework.http.HttpMethod;
import org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher;

// Simple path pattern
PathPatternRequestMatcher adminMatcher = PathPatternRequestMatcher.pathPattern("/admin/**");

// With HTTP method
PathPatternRequestMatcher postUsersMatcher =
    PathPatternRequestMatcher.pathPattern(HttpMethod.POST, "/users/**");

// With base path for reuse
PathPatternRequestMatcher.Builder api = PathPatternRequestMatcher.withDefaults()
    .basePath("/api");

http.authorizeHttpRequests(authorize -> authorize
    .requestMatchers(api.matcher("/users/**")).hasRole("USER")
    .requestMatchers(api.matcher("/admin/**")).hasRole("ADMIN")
);

// With path variables - variables are captured in MatchResult
PathPatternRequestMatcher userMatcher =
    PathPatternRequestMatcher.pathPattern("/users/{userId}/**");

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;

public final class RegexRequestMatcher implements RequestMatcher {
    /**
     * Creates a regex matcher.
     *
     * @param pattern the regex pattern
     * @param httpMethod the HTTP method or null for any
     */
    public RegexRequestMatcher(String pattern, String httpMethod);
    
    /**
     * Creates a regex matcher with case sensitivity control.
     *
     * @param pattern the regex pattern
     * @param httpMethod the HTTP method
     * @param caseInsensitive whether matching is case-insensitive
     */
    public RegexRequestMatcher(String pattern, String httpMethod, boolean caseInsensitive);
    
    public boolean matches(HttpServletRequest request);
    
    public String toString();
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;
import java.util.List;

public final class AndRequestMatcher implements RequestMatcher {
    /**
     * Creates an AND matcher.
     *
     * @param requestMatchers the list of matchers
     */
    public AndRequestMatcher(List<RequestMatcher> requestMatchers);
    
    /**
     * Creates an AND matcher from varargs.
     */
    public AndRequestMatcher(RequestMatcher... requestMatchers);
    
    public boolean matches(HttpServletRequest request);
    
    public MatchResult matcher(HttpServletRequest request);
    
    public String toString();
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;
import java.util.List;

public final class OrRequestMatcher implements RequestMatcher {
    /**
     * Creates an OR matcher.
     *
     * @param requestMatchers the list of matchers
     */
    public OrRequestMatcher(List<RequestMatcher> requestMatchers);
    
    /**
     * Creates an OR matcher from varargs.
     */
    public OrRequestMatcher(RequestMatcher... requestMatchers);
    
    public boolean matches(HttpServletRequest request);
    
    public MatchResult matcher(HttpServletRequest request);
    
    public String toString();
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;

public final class NegatedRequestMatcher implements RequestMatcher {
    /**
     * Creates a negated matcher.
     *
     * @param requestMatcher the matcher to negate
     */
    public NegatedRequestMatcher(RequestMatcher requestMatcher);
    
    public boolean matches(HttpServletRequest request);
    
    public String toString();
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;

public final class AnyRequestMatcher implements RequestMatcher {
    public static final AnyRequestMatcher INSTANCE = new AnyRequestMatcher();
    
    public boolean matches(HttpServletRequest request);
    
    public String toString();
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;

public class RequestHeaderRequestMatcher implements RequestMatcher {
    /**
     * Creates a matcher for header presence.
     *
     * @param expectedHeaderName the header name
     */
    public RequestHeaderRequestMatcher(String expectedHeaderName);
    
    /**
     * Creates a matcher for header with specific value.
     *
     * @param expectedHeaderName the header name
     * @param expectedHeaderValue the expected value
     */
    public RequestHeaderRequestMatcher(String expectedHeaderName, String expectedHeaderValue);
    
    public boolean matches(HttpServletRequest request);
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;
import java.util.Collection;

import org.springframework.http.MediaType;

public class MediaTypeRequestMatcher implements RequestMatcher {
    /**
     * Creates a matcher for media types.
     *
     * @param mediaTypes the media types to match
     */
    public MediaTypeRequestMatcher(MediaType... mediaTypes);
    
    /**
     * Creates a matcher for media type collection.
     */
    public MediaTypeRequestMatcher(Collection<MediaType> mediaTypes);
    
    public boolean matches(HttpServletRequest request);
    
    /**
     * Sets whether to ignore media type parameters (default: true).
     */
    public void setIgnoredMediaTypes(Set<MediaType> ignoredMediaTypes);
    
    /**
     * Sets whether to use Java Servlet spec behavior (default: false).
     */
    public void setUseEquals(boolean useEquals);
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;

public final class IpAddressMatcher implements RequestMatcher {
    /**
     * Creates a matcher for IP address or CIDR notation.
     *
     * @param ipAddress IP address or CIDR (e.g., "192.168.1.0/24")
     */
    public IpAddressMatcher(String ipAddress);

    public boolean matches(HttpServletRequest request);
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;

public final class ParameterRequestMatcher implements RequestMatcher {
    /**
     * Creates a matcher for parameter presence (matches if parameter exists with any non-null value).
     *
     * @param name the parameter name
     */
    public ParameterRequestMatcher(String name);

    /**
     * Creates a matcher for parameter with specific value.
     * If value is a placeholder (e.g., "{paramValue}"), matches any value and extracts it as a variable.
     *
     * @param name the parameter name
     * @param value the expected value or placeholder
     */
    public ParameterRequestMatcher(String name, String value);

    public boolean matches(HttpServletRequest request);

    public MatchResult matcher(HttpServletRequest request);
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.DispatcherType;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpMethod;

public class DispatcherTypeRequestMatcher implements RequestMatcher {
    /**
     * Creates a matcher for specific dispatcher type.
     *
     * @param dispatcherType the type to match (FORWARD, INCLUDE, REQUEST, ASYNC, ERROR)
     */
    public DispatcherTypeRequestMatcher(DispatcherType dispatcherType);

    /**
     * Creates a matcher for specific dispatcher type and HTTP method.
     *
     * @param dispatcherType the type to match
     * @param httpMethod the HTTP method to match (may be null to match all methods)
     */
    public DispatcherTypeRequestMatcher(DispatcherType dispatcherType, HttpMethod httpMethod);

    public boolean matches(HttpServletRequest request);
}

package org.springframework.security.web.util.matcher;

public final class RequestMatcherEntry<T> {
    /**
     * Creates a request matcher entry.
     *
     * @param requestMatcher the request matcher
     * @param entry the associated value
     */
    public RequestMatcherEntry(RequestMatcher requestMatcher, T entry);

    /**
     * Gets the request matcher.
     *
     * @return the request matcher
     */
    public RequestMatcher getRequestMatcher();

    /**
     * Gets the associated entry value.
     *
     * @return the entry value
     */
    public T getEntry();
}

package org.springframework.security.web.util.matcher;

import jakarta.servlet.http.HttpServletRequest;

import org.springframework.expression.EvaluationContext;
import org.springframework.expression.Expression;

public class ELRequestMatcher implements RequestMatcher {
    /**
     * Creates a matcher with an EL expression.
     *
     * @param el the Spring EL expression
     */
    public ELRequestMatcher(String el);

    public boolean matches(HttpServletRequest request);

    /**
     * Creates the evaluation context for the expression.
     *
     * @param request the HTTP request
     * @return the evaluation context
     */
    protected EvaluationContext createELContext(HttpServletRequest request);

    public String toString();
}

import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher;

@Configuration
public class RequestMatcherConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers(PathPatternRequestMatcher.pathPattern("/api/**")).hasRole("API_USER")
                .requestMatchers(PathPatternRequestMatcher.pathPattern("/admin/**")).hasRole("ADMIN")
                .anyRequest().authenticated()
            );

        return http.build();
    }
}

import org.springframework.security.web.util.matcher.*;
import org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher;

// Match API endpoints but exclude public ones
RequestMatcher apiMatcher = PathPatternRequestMatcher.pathPattern("/api/**");
RequestMatcher publicMatcher = PathPatternRequestMatcher.pathPattern("/api/public/**");
RequestMatcher privateApiMatcher = new AndRequestMatcher(
    apiMatcher,
    new NegatedRequestMatcher(publicMatcher)
);

// Match either admin or manager endpoints
RequestMatcher adminOrManagerMatcher = new OrRequestMatcher(
    PathPatternRequestMatcher.pathPattern("/admin/**"),
    PathPatternRequestMatcher.pathPattern("/manager/**")
);

import org.springframework.security.web.util.matcher.IpAddressMatcher;
import org.springframework.security.web.util.matcher.RequestMatcher;

@Configuration
public class IpBasedAccessConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        RequestMatcher internalNetwork = new IpAddressMatcher("192.168.0.0/16");
        
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers(internalNetwork).permitAll()
                .anyRequest().authenticated()
            );
        
        return http.build();
    }
}