Skip to content

Commit bff782e

Browse files
ruhan1ruhan1
authored
Update readme (#106)
1 parent b86f684 commit bff782e

1 file changed

Lines changed: 144 additions & 23 deletions

File tree

‎README.md‎

Lines changed: 144 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,158 @@
11
# Indy Generic Proxy Service
2-
Indy Generic Proxy Service is a single full-functional service providing a
3-
generic HTTP proxy interface to Indy cached content, for non-Maven, non-NPM
4-
builds.
52

6-
## Prerequisite for building
7-
1. jdk11
8-
2. mvn 3.6.2+
3+
A high-performance HTTP proxy service built on Quarkus that tracks and records external resource accesses during builds for non-Maven, non-NPM files. The service automatically creates Indy remote repositories based on external URLs and ensures all external dependencies are properly tracked and cached, preventing loss of build dependency information.
94

10-
## Configure
5+
## Architecture
116

12-
see [src/main/resources/application.yaml](src/main/resources/application.yaml) for details
7+
The service is built with a modular architecture:
138

9+
- **Core Proxy Engine**: XNIO-based async HTTP proxy server (`HttpProxy.java`)
10+
- **Request Handlers**: `ProxyAcceptHandler` manages incoming connections and routing
11+
- **MITM SSL Support**: `ProxyMITMSSLServer` enables SSL interception and certificate generation
12+
- **Repository Integration**: REST client services for Indy repository management
13+
- **Authentication**: Keycloak integration with bearer token support
14+
- **Observability**: OpenTelemetry tracing and metrics
1415

15-
## Try it
16+
## Key Features
1617

17-
There are a few steps to set it up.
18+
- **Build Dependency Tracking**: Records all external resource accesses during builds with build ID association
19+
- **Automatic Repository Creation**: Dynamically creates Indy remote repositories based on external host URLs
20+
- **MITM SSL Proxy**: Intercept and proxy HTTPS traffic with custom CA certificates for complete tracking
21+
- **Content Caching**: Intelligent caching with configurable storage strategies to avoid duplicate downloads
22+
- **Repository Management**: Dynamic repository creation and content retrieval via Indy API
23+
- **Authentication**: Keycloak OIDC integration with configurable security
24+
- **High Performance**: Async I/O with configurable worker threads and connection pooling
25+
- **Observability**: Built-in OpenTelemetry tracing and Prometheus metrics
1826

19-
1. Build (make sure you use jdk11 and mvn 3.6.2+)
20-
```
21-
$ git clone git@github.com:Commonjava/indy-generic-proxy-service.git
22-
$ cd indy-generic-proxy-service
23-
$ mvn clean compile
27+
## Technology Stack
28+
29+
- **Runtime**: Quarkus 2.3.0 with Java 11
30+
- **I/O**: XNIO for high-performance async networking
31+
- **HTTP Client**: OkHttp 4.9.2 for repository communication
32+
- **Authentication**: Keycloak 22.0.3 for OIDC/OAuth2
33+
- **Observability**: OpenTelemetry SDK with OTLP export
34+
- **Caching**: Caffeine cache with configurable eviction
35+
36+
## Prerequisites
37+
38+
- JDK 11+
39+
- Maven 3.6.2+
40+
- Running Indy instance (for repository operations)
41+
42+
## Configuration
43+
44+
Key configuration options in `application.yaml`:
45+
46+
```yaml
47+
proxy:
48+
port: 8082 # Proxy server port
49+
secured: true # Enable authentication
50+
worker:
51+
io.threads: 10 # I/O worker threads
52+
task.threads: 10 # Task worker threads
53+
54+
MITM:
55+
enabled: true # Enable MITM SSL
56+
ca.key: /tmp/ssl/ca.der # CA private key
57+
ca.cert: /tmp/ssl/ca.crt # CA certificate
58+
59+
service_proxy:
60+
services:
61+
- host: localhost # Target Indy instance
62+
port: 8080
63+
path-pattern: /api/.+ # URL pattern matching
2464
```
25-
2. Before running this service, it's required to have a running Indy instance
65+
66+
## How It Works
67+
68+
The proxy service solves the problem of lost dependency tracking in non-Maven/non-NPM builds by intercepting all external resource requests:
69+
70+
### Build Dependency Tracking Workflow
71+
72+
1. **Client Request**: Build process sends HTTP/HTTPS request to external resource
73+
2. **Proxy Interception**: Request is intercepted by the proxy service
74+
3. **Build ID Association**: External URL is recorded and associated with the current build ID
75+
4. **Repository Check**: Proxy checks if an Indy remote repository exists for the external host
76+
5. **Repository Creation**: If not found, automatically creates a new remote repository for the host
77+
6. **Content Retrieval**: Fetches the resource from the external URL
78+
7. **Content Storage**: Stores the content in the appropriate Indy repository
79+
8. **Response**: Returns the content to the client
80+
81+
### Benefits
82+
83+
- **Complete Dependency Tracking**: No external resource access goes unrecorded
84+
- **Automatic Repository Management**: No manual repository configuration needed
85+
- **Build Reproducibility**: All dependencies are cached and versioned
86+
- **Security**: MITM SSL support ensures even HTTPS resources are tracked
87+
- **Performance**: Intelligent caching reduces duplicate downloads
88+
89+
## Quick Start
90+
91+
1. **Build the project**:
92+
```bash
93+
git clone https://github.com/Commonjava/indy-generic-proxy-service.git
94+
cd indy-generic-proxy-service
95+
mvn clean compile
2696
```
27-
...
28-
services:
29-
- host: localhost
30-
...
97+
98+
2. **Configure Indy connection** in `application.yaml`:
99+
```yaml
31100
repo-service-api/mp-rest/uri: http://localhost:8080
32-
...
33101
```
34-
3. Start in debug mode
102+
103+
3. **Start in development mode**:
104+
```bash
105+
mvn quarkus:dev
106+
```
107+
108+
4. **Configure your build environment** to use the proxy:
109+
```bash
110+
export http_proxy=http://localhost:8082
111+
export https_proxy=http://localhost:8082
112+
# For builds that support proxy configuration
35113
```
36-
$ mvn quarkus:dev
114+
115+
5. **Run your build** - all external resource accesses will be automatically tracked and cached
116+
117+
## Development
118+
119+
### Key Components
120+
121+
- **`HttpProxy`**: Main application class that starts the XNIO-based proxy server
122+
- **`ProxyAcceptHandler`**: Handles incoming connections and manages the tracking workflow
123+
- **`ProxyMITMSSLServer`**: Manages SSL interception and certificate generation for HTTPS tracking
124+
- **`RepositoryService`**: REST client for Indy repository operations and automatic repository creation
125+
- **`ContentRetrievalService`**: Handles content retrieval, caching, and build ID association
126+
- **`ProxyResponseHelper`**: Manages the complete tracking workflow from request to response
127+
- **`TrackingKey`**: Associates external URLs with build IDs for dependency tracking
128+
129+
### Testing
130+
131+
Run the test suite:
132+
```bash
133+
mvn test
37134
```
135+
136+
The project includes comprehensive tests for proxy functionality, SSL handling, and repository integration.
137+
138+
## Production Deployment
139+
140+
### Docker Support
141+
142+
Multiple Dockerfile variants are available:
143+
- `Dockerfile.jvm`: Standard JVM deployment
144+
- `Dockerfile.native`: Native compilation with GraalVM
145+
- `Dockerfile.native-distroless`: Minimal distroless image
146+
147+
### Monitoring
148+
149+
The service exposes:
150+
- Health checks at `/q/health`
151+
- Metrics at `/q/metrics` (Prometheus format)
152+
- OpenTelemetry traces (configurable endpoints)
153+
154+
### Security Considerations
155+
156+
- Configure proper CA certificates for MITM functionality
157+
- Set up Keycloak authentication for production
158+
- Monitor proxy logs for security events

0 commit comments

Comments
 (0)