Skip to content

Commit 7160ba5

Browse files
RxflexRxflex
committed
docs: add public repository metadata
1 parent decdf02 commit 7160ba5

10 files changed

Lines changed: 321 additions & 2 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: Bug report
3+
about: Report a runtime, transport, FFI, or integration bug
4+
title: "[bug] "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## Summary
10+
11+
What failed?
12+
13+
## Environment
14+
15+
- OS:
16+
- Architecture:
17+
- Commit / tag:
18+
- Build artifact or local build:
19+
20+
## Area
21+
22+
- [ ] bootstrap
23+
- [ ] transport
24+
- [ ] NAT / relay
25+
- [ ] pubsub / mesh
26+
- [ ] FFI
27+
- [ ] docs
28+
- [ ] other
29+
30+
## Reproduction
31+
32+
1.
33+
2.
34+
3.
35+
36+
## Expected behavior
37+
38+
## Actual behavior
39+
40+
## Logs / diagnostics
41+
42+
Paste relevant output, `Moss_GetMeshInfo`, NAT type, or screenshots here.

‎.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 report
4+
url: https://github.com/redstone-md/moss/security
5+
about: Do not disclose vulnerabilities in public issues.
6+
- name: MOSH desktop client
7+
url: https://github.com/redstone-md/mosh
8+
about: Desktop chat UX issues belong in the separate MOSH repository.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
name: Feature request
3+
about: Propose a runtime, FFI, tooling, or documentation improvement
4+
title: "[feature] "
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
## Problem
10+
11+
What limitation are you trying to solve?
12+
13+
## Proposed change
14+
15+
Describe the expected behavior or API.
16+
17+
## Why this belongs in MOSS
18+
19+
Explain why this should live in the runtime/core repository instead of a client such as MOSH.
20+
21+
## Compatibility impact
22+
23+
- [ ] no public API change
24+
- [ ] FFI surface change
25+
- [ ] config schema change
26+
- [ ] protocol / wire behavior change
27+
28+
## Additional context

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## Summary
2+
3+
## Verification
4+
5+
- [ ] `go test ./... -count=1 -timeout 1800s`
6+
- [ ] relevant manual verification completed
7+
8+
## Compatibility
9+
10+
- [ ] no FFI/API change
11+
- [ ] docs updated if behavior changed
12+
- [ ] release/runtime impact noted
13+
14+
## Notes

‎CODE_OF_CONDUCT.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Code of Conduct
2+
3+
## Our standard
4+
5+
Contributors are expected to keep discussion technical, respectful, and direct.
6+
7+
Examples of acceptable behavior:
8+
9+
- giving actionable technical feedback
10+
- disagreeing on design with concrete reasoning
11+
- reporting bugs and regressions clearly
12+
- acknowledging uncertainty honestly
13+
14+
Examples of unacceptable behavior:
15+
16+
- harassment or personal attacks
17+
- hostile, inflammatory, or insulting language
18+
- doxxing or sharing private information
19+
- repeated bad-faith disruption
20+
21+
## Enforcement
22+
23+
Maintainers may remove comments, reject contributions, or block participation when behavior makes collaboration unsafe or unproductive.
24+
25+
## Scope
26+
27+
This applies to:
28+
29+
- issues
30+
- pull requests
31+
- code review
32+
- discussions tied to this repository

