Skip to content

Latest commit

 

History

History
125 lines (84 loc) · 3.65 KB

CONTRIBUTING.md

File metadata and controls

125 lines (84 loc) · 3.65 KB
Raw

Contributing

License and Copyright Attribution

When you open a Pull Request to the project, you agree to license your code under the GNU AFFERO GENERAL PUBLIC LICENSE and to transfer the copyright on the submitted code to Kévin Dunglas.

Be sure to you have the right to do that (if you are a professional, ask your company)!

If you include code from another project, please mention it in the Pull Request description and credit the original author.

Start a Demo API and Contribute to the Caddy Plugin

Clone the project:

$ git clone https://github.com/dunglas/vulcain
$ cd vulcain

Install the dependencies:

$ go get

Run the fixture API:

# You must run the server too
$ cd ../fixtures/
$ go run main.go

Run Caddy with the Vulcain module as a reverse proxy:

$ cd caddy/
$ go run vulcain/main.go

Alternatively, to use VSCode and its integrated debugger, use this configuration in .vscode/launch.json:

{
   "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch the proxy",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}/caddy/vulcain",
            "args": ["run", "--config", "../fixtures/Caddyfile"]
        }
    ]
}

Go on http://localhost:8081 and enjoy! The API is available on https://localhost:3000.

An API using an OpenAPI mapping is available on https://localhost:3000/oa/books.json.

To run the test suite:

$ go test -v -timeout 30s github.com/dunglas/vulcain/caddy

Start a Demo API and Contribute to the Legacy Gateway Server

Clone the project:

$ git clone https://github.com/dunglas/vulcain
$ cd vulcain

Install the dependencies:

$ go get

Run the server:

$ go run cmd/vulcain/main.go

Run the fixture API:

# You must run the server too
$ cd fixtures/
$ go run main.go

Go to https://localhost:3000 and accept the self-signed certificate. Go on http://localhost:8081 and enjoy!

An API using an OpenAPI mapping is available on https://localhost:3000/oa/books.json.

To run the test suite:

$ go test -v -timeout 30s github.com/dunglas/vulcain/gateway

curl Examples

Preload all relations referenced in the hydra:member, then in the author relationship, but only include the title and the author of these relations:

$ curl https://localhost:3000/books.jsonld \
    --get \
    --data 'preload="/hydra:member/*/author"' \
    --data 'fields="/hydra:member/*/author", "/hydra:member/*/title"' \
    --verbose \
    --insecure

Using headers:

$ curl https://localhost:3000/books.jsonld \
    --get \
    --header 'Preload: "/hydra:member/*/author"' \
    --header 'Fields: "/hydra:member/*/author", "/hydra:member/*/title"' \
    --verbose \
    --insecure

Protocol

The protocol is written in Markdown, compatible with Mmark. It is then converted in the the "xml2rfc" Version 3 Vocabulary.

To contribute to the protocol itself:

  • Make your changes
  • Download Mmark
  • Download xml2rfc using pip: pip install xml2rfc
  • Format the Markdown file: mmark -markdown -w spec/vulcain.md
  • Generate the XML file: mmark spec/vulcain.md > spec/vulcain.xml
  • Validate the generated XML file and generate the text file: xml2rfc --text --v3 spec/vulcain.xml
  • Remove non-ASCII characters from the generated vulcain.txt file (example: Kévin, André, Ã�elik)
  • If appropriate, be sure to update the reference implementation accordingly