Compare commits
1 commit
c01c6d0ba1
...
a9fdd6599d
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a9fdd6599d |
1 changed files with 0 additions and 135 deletions
135
CLAUDE.md
135
CLAUDE.md
|
|
@ -1,135 +0,0 @@
|
||||||
# CLAUDE.md
|
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
aproxy is an Activity Pub Reverse Proxy Framework built on OpenResty (NGINX + LuaJIT). It provides a modular script system to add filtering and protection capabilities in front of ActivityPub implementations.
|
|
||||||
|
|
||||||
## Development Commands
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
```sh
|
|
||||||
# Install test dependencies (only needed once)
|
|
||||||
make testdeps
|
|
||||||
eval (luarocks-5.1 path --bin)
|
|
||||||
|
|
||||||
# Run test suite
|
|
||||||
make test
|
|
||||||
```
|
|
||||||
|
|
||||||
The test suite uses luajit and luaunit for testing. Tests are located in the `tests/` directory.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
### Core Components
|
|
||||||
|
|
||||||
- **main.lua**: Entry point with two hooks:
|
|
||||||
- `init()`: Validates configuration at startup
|
|
||||||
- `access()`: Called on every request to execute the filter chain
|
|
||||||
|
|
||||||
- **config.lua**: Configuration system
|
|
||||||
- Searches for `conf.lua` in paths: `.;/etc/aproxy` (or `$APROXY_CONFIG_PATH`)
|
|
||||||
- Provides schema validation framework
|
|
||||||
- Schema supports types: `string`, `number`, `table`, `list` (array of values)
|
|
||||||
|
|
||||||
- **ctx.lua**: Request context and filter chain executor
|
|
||||||
- Loads scripts from config and builds `compiled_chain`
|
|
||||||
- Matches request URIs against script PCRE regexes
|
|
||||||
- Executes matching callbacks sequentially
|
|
||||||
- If any callback returns a status code, request is terminated with that response
|
|
||||||
|
|
||||||
- **util.lua**: Lua standard library extensions
|
|
||||||
- `table.readonly()`: Create read-only table wrapper
|
|
||||||
- `table.pprint()`: Pretty-print nested tables
|
|
||||||
- `string.split()`: Split strings by separator
|
|
||||||
|
|
||||||
### Script Module Structure
|
|
||||||
|
|
||||||
Scripts live in `scripts/` and must export:
|
|
||||||
|
|
||||||
```lua
|
|
||||||
return {
|
|
||||||
name = 'ModuleName',
|
|
||||||
author = 'email',
|
|
||||||
title = 'Short Title',
|
|
||||||
description = [[Long description]],
|
|
||||||
version = 1,
|
|
||||||
|
|
||||||
-- Called once at startup with config
|
|
||||||
-- Return value becomes module state
|
|
||||||
init = function(cfg)
|
|
||||||
return state
|
|
||||||
end,
|
|
||||||
|
|
||||||
-- Map of PCRE regex patterns to callback functions
|
|
||||||
callbacks = {
|
|
||||||
['/api/path'] = function(cfg, state)
|
|
||||||
-- Return nil to allow request
|
|
||||||
-- Return status_code, body to block request
|
|
||||||
return nil
|
|
||||||
end
|
|
||||||
},
|
|
||||||
|
|
||||||
-- Schema for validating this module's config
|
|
||||||
config = {
|
|
||||||
['field_name'] = {
|
|
||||||
type = 'string|number|table|list',
|
|
||||||
schema = {...}, -- for table/list types
|
|
||||||
description = 'field description'
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Important**: Module configs are made read-only via `table.readonly()` before being passed to callbacks. Attempting to modify them will error.
|
|
||||||
|
|
||||||
### Request Flow
|
|
||||||
|
|
||||||
1. OpenResty calls `aproxy.main.access()` on each request
|
|
||||||
2. `ctx:onRequest()` iterates through `compiled_chain`
|
|
||||||
3. For each script, check if request URI matches any callback regex
|
|
||||||
4. Execute matching callbacks with their config and state
|
|
||||||
5. If callback returns `(status_code, body)`, terminate request with that response
|
|
||||||
6. If callback returns `nil`, continue to next callback
|
|
||||||
7. If no callbacks block the request, pass through to backend
|
|
||||||
|
|
||||||
### Testing Framework
|
|
||||||
|
|
||||||
Tests use a mock `ngx` object (created by `createNgx()` in test.lua) that simulates OpenResty's API:
|
|
||||||
- `ngx.var.uri`: Request URI
|
|
||||||
- `ngx.req.get_uri_args()`: Query parameters
|
|
||||||
- `ngx.req.get_headers()`: Request headers
|
|
||||||
- `ngx.status`, `ngx.say()`, `ngx.exit()`: Response control
|
|
||||||
- `ngx.re.match()`: PCRE regex matching via rex_pcre2
|
|
||||||
|
|
||||||
Use `setupTest(module_path, config)` to initialize a module for testing and `setupFakeRequest(path, options)` to simulate requests.
|
|
||||||
|
|
||||||
To run the test suite:
|
|
||||||
```sh
|
|
||||||
# needed only once ever to setup the environment
|
|
||||||
make testdeps
|
|
||||||
|
|
||||||
# run once on any new shell
|
|
||||||
eval (luarocks-5.1 path --bin)
|
|
||||||
|
|
||||||
# actually run suite
|
|
||||||
make test
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
The default config file (`conf.lua`) structure:
|
|
||||||
|
|
||||||
```lua
|
|
||||||
return {
|
|
||||||
version = 1,
|
|
||||||
wantedScripts = {
|
|
||||||
['script_name'] = {
|
|
||||||
-- script-specific config matching its schema
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Scripts are loaded from `scripts/{script_name}.lua` based on keys in `wantedScripts`.
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue