The Open Source UYou install GitKraken using the basic instructions on the website:
wget https://release.gitkraken.com/linux/gitkraken-amd64.deb
dpkg -i gitkraken-amd64.deb
It installs successfully. You start it and... nothing.
I learned that you can fix this behavior by installing: libcurl3.
sudo apt install libcurl3
The Promise object represents the eventual completion (or failure) of an asynchronous operation and its resulting value.
-MDN
Put simply1, it is a means to reorganize asynchronous (concurrently executing) code to reduce nesting among other reasons.
Over the next couple of posts, I'm going to give a brief primer on what a promise is and how to use it but the main purpose of this article is to understand how a Promise library is implemented. I was poking through the source code of Pinkie not too long ago and it seemed like a great article candidate.
Without going into too much detail, they are used to avoid "Callback Hell" as well as create a more familiar code-flow (the try/catch). pattern. Here's a contrived but pseudo real-world example:
A promise allows us to restructure the code as such as this:
There appears to be more code in the later version because, I suppose, there is. The use of a promise doesn't reduce code. It makes the flow more obvious. And I do believe that is achieved here. You now see the order of execution more clearly. Each then statement must be completed before the previous then statement and should an error occur, the catch(function(er){}) will intercede to allow you to handle the error gracefully.
Promises in JavaScript has become quite ubiquitous. Should you want to see more examples or practical uses of Promises, the pg-promise library has excellent up-to-date examples that are both clear and real-world. The library itself is a PostgreSQL interface for Node.
In the next post, we'll look at how promise libraries are implemented by dissecting the implementation by Floatdrop called Pinkie. A small ES2015 Promise implementation.
An Oversimplification but suitable for our purposes. ↩
Bit masks are a computer science concept; in a nutshell, they represent options which can be combined in a variety of ways.
A very basic example colors. Blue and Green combined create yellow. This can be represented in bit masks.
The following example is sourced from the Bit field article on Wikipedia; it illustrates the concept well for those new to it.
Consider the following1 and take note of the binary version which is in the comment.
// primary colors
#define BLUE 4 /* 100 */
#define GREEN 2 /* 010 */
#define RED 1 /* 001 */
This creates the base options. The next example uses the above to further define more colors without assigning them specific numbers, although they would output as numbers.
// mixed colors
#define BLACK 0 /* 000 */
#define YELLOW (RED | GREEN) /* 011 */
#define MAGENTA (RED | BLUE) /* 101 */
#define CYAN (GREEN | BLUE) /* 110 */
#define WHITE (RED | GREEN | BLUE) /* 111 */
Notice that WHITE is all the colors -- all the bits are "on" and black is no color -- all the bits are off.
I've seen this used quite a bit although, I must admit, I don't come across it quite as often as I used to. Rest assured, it is still in use and is quite useful.
The code presented is Pseudocode. It is not intended to be complete. ↩
Bouncy is a tool to "pipe raw http traffic from [an] incoming http request to a another remote end point."
It's an interesting tool and, for me, a useful find. Not to reveal too much but this site is running on Node among other technologies.
I think this tool has a lot of possible applications1 but for me, it acts as a virtual host router. I don't want to go into too much detail here (you can see here for more info) but in my scenario, I wanted to setup my server so that I could host another site on the same server if needed or desired.
Bouncy allows me to do that; using bouncy I created a small custom program that listens on port 80 (the website port). When it accepts an incoming request it routes it to the correct site which is running on another port (on the same server) -- say 8000 for discussion.
It determines the site via the request host headers (req.headers.host).
Summary of example configuration:
It's a small library (it's available as a CLI tool as well) and I think it's an excellent candidate for a first article. I'm, frankly, curious how it works and it's small enough to sort out the structure of these posts.
For the purpose of this article, I've forked the git repository to https://github.com/TheOpenSourceU/bouncy
I'll use and reference this version in this article. Because the parent/source project could continue to be developed, I've created a branch called tOSU/explore. This will remain consistent with this article whereas master can deviate. I want to keep master consistent with the sources' master.
I'll do my best to link or explain related technologies and concepts. A principle goal of this site is to engage folks with a diverse backgrounds and experience levels.
That said, I do make some assumptions about a basic familiarity with some technology. At this time, I don't have public comments on this site but should you need to provide critical (respectful) feedback or ask questions, please feel use the GitHub issues located here.
Knowing and understanding the high-level purpose of a package/programs dependencies is helpful in understanding the parent application.
Bouncy has two main dependencies (for those unfamiliar, this is in the package.json file.
// ...
"dependencies" : {
"through": "~2.3.4",
"optimist": "~0.3.5"
},
// ...
The entry point and frankly the main implementation. Bouncy is built on top of the bog standard NodeJS http/https library and in a way, simply wraps it. Given it's relationship to http/https, Bouncy is event driven.
The correct server type is created (secure or not); then three events are assigned handlers. The first is the connection or secureConnection event which is handled by an anonymous function which we'll call the "connection event handler". The other two events are upgrade and request which are both assigned onrequest.
This accepts the parameter stream. This represents the network stream of data coming in for the request. The handler adds a property called _bouncyStream which is the results of stealthBuffer().
The next snippet is the nuts and bolts of the handler.
var src = stream._bouncyStream = stealthBuffer();
// ... old version work around ...
else stream.pipe(src);
At this point, stream is an instance of Socket and src is an instance of Stream. (Notice that despite the name, stream is not Stream -- that capital "S" is important.)
The src (Stream) is piped (sent) to the Socket. This completes the set up of the connection. Now, bouncy will wait for incoming requests and through onrequest, route them.
onrequestThis is the main purpose of Bouncy. This ultimately bounces the request to another port via the cb parameter as this is the user implemented code provided as a callback.
Here's the example given on the GitHub page.
var bouncy = require('bouncy');
var server = bouncy(function (req, res, bounce) {
if (req.headers.host === 'beep.example.com') {
bounce(8001);
}
else if (req.headers.host === 'boop.example.com') {
bounce(8002);
}
else {
res.statusCode = 404;
res.end('no such host');
}
});
server.listen(8000);
The anonymous function passed into the bouncy and is called after some setup which is mainly creating the bounce method. The end user then calls bounce with the appropriate port and said method pipes the connection to the new path.
This "bounces" the request to the new port.
stealthBuffer()stealthBuffer() returns an instance of the dependency through; recall this provides the means to make a stream readable and writable.
This is ultimately used in the connection event handler. The bottom line is it augments the request for passing it through to the bounce method in the onrequest handler.
I'm wondering if Bouncy can be used to load balance the same site on two different instances of NodeJS. I strongly suspect it could and hope to test that soon... ↩
There are plenty of resources out there to learn how to use git... but I'd say a good percentage of those focus on using git from git init and on -- that is, starting a new repository from scratch.
This post is going to focus on using git to contribute to an existing, established project on github. I'm assuming no prior knowledge of git/GitKraken/SourceTree. That said, I'm going to assume you are using at least GitKraken or SourceTree and not the CLI.
I encourage you to follow along. For my screenshots, I'll be using my "pg-migration" project but you can use any GitHub project you desire. I strongly encourage you to follow along.
Open the "project" for GitHub. You want to fork the target repository. What this does is create a copy of the project to your GitHub account. This becomes your "remote working" space.
Upon clicking this, you see something like the following.
After the process, you'll be taken to the forked instance which will appear quite identical to the original. For example, the readme will be showing.
At this point, you clone the repository with git. Cloning is similar to check out used in TFS or Subversion; there is more to it but for now consider them the same thing. You want to clone your fork and not the original in order to be prepared to publish changes for a pull request later.
With GitKraken, there are several ways to close a repository but the most direct are to select File -> Clone. You'll be presented with a dialog like the following. You may use the URL option or the GitHub.com option. For simplicity, I'll show a screenshot of the URL section.
Once you've cloned you'll be on the default branch master, before doing anything you should create a branch specific to your current efforts. The common branch naming convention is:
feature/feature-name-or-idissue/issue-idhacking
Click on "branch" and enter a name for it and hit enter. If you're just doing the steps to follow along, use hacking as the branch name otherwise select accordingly. Upon creating the branch, your working copy will be set to the branch. The working copy is the source code that you can edit.
If you open the folder in Finder or Windows Explorer, you should see the source files as, well, files.
In GitKraken, the active branch has a green checkmark next to it.
You are now ready to work. You can put comments or make changes. If you want to keep the changes, commit them. When you commit in git you are only committing to your clone -- that is, the git repository on your computer. Git works by keeping a full copy of the version control repository locally. There is a complete copy on the server as well but the two are only indirectly linked -- you have to give it the push command to send the changes to the server.
Consider the git repository on your computer to be temporary. Any changes you want to truly keep should be "pushed" to Github. This makes hacking in a throwaway branch on your local repository super easy but it also means that you can lose work you want to keep. Be mindful of this and push when appropriate.
Make a few changes or add notes for yourself -- anything really -- and save the modification. Let's commit these changes. In GitKraken, the command becomes present when it detects changes to your working copy. Select the line that says // WIP and you'll see something like the following. Note that the UI changes layout depending on the size of the window.
Move your modified files to staged -- this indicates your intent to include these files in your commit -- fill in the summary and click "Commit".
The UI updates to reflect that hacking has moved forward one node from master and you'll see your notes. From here, I encourage you to explore the UI of GitKraken or SourceTree.
Once you are ready, I encourage you to push your changes to the repository on GitHub. Remember that you forked the project and so:
Click the push button in the toolbar and you'll be presented with the following dialog. Simply click Submit.
This dialog is indicating you're going to send this to the remote called origin (automatically assigned to the clone source) / branch hacking.
On the GitHub side of things, you'll see the following:
Should you want the author of the source project to include your changes in the main project (and assuming you've followed the project's contributing documentation), you can issue a pull request.
For now, that is the basic usage of git to collaborate on an existing project. There are other things you need to be aware of such as merging and overall branch management but I'll be covering those in future articles. For now, this should get you started.
Enjoy hacking.
I've invented this. It's a convention I use to avoid contaminating master. ↩