diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ce144bf --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +# Code of Conduct + +This project follows the ownCloud Code of Conduct. + +Please read the full Code of Conduct at: +**** + +By participating in this project, you agree to abide by its terms. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..65c9915 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing + +Thank you for your interest in contributing to this project! + +Please read the full contributing guidelines at: +**** + +For development setup, coding standards, and pull request process, +see the README in this repository. diff --git a/README.md b/README.md index 29e47ed..26cce21 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,108 @@ # protoc-gen-microweb -Protocol Buffers plugin that generates HTTP web handlers from protobuf service definitions. Converts gRPC HTTP annotations into Chi router handlers with JSON serialization, eliminating manual HTTP boilerplate code. Generates service interfaces, request/response marshaling, and proper error handling for REST APIs built on protobuf schemas. + -The three files serve different purposes in a protobuf-based system: +[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) [![Docker Hub](https://img.shields.io/docker/pulls/owncloud)](https://hub.docker.com/r/owncloud/ocis) -## `greeter.pb.go` (protoc-gen-go) -- **Purpose**: Core protobuf message definitions and serialization -- **Usage**: Base layer for all protobuf operations +A Protocol Buffers compiler plugin that generates HTTP web handler code from protobuf service definitions. It converts gRPC HTTP annotations into Go Chi router handlers with JSON serialization, producing service interfaces, request/response marshaling, and error handling for REST APIs -- eliminating the boilerplate of manually wiring up protobuf services as HTTP endpoints. -## `greeter.pb.micro.go` (protoc-gen-micro) -- **Purpose**: Go-micro framework client/server code -- **Usage**: For microservices using go-micro framework +## Getting Started -## `greeter.pb.web.go` (protoc-gen-microweb) -- **Purpose**: HTTP REST API handlers -- **Usage**: For HTTP APIs that expose protobuf services as REST +Follow the steps below to install and use the protoc plugin. -## Differences: -- **Protocol**: `pb.go` = protobuf binary, `micro.go` = micro RPC, `web.go` = HTTP/JSON -- **Transport**: `pb.go` = none, `micro.go` = micro client/server, `web.go` = Chi HTTP router -- **Serialization**: `pb.go` = protobuf binary, `micro.go` = protobuf binary, `web.go` = JSON -- **Use case**: `pb.go` = foundation, `micro.go` = microservices, `web.go` = REST APIs +### Installation -**The three files work together: `pb.go` provides the data structures, `micro.go` enables microservice communication, and `web.go` exposes HTTP REST endpoints.** +```bash +go install github.com/owncloud/protoc-gen-microweb@latest +``` + +### Usage +```bash +protoc \ + --proto_path=proto/ \ + --microweb_out=proto/ \ + --microweb_opt=module=github.com/your/module/proto \ + proto/your_service.proto +``` -## Quick Example +### Development -```protobuf -service Greeter { - rpc Say(SayRequest) returns (SayResponse) { - option (google.api.http) = { - post: "/api/say" - body: "*" - }; - } -} +```bash +go get -d github.com/owncloud/protoc-gen-microweb +go install ``` -```go -// Generated handler interface -type GreeterHandler interface { - Say(ctx context.Context, in *SayRequest, out *SayResponse) error -} +### Testing -// Usage -mux := chi.NewMux() -proto.RegisterGreeterWeb(mux, &Greeter{}) +```bash +bash test.sh ``` -## Docs +## Documentation -### Run +- [Protocol Buffers](https://protobuf.dev/) +- [gRPC HTTP Annotations](https://cloud.google.com/endpoints/docs/grpc/transcoding) +- [Chi Router](https://github.com/go-chi/chi) -``` -# Install required tools -go install google.golang.org/protobuf/cmd/protoc-gen-go@latest -go install github.com/owncloud/protoc-gen-microweb@latest +## Part of ownCloud Infinite Scale -# Generate Go code from protobuf -protoc \ - --proto_path=$(go env GOPATH)/pkg/mod/github.com/grpc-ecosystem/grpc-gateway@v1.16.0/third_party/googleapis \ - --proto_path=proto/ \ - --go_out=proto/ \ - --go_opt=module=github.com/owncloud/protoc-gen-microweb/examples/greeter/proto \ - --go-grpc_out=proto/ \ - --go-grpc_opt=module=github.com/owncloud/protoc-gen-microweb/examples/greeter/proto \ - --micro_out=proto/ \ - --micro_opt=module=github.com/owncloud/protoc-gen-microweb/examples/greeter/proto \ - --microweb_out=proto/ \ - --microweb_opt=module=github.com/owncloud/protoc-gen-microweb/examples/greeter/proto \ - proto/greeter.proto -``` +This protoc plugin is used in the [oCIS](https://github.com/owncloud/ocis) build pipeline to generate HTTP REST handlers from protobuf service definitions. -### Install +This component is part of the [oCIS Docker image](https://hub.docker.com/r/owncloud/ocis). -``` -GO111MODULE=off go get -v github.com/owncloud/protoc-gen-microweb -``` +## Community & Support -### Development +**[Star](https://github.com/owncloud/protoc-gen-microweb)** this repo and **Watch** for release notifications! -Make sure you have a working Go environment, for further reference or a guide take a look at the [install instructions](http://golang.org/doc/install.html). This project requires Go >= v1.12. +- [ownCloud Website](https://owncloud.com) +- [Community Discussions](https://github.com/orgs/owncloud/discussions) +- [Matrix Chat](https://app.element.io/#/room/#owncloud:matrix.org) +- [Documentation](https://doc.owncloud.com) +- [Enterprise Support](https://owncloud.com/contact-us/) +- [OSPO Home](https://kiteworks.com/opensource) -```bash -go get -d github.com/owncloud/protoc-gen-microweb -cd $GOPATH/src/github.com/owncloud/protoc-gen-microweb +## Contributing -go install -``` +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. -## Security +### Workflow -If you find a security issue please contact security@owncloud.com first. +- **Rebase Early, Rebase Often!** We use a rebase workflow. Always rebase on the target branch before submitting a PR. +- **Dependabot**: Automated dependency updates are managed via Dependabot. Review and merge dependency PRs promptly. +- **Signed Commits**: All commits **must** be PGP/GPG signed. See [GitHub's signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification). +- **DCO Sign-off**: Every commit must carry a `Signed-off-by` line: + ``` + git commit -s -S -m "your commit message" + ``` +- **GitHub Actions Policy**: Workflows may only use actions that are (a) owned by `owncloud`, (b) created by GitHub (`actions/*`), or (c) verified in the GitHub Marketplace. -## Contributing +## Security -Fork -> Patch -> Push -> Pull Request +**Do not open a public GitHub issue for security vulnerabilities.** -## Authors +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). -* [Thomas Boerger](https://github.com/tboerger) +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) ## License -Apache-2.0 +This project is licensed under the [Apache-2.0](LICENSE). -## Copyright +## About the ownCloud OSPO -``` -Copyright (c) 2021 ownCloud GmbH -``` +The [Kiteworks Open Source Program Office](https://kiteworks.com/opensource), operating under +the [ownCloud](https://owncloud.com) brand, launched on May 5, 2026, to steward the open source +ecosystem around ownCloud's products. The OSPO ensures transparent governance, license compliance, +community health, and sustainable collaboration between the open source community and +[Kiteworks](https://www.kiteworks.com), which acquired ownCloud in 2023. + +- **OSPO Home**: +- **GitHub**: +- **ownCloud**: + +For questions about the OSPO or licensing, contact ospo@kiteworks.com. + +> **License status:** This repository is already licensed under Apache-2.0 -- the OSPO target license. +> No migration is required. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..78094ae --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Reporting a Vulnerability + +**Do NOT open a public GitHub issue for security vulnerabilities.** + +Please report security issues responsibly via: +**** + +You can also report vulnerabilities through our YesWeHack bug bounty program: +**** diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..d87c0ca --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ +# Support + +For support with this project, please use the following channels: + +- **Enterprise Support**: +- **Community discussions**: https://github.com/orgs/owncloud/discussions +- **Matrix Chat**: +- **Documentation**: + +Please do not use GitHub issues for general support questions. diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..59b2449 --- /dev/null +++ b/agents.md @@ -0,0 +1,56 @@ +# agents.md -- protoc-gen-microweb + +## Repository Overview + +Protocol Buffers compiler plugin that generates HTTP REST handlers from protobuf service definitions. Written in Go. Licensed under Apache-2.0. + +## Architecture & Key Paths + +- `main.go` -- Plugin entry point +- `microweb.go` -- Core code generation logic +- `examples/` -- Example protobuf services and generated output +- `go.mod` / `go.sum` -- Go module definition +- `tools.go` -- Tool dependencies +- `test.sh` -- Test script + +## Development Conventions + +- Go codebase +- Protoc plugin protocol +- Chi router for generated handlers + +## Build & Test Commands + +```bash +go install # Install the plugin +bash test.sh # Run tests +``` + +## Important Constraints + +- Licensed under Apache-2.0 (already at the OSPO target license). The broader ownCloud organization is migrating other repositories from copyleft licenses to Apache 2.0. +- Used in the oCIS build pipeline for REST handler generation. +- All contributions require a DCO sign-off. + + +## OSPO Policy Constraints + +### GitHub Actions +- **Only** use actions owned by `owncloud`, created by GitHub (`actions/*`), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers. +- Pin all actions to their full commit SHA (not tags): `uses: actions/checkout@ # vX.Y.Z` +- Never introduce actions from unverified third parties. + +### Dependency Management +- Dependabot is configured for automated dependency updates. +- Review and merge Dependabot PRs as part of regular maintenance. +- Do not introduce new dependencies without discussion in an issue first. + +### Git Workflow +- **Rebase policy**: Always rebase; never create merge commits. Use `git pull --rebase` and `git rebase` before pushing. +- **Signed commits**: All commits **must** be PGP/GPG signed (`git commit -S -s`). +- **DCO sign-off**: Every commit needs a `Signed-off-by` line (`git commit -s`). +- **Conventional Commits & Squash Merge**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this. + +## Context for AI Agents + +This is a protoc plugin. It reads protobuf service definitions with gRPC HTTP annotations and generates Go code that wires up Chi router handlers with JSON serialization. The generated code bridges protobuf services to HTTP REST endpoints.