‎CONTRIBUTING.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Contributing
2+
3+
## Before you start
4+
5+
- use `dev` for active work
6+
- keep changes focused and atomic
7+
- prefer fixing root causes over adding special cases
8+
9+
## Development workflow
10+
11+
1. Create a branch from `dev`.
12+
2. Make a narrowly scoped change.
13+
3. Add or update tests.
14+
4. Run the relevant local verification commands.
15+
5. Open a pull request against `dev`.
16+
17+
## Required local checks
18+
19+
At minimum:
20+
21+
```bash
22+
go test ./... -count=1 -timeout 1800s
23+
```
24+
25+
If you touch FFI behavior, also rebuild the shared library:
26+
27+
```bash
28+
go build -buildmode=c-shared -o moss.dll ./cmd/moss-ffi
29+
```
30+
31+
On Unix-like systems:
32+
33+
```bash
34+
go build -buildmode=c-shared -o libmoss.so ./cmd/moss-ffi
35+
```
36+
37+
## Commit style
38+
39+
Use Conventional Commits:
40+
41+
- `feat:`
42+
- `fix:`
43+
- `docs:`
44+
- `ci:`
45+
- `test:`
46+
- `chore:`
47+
48+
## Pull request expectations
49+
50+
A good pull request includes:
51+
52+
- what changed
53+
- why it changed
54+
- how it was verified
55+
- any behavior or compatibility risks
56+
57+
## Design expectations
58+
59+
- keep runtime code readable and testable
60+
- avoid unnecessary coupling across `internal/*` packages
61+
- preserve FFI compatibility unless the change is intentional and documented
62+
- validate all new external inputs
63+
64+
## Separate client repository
65+
66+
Desktop chat clients live in [MOSH](https://github.com/redstone-md/mosh).
67+
68+
Changes to the shared runtime contract should update:
69+
70+
- `docs/API.md`
71+
- `docs/SHARED_INTEGRATION.md`
72+
- MOSH integration code if the desktop client is affected

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 redstone-md
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
[![CI Main](https://github.com/redstone-md/moss/actions/workflows/ci-main.yml/badge.svg)](https://github.com/redstone-md/moss/actions/workflows/ci-main.yml)
44
[![CI Dev](https://github.com/redstone-md/moss/actions/workflows/ci-dev.yml/badge.svg)](https://github.com/redstone-md/moss/actions/workflows/ci-dev.yml)
55

6-
Moss is an embeddable P2P mesh core written in Go and exported through CGO as a C-shared library. The project in this repository follows the `PRD.md` scope with a pragmatic v1 implementation:
6+
Moss is an embeddable P2P mesh core written in Go and exported through CGO as a C-shared library. This repository is the runtime layer, not the end-user chat application.
7+
8+
The current implementation covers the `PRD.md` scope with a pragmatic v1 runtime:
79

810
- tracker-based bootstrapping via BEP 15 UDP and BEP 3 HTTP announces
911
- encrypted peer transport with Noise XX (`25519_ChaChaPoly_BLAKE2s`) plus identity binding
@@ -12,12 +14,25 @@ Moss is an embeddable P2P mesh core written in Go and exported through CGO as a
1214
- C FFI surface with examples for C, C++, Python (`ctypes`), and Rust
1315
- unit, integration, and shared-library smoke tests
1416

15-
Desktop chat clients now live in the separate [MOSH](https://github.com/redstone-md/mosh) repository, which consumes `MOSS` through the shared runtime and a Git submodule pin for compatibility.
17+
Desktop clients now live in the separate [MOSH](https://github.com/redstone-md/mosh) repository, which consumes `MOSS` through the shared runtime and a Git submodule pin for compatibility.
18+
19+
## Repository role
20+
21+
- `MOSS` = runtime, protocol, NAT/relay logic, FFI, examples
22+
- `MOSH` = desktop chat client built on top of `MOSS`
1623

1724
FFI docs:
1825

1926
- API reference: [docs/API.md](docs/API.md)
2027
- Shared integration guide: [docs/SHARED_INTEGRATION.md](docs/SHARED_INTEGRATION.md)
28+
- Known limitations: [docs/KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md)
29+
30+
Repository policy:
31+
32+
- License: [MIT](LICENSE)
33+
- Security reporting: [SECURITY.md](SECURITY.md)
34+
- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
35+
- Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
2136

2237
## Layout
2338

@@ -49,6 +64,19 @@ CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 \
4964

5065
The generated header is emitted next to the shared library as `moss.h` or `libmoss.h`, depending on the output name.
5166

67+
## Quick Start
68+
69+
Build the shared runtime:
70+
71+
```bash
72+
go build -buildmode=c-shared -o moss.dll ./cmd/moss-ffi
73+
```
74+
75+
Then integrate it from your host application through the FFI surface described in:
76+
77+
- [docs/API.md](docs/API.md)
78+
- [docs/SHARED_INTEGRATION.md](docs/SHARED_INTEGRATION.md)
79+
5280
GitHub Actions publishes release artifacts only from tags.
5381

5482
Main release tags (`v*`) publish separate shared-library artifacts for both macOS architectures:
@@ -92,6 +120,12 @@ Current exported functions:
92120

93121
See [docs/API.md](docs/API.md) for signatures, config fields, event IDs, and error codes.
94122

123+
## Stability Notes
124+
125+
- The repository is public-ready as a runtime/core project.
126+
- NAT traversal and relay fallback are implemented and tested, but network behavior still depends on real-world topology.
127+
- Public client-facing UX issues should go to [MOSH](https://github.com/redstone-md/mosh).
128+
95129
## Local integration example
96130

97131
Two nodes on localhost can be started with one node configured as a static peer of the other:

‎SECURITY.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Security Policy
2+
3+
## Supported branches
4+
5+
Security fixes are applied on a best-effort basis to:
6+
7+
- `main`
8+
- `dev`
9+
10+
Tagged releases are preferred for downstream consumption. If a security fix lands on `dev` first, it may be promoted to `main` after verification.
11+
12+
## Reporting a vulnerability
13+
14+
Do not open public GitHub issues for suspected vulnerabilities.
15+
16+
Send a private report to the repository maintainers with:
17+
18+
- affected version, commit, or artifact
19+
- impact summary
20+
- reproduction steps or proof of concept
21+
- any suggested mitigation
22+
23+
If direct maintainer contact is unavailable, open a GitHub issue with no exploit details and state that you need a private security contact.
24+
25+
## Scope
26+
27+
Security-sensitive areas in this repository include:
28+
29+
- `cmd/moss-ffi` shared-library boundary
30+
- `internal/transport` encrypted session handling
31+
- `internal/bootstrap` tracker parsing and announce handling
32+
- `internal/nat` NAT traversal and relay behavior
33+
34+
Out-of-scope items usually include:
35+
36+
- local development environment issues
37+
- unsupported forks
38+
- social engineering or physical access scenarios
39+
40+
## Disclosure expectations
41+
42+
- reasonable time for triage is expected before public disclosure
43+
- coordinated disclosure is preferred
44+
- fixes may land together with tests and hardening notes

‎docs/KNOWN_LIMITATIONS.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Known Limitations
2+
3+
This document exists to keep repository claims aligned with current runtime behavior.
4+
5+
## Runtime and networking
6+
7+
- NAT traversal is implemented pragmatically, but not every real-world NAT topology has the same success rate.
8+
- Direct UDP paths are more sensitive to packet loss and jitter than relay fallback paths.
9+
- Relay and NAT behavior are covered by tests, but large-scale public-network validation is still more limited than pure unit coverage.
10+
11+
## Specification parity
12+
13+
- The repository tracks the `PRD.md` scope with a practical v1 implementation.
14+
- Some production-grade goals from the PRD are only partially proven by automated tests and not by broad public telemetry.
15+
16+
## Performance and scale
17+
18+
- CI validates correctness first; it is not a substitute for sustained long-running load tests.
19+
- Benchmarks exist, but public support guarantees for every network environment are intentionally conservative.
20+
21+
## Client applications
22+
23+
- `MOSS` is the runtime and shared-library repository.
24+
- Desktop chat UX now lives in [MOSH](https://github.com/redstone-md/mosh), which evolves separately.

0 commit comments

Comments
 (0)