Skip to content

Commit e5f811c

Browse files
htcom-codehtcom-code
committed
feat: initial public release (v0.0.1)
0 parents  commit e5f811c

96 files changed

Lines changed: 65250 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Normalize line endings so checkouts are identical on macOS, Linux, and Windows.
2+
# Without this, Git-for-Windows (core.autocrlf=true) checks out *.go with CRLF,
3+
# which compiles fine but makes `gofmt -l` flag every file — breaking the format
4+
# discipline. Keeping LF in the working tree avoids that churn.
5+
* text=auto eol=lf
6+
7+
# Toolchain-sensitive text files: force LF explicitly.
8+
*.go text eol=lf
9+
*.mod text eol=lf
10+
*.sum text eol=lf
11+
*.md text eol=lf
12+
*.yml text eol=lf
13+
*.yaml text eol=lf
14+
*.json text eol=lf
15+
*.lua text eol=lf
16+
Makefile text eol=lf
17+
18+
# Binary files Git should never touch.
19+
*.png binary
20+
*.jpg binary
21+
*.gif binary
22+
23+
# Excluded from `git archive` (source snapshots / GitHub mirror), but kept
24+
# tracked here — these are internal development artifacts that stay in the
25+
# origin repo yet don't belong in a published source export. See
26+
# docs/plans/glimmering-gathering-wall.md (GitLab → GitHub migration).
27+
docs/golang-ai-rule.md export-ignore
28+
docs/history.md export-ignore
29+
docs/concurrency-safety.ko.md export-ignore
30+
docs/plans/ export-ignore
31+
.gitlab-ci.yml export-ignore
32+
.claude/ export-ignore

‎.github/CODEOWNERS‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Default owner for everything in the repo.
2+
# See https://docs.github.com/articles/about-code-owners
3+
* @htjulia

