design-and-project.md

layout	page
title	Design & project
tagline

{% include JB/setup %}

Note! This page describes the general design and project-setup for Threft.io. As the project is still in it's early stages a lot of what is described here is not actually finished yet or not even in development! More information will become available gradually on subpages under /design, which will be linked from this page.

Contribute? Contributions are very welcome! Join threft-dev and/or find out how to help with development.

Design

Rather than creating new idea's and solutions: the Threft.io design borrows the best idea's from other projects such as Protobuf, Thrift and Go. For instance, even though compromises must be made to stay compatible.

IDL: Interface Definition Language

.thrift and .threft

The Threft.io parser can parse two types of files. The first is the existing Thrift IDL, with the .thrift file extension. The second is the more strict Threft.io IDL, with the .threft file extension.

Parser & Generators

The parser and generators are seperated. The parser checks and parses input files to the Threft Interface Definition Model (TIDM). The TIDM is then marshalled to tidm-json, which is simply json following a specific structure. The parser executes the generator and sends the tidm-json on stdin. The generator creates code and writes files. A generator doesn't have to be written in Go because it is separated from the parser. Anyone can create a generator for any language in any language.

Generated code and support libraries

Since everyone can create a generator, this project cannot controll the design of the generated code. Since the Go generator (threft-gen-go) is part of this project a set of design principles are defined: - Minimal runtime reflection and type assertion in generated code. - Threrefore: code for serialisation/de-serialisation is to be generated, not support library. - Support library should only complement the standard libraries with small functionality such as networking helpers.

Project

Commands

The Threft.io project consists of multiple commands.

threft

Reads .thrift files and executes a generator with tidm-json.
source

threft-gen-go

Generates Go code from given tidm-json.
source

threft-gen-html

Generates HTML documentation from given tidm-json.
source

Packages

The project commands are backed by packages.

threft/tidm

Threft Interface Definition Model. Datastructure that can be marhsalled to/from tidm-json. Also contains IDL parsing code.
source | godoc

threft-gen-go/gog

Actual Go generator code. Is being used by the threft-gen-go command.
source | godoc

threft-gen-html/htmlg

Actual HTML generator code. Is being used by the threft-gen-html command.
source | godoc