‎.github/FUNDING.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# These are supported funding model platforms
2+
3+
github: htcom-code
4+
#patreon: # Replace with a single Patreon username
5+
#open_collective: # Replace with a single Open Collective username
6+
#ko_fi: # Replace with a single Ko-fi username
7+
#tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
8+
#community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
9+
#liberapay: # Replace with a single Liberapay username
10+
#issuehunt: # Replace with a single IssueHunt username
11+
#lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
12+
#polar: # Replace with a single Polar username
13+
#buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
14+
#thanks_dev: # Replace with a single thanks.dev username
15+
#custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Bug report
2+
description: luart misbehaves — wrong result, crash, race, leak, or a pooling / caching / registry / config fault.
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for the report. `luart` is a **high-performance, concurrency-safe
9+
runtime** (bytecode cache + per-script VM pool + dynamic registry) built on
10+
top of [lua-pure](https://github.com/htcom-code/lua-pure).
11+
12+
- **Lua *language* bugs** (a script behaves differently from PUC-Lua 5.4.8,
13+
wrong error text, arithmetic/coercion, `string.*`) belong to
14+
**[lua-pure](https://github.com/htcom-code/lua-pure/issues)**, not here.
15+
- File here for luart's runtime: caching, VM pooling, the dynamic registry
16+
(lazy load, TTL eviction, memory budget, hot reload), `SourceLoader`,
17+
`ExecTimeout` / `MaxInstructions`, `Config`, observability.
18+
- **Security issues:** do **not** file here — see
19+
[SECURITY.md](../blob/main/SECURITY.md).
20+
- type: textarea
21+
id: reproducer
22+
attributes:
23+
label: Minimal reproducer
24+
description: The smallest Go program (using luart) plus Lua script that triggers the bug. A failing test is ideal.
25+
render: go
26+
placeholder: |
27+
loader := luart.NewMapLoader()
28+
loader.Set("s", `function f() return 1 end`, luart.HashVersion("..."), "1.0.0")
29+
rt := luart.New(loader, luart.Config{MaxStates: 4})
30+
defer rt.Close()
31+
_, err := rt.Run(context.Background(), "s", "f")
32+
validations:
33+
required: true
34+
- type: textarea
35+
id: expected
36+
attributes:
37+
label: Expected behaviour
38+
description: What you expected luart to do.
39+
validations:
40+
required: true
41+
- type: textarea
42+
id: actual
43+
attributes:
44+
label: Actual behaviour
45+
description: What happened instead — output, error, panic, stack trace, or `-race` report. Paste it verbatim.
46+
render: shell
47+
validations:
48+
required: true
49+
- type: input
50+
id: version
51+
attributes:
52+
label: luart version / commit
53+
description: Release tag (e.g. v0.2.0) or commit SHA.
54+
placeholder: "v0.2.0 or abc1234"
55+
validations:
56+
required: true
57+
- type: input
58+
id: goenv
59+
attributes:
60+
label: Go version & OS/arch
61+
description: Output of `go version`.
62+
placeholder: "go1.24 darwin/arm64"
63+
validations:
64+
required: false
65+
- type: textarea
66+
id: config
67+
attributes:
68+
label: Config & concurrency context
69+
description: >-
70+
Relevant `Config` (MaxStates, MemoryBudgetBytes, IdleTTL, ExecTimeout,
71+
MaxInstructions, SkipOpenLibs, custom Libs), which `SourceLoader` you use,
72+
and the concurrency shape (how many goroutines call `Run`, whether hot
73+
reload / eviction was active). Most pooling/registry bugs only reproduce
74+
under a specific config + load.
75+
validations:
76+
required: false
77+
- type: textarea
78+
id: extra
79+
attributes:
80+
label: Anything else
81+
description: Logs, metrics, profiles, or other context.
82+
validations:
83+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Security vulnerability
4+
url: https://github.com/htcom-code/go-lua-perf/security/advisories/new
5+
about: Report a vulnerability privately — do not open a public issue. See SECURITY.md.
6+
- name: Lua language behaviour (lua-pure)
7+
url: https://github.com/htcom-code/lua-pure/issues
8+
about: Bugs in Lua semantics / standard library (differs from PUC-Lua 5.4.8) belong to the lua-pure engine, not luart.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Feature request
2+
description: Suggest a luart runtime capability — caching, pooling, registry, config, observability, or a SourceLoader enhancement.
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
`luart` is the **runtime layer** — bytecode caching, per-script VM pooling,
9+
the dynamic registry, `SourceLoader`, config, and observability — on top of
10+
[lua-pure](https://github.com/htcom-code/lua-pure).
11+
12+
Requests for the **Lua language surface** (new/changed Lua semantics,
13+
standard-library behaviour) are **out of scope here** — those track PUC-Lua
14+
upstream in [lua-pure](https://github.com/htcom-code/lua-pure/issues).
15+
- type: textarea
16+
id: problem
17+
attributes:
18+
label: Problem / use case
19+
description: What are you trying to do, and what's missing or awkward with luart today?
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: proposal
24+
attributes:
25+
label: Proposed solution
26+
description: The API or behaviour you'd like. A sketch of the Go call site (New / Run / Config / SourceLoader) helps.
27+
render: go
28+
validations:
29+
required: true
30+
- type: textarea
31+
id: alternatives
32+
attributes:
33+
label: Alternatives considered
34+
description: Workarounds you've tried (e.g. a custom SourceLoader, external cache) or other designs you weighed.
35+
validations:
36+
required: false
37+
- type: checkboxes
38+
id: scope
39+
attributes:
40+
label: Scope check
41+
options:
42+
- label: This is about the luart runtime, not a change to the Lua language surface (those go to lua-pure).
43+
required: true
44+
- label: I've considered whether this fits an existing extension point (custom SourceLoader, Config.Libs, Metrics/Logger/TraceHook) rather than a core change.
45+
required: false

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
<!--
2+
Thanks for contributing to go-lua-perf (luart)! Keep the title in Conventional
3+
Commits form, e.g. `fix(pool): release State on Run panic`.
4+
Delete any section that does not apply.
5+
-->
6+
7+
## What & why
8+
9+
<!-- What does this change do, and what problem does it solve? -->
10+
11+
## Type of change
12+
13+
- [ ] `fix` — bug fix (no new API)
14+
- [ ] `feat` — new capability (runtime, registry, config, SourceLoader, observability)
15+
- [ ] `perf` — performance, no observable behaviour change
16+
- [ ] `docs` — documentation only
17+
- [ ] `refactor` / `chore` / `test` / `ci` — no behaviour change
18+
19+
## Concurrency & correctness
20+
21+
luart is concurrency-safe by contract — pooled States are never shared across
22+
goroutines, and the registry is exercised under load.
23+
24+
- [ ] `make race` passes (`go test -race ./...`)
25+
- [ ] Added/updated exception-case tests (nil/empty, cancellation/timeout,
26+
eviction under memory budget, hot reload, double-close, leak/invariant)
27+
- [ ] No `lua.Value` reference escapes the State that owns it
28+
29+
## Performance (for `perf`, and anything touching the hot path)
30+
31+
The caching + pooling wins (load/cache-hit ≈ file-size-independent; pool reuse)
32+
are the point of this library — guard them.
33+
34+
- [ ] `benchstat` before/after included below; no regression on the affected benchmark
35+
- [ ] Allocation counts (`-benchmem`) checked where relevant
36+
37+
```
38+
<!-- benchstat / go test -bench output -->
39+
```
40+
41+
## Verification
42+
43+
The Makefile is the single source of truth.
44+
45+
- [ ] `make all` passes (vet → test → race → build)
46+
- [ ] Godoc updated for any exported symbol (with `// Since: YYYY-MM-DD` on new API)
47+
- [ ] Docs updated if behaviour/config changed (README, `docs/*`)
48+
49+
## Related
50+
51+
<!-- Closes #123, related issues. -->

‎.github/dependabot.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
version: 2
2+
updates:
3+
# Go module dependencies (lua-pure, yaml.v3).
4+
- package-ecosystem: gomod
5+
directory: "/"
6+
schedule:
7+
interval: weekly
8+
open-pull-requests-limit: 5
9+
10+
# GitHub Actions used in .github/workflows/.
11+
- package-ecosystem: github-actions
12+
directory: "/"
13+
schedule:
14+
interval: weekly
15+
open-pull-requests-limit: 5

‎.github/workflows/ci.yml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# GitHub Actions CI — mirrors the Makefile's verification discipline
2+
# (vet → test → race → build, plus bench) on pull requests and pushes to main,
3+
# and only when source files change (doc-only changes are skipped).
4+
# The Makefile is the single source of truth: jobs call `make <target>` where a
5+
# target exists; the extra hardening steps (gofmt gate, govulncheck,
6+
# cross-platform build, coverage) are CI-only and call `go` directly.
7+
8+
name: CI
9+
10+
on:
11+
push:
12+
branches: [main]
13+
paths:
14+
- "**/*.go"
15+
- "go.mod"
16+
- "go.sum"
17+
- "Makefile"
18+
- ".github/workflows/ci.yml"
19+
pull_request:
20+
paths:
21+
- "**/*.go"
22+
- "go.mod"
23+
- "go.sum"
24+
- "Makefile"
25+
- ".github/workflows/ci.yml"
26+
27+
concurrency:
28+
group: ci-${{ github.ref }}
29+
cancel-in-progress: true
30+
31+
jobs:
32+
# Fast fail on formatting before spending time on the heavier jobs. The repo
33+
# keeps LF line endings (.gitattributes) so gofmt is consistent across OSes.
34+
format:
35+
runs-on: ubuntu-latest
36+
steps:
37+
- uses: actions/checkout@v4
38+
- uses: actions/setup-go@v5
39+
with:
40+
go-version-file: go.mod
41+
- name: gofmt
42+
run: |
43+
unformatted=$(gofmt -l .)
44+
if [ -n "$unformatted" ]; then
45+
echo "These files are not gofmt-clean:"; echo "$unformatted"
46+
exit 1
47+
fi
48+
49+
verify:
50+
runs-on: ubuntu-latest
51+
steps:
52+
- uses: actions/checkout@v4
53+
- uses: actions/setup-go@v5
54+
with:
55+
go-version-file: go.mod # tracks the toolchain pinned in go.mod
56+
cache: true # module + build cache, keyed on go.sum
57+
- run: make vet
58+
# The test gate, with a coverage profile attached (equivalent to `make test`).
59+
- name: test (with coverage)
60+
run: go test -covermode=atomic -coverprofile=coverage.out ./...
61+
- run: make race
62+
- name: upload coverage
63+
uses: actions/upload-artifact@v4
64+
with:
65+
name: coverage
66+
path: coverage.out
67+
if-no-files-found: warn
68+
69+
# Scan dependencies and code for known vulnerabilities.
70+
govulncheck:
71+
runs-on: ubuntu-latest
72+
steps:
73+
- uses: actions/checkout@v4
74+
- uses: actions/setup-go@v5
75+
with:
76+
go-version-file: go.mod
77+
cache: true
78+
- name: govulncheck
79+
run: |
80+
go install golang.org/x/vuln/cmd/govulncheck@latest
81+
govulncheck ./...
82+
83+
# build runs only after verify passes, mirroring Makefile rule #6
84+
# ("build only after tests pass"), and proves the library + all `go` targets
85+
# are cross-platform (the README's Windows/macOS claim). `make` isn't assumed
86+
# on Windows, so call `go` directly.
87+
build:
88+
needs: verify
89+
strategy:
90+
fail-fast: false
91+
matrix:
92+
os: [ubuntu-latest, macos-latest, windows-latest]
93+
runs-on: ${{ matrix.os }}
94+
steps:
95+
- uses: actions/checkout@v4
96+
- uses: actions/setup-go@v5
97+
with:
98+
go-version-file: go.mod
99+
cache: true
100+
- run: go vet ./...
101+
- run: go build ./...
102+
103+
# bench is observational, not a gate — a slow/noisy run must not fail CI.
104+
bench:
105+
needs: verify
106+
runs-on: ubuntu-latest
107+
continue-on-error: true
108+
steps:
109+
- uses: actions/checkout@v4
110+
- uses: actions/setup-go@v5
111+
with:
112+
go-version-file: go.mod
113+
cache: true
114+
- run: make bench

0 commit comments

Comments
 (0)